12 Working with files on GitHub
12.1 Learning objectives
The learning objectives of this session are to:
- Navigate GitHub to create, upload, rename, edit, and delete 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.
12.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).
12.3 Add a soup recipe
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 copy and paste the following recipe:
Ingredients for soup
- 4 tbs butter
- 0.5 large onion, cut into large wedges
- 1 can of tomatoes
- 1.5 cups water, vegetable or chicken stock
- 0.5 tsp salt, or more to taste
Instructions
1. Melt the butter over medium heat in a large saucepan.
2. Add onion wedges, water, tomatoes with their juices, and salt.
3. Bring to a simmer and cook for about 40 minutes. Stir occasionally.
4. Blend the soup, and season to taste.Once 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. In the message section, briefly describe the change. No extended description is needed. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up.
A descriptive message for these changes could be “Create soup recipe md file”
You might have noticed that GitHub automatically creates a commit message for you. Remember that you can edit this message to make it more descriptive. It’s a 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’ve now added our first recipe to the repository! 🎉 Now, you’ll practice creating files in your repository by adding another recipe.
12.5 Edit, rename, and move the soup recipe to a new folder
Now, we’ll take a look at how to edit, rename, and move files in repositories on GitHub.
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 and content. We also want to create some folders to group similar recipes together.
Let’s start by doing this with the soup recipe.
Edit the content of soup.md
When we added the content of the file, you might have noticed that it said “Ingredients for soup” on the first line. This is a bit generic, so let’s change it.
Like before, we’ll click the soup.md file in the “Code” tab of the repository to open it and click the pencil icon 
on the top-right side of the page.
Now, let’s revise the first line of the file to be “Ingredients for tomato soup”. Once we’ve made the changes, let’s commit them. 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. No extended description is needed. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up.
A descriptive commit message for these changes could be “Add ‘tomato’ to the heading of the soup recipe”.
Rename 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. Then, 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. In the message section, briefly describe the change. No extended description is needed. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up.
A descriptive commit message for these changes could be “Rename soup.md to tomato-soup.md”.
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.
/
You might have noticed 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.
However, we can use the backspace key to remove the / which leads 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. In the message section, briefly describe the change. No extended description is needed. Keep the “Commit directly to the main branch” option selected. Then, click “Commit changes” at the bottom of the pop-up.
A descriptive message for these changes could be “Move tomato soup recipe into a new soups folder”.
We have now renamed the soup recipe file, edited its content, and moved it to a new folder in your repository! 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. However, for practice and clarity in the history, we’ve split these changes into separate steps.
12.6 🧑💻 Exercise: edit, rename, and move the cookies.md file
Time: ~10 minutes
Just like we did with the soup recipe above, let’s rename the cookies.md file so the 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 renaming 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. No extended description is needed. 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”.
Edit the chocolate-chip-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 “chocolate chip”, 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. No extended description is needed. 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”.
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. No extended description is needed. 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 renamed your cookies recipe file and moved it to a new folder in your repository! 🥳
12.7 Delete files and folders in a GitHub repository
Let’s imagine that we have decided that our recipe book should solely focus on recipes for sweets, desserts, and baked goods. This means that we want to remove the tomato soup recipe from the repository along with the soups/folder.
To delete the tomato-soup.md file and the soups/ folder, we’ll click the soups/ folder in the “Code” tab of the repository and then click the tomato-soup.md file within it.
In the top-right corner of the page, we’ll click the button with three dots (
), scroll down to the bottom of the dropdown menu and click “Delete file”.
We’ll save the changes by committing the changes as we have done before.
Now, when looking at the files and folders in the repository, you might notice something unexpected: When we deleted the tomato-soup.md file, GitHub automatically deleted the soups/ folder as well! This is because the folder only contained that file. GitHub automatically removes empty folders when the last file in the folder is deleted. So, we don’t need to delete the soups/ folder separately. 🔥
We have now deleted the tomato soup recipe and the soups/ folder from the repository and are ready to focus on sweets and baked goods! 🍰
If you wanted to delete a folder with multiple files in it along with the files themselves, you can go to the folder and click the three dots button () in the top-right corner of the page. Then, click “Delete directory” in the dropdown menu.
This will delete the folder and all the files within it, so be careful with deleting folders directly like this.
12.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.
12.9 🧑💻 Exercise: Upload a file to your repository
Time: ~10 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.
12.10 Explore the history to find previous changes
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.
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).
When we explore the history of the repository, it will (hopefully) highlight 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.
As mentioned above, it’s possible to both explore the history of the entire repository and the history of a specific file. The history of the entire repository shows all the commits that have been made to all files in the repository, while the history of a specific file shows the commits that have been made to that file only.
You can access the history of a specific file by going to the file in the repository and clicking the “History” button on the top-right side of the page.
It can also be useful to look at the entire repository at a specific point in time. This can be done by clicking the “Browse files” button on the top-right side of the page when you’ve clicked on a specific commit message. This will show you all files in the repository as they were at that point in time ⏰
12.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
- Deleted files and folders from the repository
- Uploaded a local file to the repository
- Explored the history of the repository to see the changes and locate specific changes