13 Working with files on GitHub
13.1 Learning objectives
The learning objectives of this session are to:
- Navigate GitHub to create, upload, rename, and edit files and folders.
- Use good naming practices for files and folders.
- Use the GitHub history page to explore and find previous changes made to your files.
13.2 📖 Reading task: Naming of files and folders
Emphasise mainly not to use spaces in file names and why, not to use special characters and why, and to remember file extensions and why.
You can show an example of why spaces aren’t good by going to your browser and typing in a URL with a space in it, e.g., google.com/ search.
Time: ~5 minutes.
Before we start adding files and folders to our repositories, let’s take a moment to talk about good naming practices for files and folders.
When working with files and folders in a repository—and in general—it’s important to think about how you name them. Good naming practices can help you and others understand the content of a file or folder and make it easier to find what you are looking for.
Avoiding certain characters can also help prevent issues when working with files across different operating systems (like Windows, Mac, and Linux).
Here are some tips for good naming practices:
- Use descriptive names: Choose names that describe the content of the file or folder. For example, instead of naming a file
file1.md, name itdata-analysis-results.md. - Use lowercase letters: Filenames are case-sensitive on some operating systems, so it is a good practice to always use lowercase letters when naming files and folders to avoid confusion.
- Use hyphens or underscores: If you need to separate words in a filename, use hyphens (
-) or underscores (_) instead of spaces. For example, instead ofdata analysis results.md, name your filedata-analysis-results.mdordata_analysis_results.md. Spaces can introduce issues in some situations and contexts. So, it’s best to avoid them altogether. - Avoid special characters: Some special characters, such as
&,?,#, and the Danishæ,ø,å, can cause issues in filenames, so it’s best to avoid using them. If you work in Danish and have a file name withæ,ø, orå, you can use the non-Danish equivalents (ae,oe, andaa) instead. - Use file extensions: Remember to include file extensions in your file names to indicate the type of file. For example, use
.mdfor Markdown files (soup.md), and.csvfor CSV files (budget.csv).
13.3 Add a soup recipe
Go through this slowly, stay on the same page and type out the recipe below, don’t copy and paste.
Now, it’s time to create the first file on GitHub. Let’s add a soup recipe together! 🥣.
In the “Code” tab of the repository, we’ll click the button saying “Add file” in the top-right side of the page. In the dropdown menu, we’ll click “Create new file”.
This leads us to a new page with an empty, unnamed file.
In the “Name your file…” field, in the top-left side of the page, we’ll type the name of our file. Let’s follow the good naming practices we’ve read about above and call it soup.md.
For the content of the file, we’ll write out the following text:
Ingredients:
- Tomato
- Onion
- Oil
- WaterOnce we have added the file name and the recipe itself, let’s save the changes. Click the “Commit changes…” button in the top-right corner of the page to open the commit message pop-up. This pop-up is where we will add the commit message to describe the changes we’ve made.
You might have noticed that GitHub automatically creates a commit message for you. It’s good practice to edit it to be more descriptive, as it helps you and others understand the changes that were made to the repository. Otherwise, you might end up with a commit history that is “Update file”, “Update file”, “Update file”, etc. 😬 We’ll use a descriptive message for these changes by writing “Add soup recipe md file”.
We usually don’t need to add an extended description of the changes, so we can leave it empty here. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up.
We’ve now added our first recipe to the repository! 🎉 Now, you’ll practice creating files in your repository by adding another recipe.
13.5 Edit the content of a file
Adding a file is great, but most of the time we’ll be editing existing files. Let’s change the first line of the soup.md file.
Click the soup.md file in the “Code” tab of the repository to open it. Before continuing to edit, let’s walk through this slightly new page that we’ve gone into after clicking the file. We now see a new sidebar on the left side of the screen. This sidebar shows the file tree of the repository. The file we are currently editing should be highlighted. As you add files and folders, this file tree will grow and show them. Use it to help you navigate the repository. You can even use the search bar at the top of the sidebar to search for specific files and folders in the repository.
Alright, now to edit, click the pencil icon 
on the top-right side of the page. Let’s revise the first line of the file to be “Ingredients for tomato soup:”. When we’ve made the changes, we’ll commit them. Click the “Commit changes…” button in the top-right corner of the page to open the commit message pop-up. A descriptive commit message for these changes could be “Specify that ingredients are for a tomato soup”. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up.
13.6 Rename and move the soup recipe to a new folder
Moving and renaming files are other common tasks. Let’s imagine that we want to add more recipes to the repository in the future. To keep things organised, we want our recipes to have descriptive names. We also want to create some folders to group similar recipes together.
Rename soup.md to tomato-soup.md
Let’s start by renaming the soup.md file. We’ll go to the soup.md file in the repository by clicking on it in the “Code” tab. To rename files or move them, we have to “edit” them like we did above. So we’ll click the pencil icon on the top-right side of the page to edit the file.
On the top-left side of the page, we’ll see the name of the file. Let’s click on the name and rename the file to tomato-soup.md. Remember to keep the .md file extension.
Once we have renamed the file, let’s commit the changes. Click the “Commit changes…” button in the top-right corner of the page to open the commit message pop-up. Write a descriptive commit message for this change, e.g., “Rename soup.md to tomato-soup.md”. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up.
Move tomato-soup.md to a new soups/ folder
Next, let’s move the tomato-soup.md file to a new soups/ folder. As before, we’ll click the tomato-soup.md file to open it and click the pencil icon on the top-right side of the page.
Now, let’s change the path of the file to a new folder in the repository, by adding soups/ before the file name like so: soups/tomato-soup.md. Remember to use / between the folder name and the file name.
This will create a new folder in your recipes repository called soups/ and then move the tomato-soup.md file into it. Notice that once we add the slash / after the folder name, GitHub moves the cursor to the end of the file path, to the file name. This might make it seem like we can’t go back to the folder name and correct it if we make a typo or want to change it. But we can still change it! If we make a mistake in the folder name, we can fix it by using the backspace key to remove the /, moving the cursor back to the folder name. Now, we can change the folder name as we like 🥳
Click the “Commit changes…” button in the top-right corner of the page to open the commit message pop-up. Write a descriptive message for these changes like “Move tomato soup recipe into a new soups folder”. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up.
We’ve now moved the file! You can see the new folder soups/ in the Code tab of your repository and even click on it to see the tomato-soup.md file. 🥣 🍅
It is possible to edit, rename, and move files in the same step if you want to. For this workshop, we’ve split these changes into separate steps to highlight how to do each.
13.7 🧑💻 Exercise: Edit, rename, and move the cookies.md file
Time: ~5 minutes
Just like we did with the soup recipe above, let’s edit and rename the cookies.md file so the content and name is more specific. Let’s also move it to a new baked-goods/ folder. That way, if you want to add other recipes for baked goods, you can put it in that folder.
While you can do these changes in one step, for practice, rename the file first, then edit the content, and last move it to the new folder.
Start by editing the cookies.md file by changing the first line:
- Click the pencil icon on top-right side of the page (“Edit this file”) to edit the file.
- Edit the first line of the file by adding that it is ingredients for chocolate chip cookies, so it becomes “Ingredients for chocolate chip cookies:”.
- Click the “Commit changes…” button in the top-right corner of the page to open the commit message pop-up. In the message section, briefly describe the change. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up. Here, a descriptive message could be “Edit heading to specify that this is a chocolate chip cookie recipe”.
Then, rename the cookies.md file:
- Click the pencil icon on the top-right side of the page (“Edit this file”) to edit the
cookies.mdfile. - Click the name of the file at the top-left of the page and rename the file to
chocolate-chip-cookies.md. Remember to not use spaces in the file name and to keep the file extension (.md). - Click the “Commit changes…” button in the top-right corner of the page to open the commit message pop-up. In the message section, briefly describe the change. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up. Here, a descriptive message could be “Rename cookie recipe to chocolate chip cookies”.
Next, move the file to a new baked-goods/ folder:
- Click the pencil icon on the top-right side of the page (“Edit this file”) as we did before on the
chocolate-chip-cookies.mdfile. - Click the name of the file at the top-left of the page and change the path of the file to a new folder in your repository. The current file path is
chocolate-chip-cookies.md. To create a new folder, change the file path by typingbaked-goods/at the beginning of the file name, so the path becomesbaked-goods/chocolate-chip-cookies.md. Notice the/between the folder name and the file name. - Click the “Commit changes…” button in the top-right corner of the page to open the commit message pop-up. In the message section, briefly describe the change. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up. Here, a descriptive message could be “Move cookie recipe to baked-goods folder”.
You have now edited and renamed your cookies recipe file and moved it to a new folder in your repository! 🥳
13.8 Upload files to a GitHub repository
Briefly go through the process of uploading files to a GitHub repository, showing the actual uploading process.
Make sure to mention that this is not a type-along. The learnes will find an image to upload and upload it the upcoming exercise.
Until now, we’ve been adding files and folders to the repository by creating them directly on GitHub. This is a great way to add files and folders when we want to create new content or edit existing content directly on GitHub. But, what if we have files on our computer that we want to add to the repository? Then, we need to upload them.
Uploading files to a GitHub repository is a bit different from adding files and folders. When we upload files, we can select files from our computer and upload them directly to the repository.
To upload files to a GitHub repository, we’ll go to the “Code” tab of the repository and click the “Add file” button on the top-right side of the page. In the dropdown menu, we’ll click “Upload files”. This leads us to a new page where we can drag and drop files from our computer or click the “choose your files” button to select files from our computer. Once we’ve selected the files we want to upload, we can add a commit message and commit the changes. This will upload the files to the repository and create a new commit with the changes.
13.9 🧑💻 Exercise: Upload a file to your repository
Time: ~5 minutes.
Now, it’s your turn to upload a file to your repository. Find an image of a cookie or recipe book from Pixabay (or similar website), download it to your computer, and then upload the image to your repository.
Once you have decided on a file to upload and downloaded it to your computer, follow these steps:
- In the “Code” tab of your repository, click the “Add file” button and then “Upload files”.
- Drag and drop the file you want to upload into the upload area or click the “choose your files” button to select the file from your computer.
- Once you’ve selected the file, add a commit message to describe the changes as you’ve done before.
- Click the “Commit changes…” button to upload the file to your repository.
13.10 Explore the history to find previous changes
Use this text below as a guide to visually walkthrough the repository’s history.
Now that we’ve made several changes, let’s look at the repository’s history. This shows what changes were made, who made them, and when they were made. This is very useful for tracking progress or finding specific changes. On GitHub, we can see the history of the entire repository or the history of a specific file.
Because we’ve only made a few changes to the repository, let’s explore the history of the entire repository to locate the commit where we first added the cookie recipe.
In the “Code” tab of the repository, click the “
Commits” button on the top-right side of the page. This leads us to a page that shows all the changes that have been made to the repository along with the commit messages, the author of the changes, and when the changes where made. Neat!
Now, we’ll go through the list of commits to find the commit where we added the cookie recipe. The commit message should be something like “Add cookie recipe”. Notice where you can see the author of the commit and when the commit was made.
As we explore the history of the repository, it (hopefully) highlights the importance of writing meaningful commit messages. Imagine if all the commit messages were “Update file”. Then, it would be quite cumbersome to find the change we were looking for.
By contrast, if the commits have meaningful messages (like “Add cookie recipe” or “Move cookie recipe to baked-goods folder”), it is much easier to get an overview of the changes and locate the one we’re looking for.
Let’s click on the commit message to see what was changed in that commit. Take a moment to explore the information that GitHub provides about the commit. On the left side of the page, we can see which files were changed in the commit, and on the right side, we can see the specific changes that were made to the file. In the top-left corner of the page, we can still see who made the changes and when they committed these changes. We can also see that this shows us the version of the file where the heading hadn’t been changed yet. This is how we can look at what the file looked like at that point in time.
If we want to go back to the list of commits, we can use our browser to go back to the previous page. For most browsers, this can be achieved by clicking the left-facing arrow in the top-left corner of the browser.
To see what editing a line within a file looks like, we can click on the commit message where we edited the heading of the cookie recipe. This will show us the changes that were made in that commit. The edited line is shown two times: the old line (in red with a minus in front of it) and the new line (in green with a plus).
13.11 Summary
In this session, we have explored how to work with files on GitHub. In particular, we have:
- Added files and folders to a GitHub repository
- Renamed, edited, and moved files in the repository
- Uploaded a local file to the repository
- Explored the history of the repository to see the changes and locate specific changes