Tracking Changes

Overview

Teaching: 20 min
Exercises: 0 min

Questions

• How do I record changes in Git?

• How do I check the status of my version control repository?

• How do I record notes about what changes I made and why?

Objectives

• Go through the modify-add-commit cycle for one or more files.

• Explain where information is stored at each stage of Git commit workflow.

You should now have a hello-world repository on your desktop.

Let’s create a file and add it to the repository.

CLI Steps

https://swcarpentry.github.io/git-novice/04-changes/

This is a two-stage process. First, we add any files for which we want to save the changes to a staging area, then we commit those changes to the repository. This two-stage process gives us fine-grained control over what should and should not be included in a particular commit.

Let’s create a new file using the touch command, which is a quick way to create an empty file.

$ touch index.md

The .md extension above signifies that we have chosen to use the Markdown format, a lightweight markup language with plain text formatting syntax. We will explore Markdown a bit later.

Let’s check the status of our project.

$ git status

On branch master
No commits yet
Untracked files:
  (use "git add <file>..." to include in what will be committed)

    index.md

nothing added to commit but untracked files present (use "git add" to track)

This status is telling us that git has noticed a new file in our directory that we are not yet tracking. With colorised output, the filename will appear in red. To change this, and to tell Git we want to track any changes we make to index.md, we use git add.

$ git add index.md

This adds our Markdown file to the staging area (the area where git checks for file changes). To confirm this we want to use git status again.

$ git status

On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

    new file:   index.md

If we are using colorised output, we will see that the filename has changed color (from red to green). Git also tells us that there is a new file to be committed, but, before we do that, let’s add some text to the file.

We will edit the file index.md with the nano text editor on the command line.

$ nano index.md

Type # Hello, world! into the file. Then press Control-O to save and then Control-X to exit nano.

Now, let’s check if Git has spotted the changes.

$ git status

On branch master

No commits yet

Changes to be committed:
 (use "git rm --cached <file>..." to unstage)

 new file:   index.md

Changes not staged for commit:
 (use "git add <file>..." to update what will be committed)
 (use "git checkout -- <file>..." to discard changes in working directory)

 modified:   index.md

This lets us know that git has indeed spotted the changes to our file, but that it hasn’t yet staged them, so let’s add the new version of the file to the staging area.

$ git add index.md

Open a plain text editor (typically Notepad on Windows or TextEdit on macOS) and save an empty file named index.md in the hello-world directory.

You’ll see that GitHub Desktop has changed to signify that a new file has been added. The left hand panel, which shows changes that have occurred in the repository, lists the new file. It knows this is a new file that it will have to add to the repository, as indicated by the green plus sign.

Edit the file again and add the text # Hello, world! on the first line. Save the file and then check that contents of the file appear in green in the right hand panel of Git Desktop, showing the lines that have changed.

To finalize saving this version of the file in the repository we need to write a commit message that describes our changes and commit the changes.

CLI Steps

Now we are ready to commit our first changes. Commit is similar to ‘saving’ a file to Git. However, compared to saving, a commit provides a lot more information about the changes we have made, and this information will remain visible to us later.

$ git commit -m 'Add index.md'

[master (root-commit) e9e8fd3] Add index.md
 1 file changed, 1 insertion(+)
 create mode 100644 index.md

We can see that one file has changed and that we made one insertion, which was a line with the text ‘# Hello, world!’. We can also see the commit message ‘Add index.md’, which we added by using the -m flag after git commit. The commit message is used to record a short, descriptive, and specific summary of what we did to help us remember later on without having to look at the actual changes. If we just run git commit without the -m option, Git will launch nano (or whatever other editor we configured as core.editor) so that we can write a longer message.

Having made a commit, we now have a permanent record of what was changed, along with metadata about who made the commit and at what time.

You can provide both a short summary of the changes and a longer description by typing in the lower left hand corner of GitHub Desktop. Then click Commit to master.

When we commit our changes, Git takes everything we have told it to save and stores a copy permanently inside the special .git directory. This permanent copy is called a commit (or revision) and is assigned a identifier.

If you click the History tab you’ll see a record of the changes you have made.
The “Initial commit’ was generated automatically when you requested a README file to be added to the repository, and at the top you’ll see the commit we made with the summary “Initial file”. More details are listed on the right hand side, including the description and a short version identifier for the commit (288e33a in the example - yours will be different).

Where Are My Changes?

If we look in our directory at this point, we will still see just the files README.md and index.md. That’s because Git saves information about files’ history in the special .git directory mentioned earlier so that our filesystem doesn’t become cluttered (and so that we can’t accidentally edit or delete an old version).

Now, open up your text editor and change the first line in index.md to # Hello, world, Hello!. Save the modified file

When we switch back to GitHub Desktop, we see that something has happened in Changes tab. index.md appears in the left hand panel with a yellow icon, which signifies that this file has been changed. In the right hand panel we can see the new index.md header, shown in green, has been addeed. It also shows that the old header without the extra Hello, shown in red, has been removed.
If we write a commit message these changes will be saved in our history.

When we look at the history tab, we can see our new commit in the list. It’s got a completely different identifier. Note that git only saves the history of changes, as opposed to multiple copies of files. This is why git works well for text files and code, but not so well for images and binary files.

Directories

Two important facts you should know about directories in Git.

1. Git does not track directories on their own, only files within them. Try adding a folder to survey_data.

Note, our newly created empty directory directory does not appear in the changes tab of GitHub Desktop. This is the reason why you will sometimes see .gitkeep files in otherwise empty directories. Unlike .gitignore, these files are not special and their sole purpose is to populate a directory so that Git adds it to the repository. In fact, you can name such files anything you like.

Choosing a Commit Message

In this moment you have the opportunity to communicate with the future ;-) The commit messages does need to repeat the obvious like “add”, “remove”, “change”, and what exactly it was.

What would you say to a colleague who is looking over your shoulder to explain what you did? Come up with other commit messages that explain why!

Solution

For example:

• “Explain missing data”
• “Avoid overlooking missing data in calculations”

Version-controlling images

All Git tools are optimised for text files and show changes line-by-line. GitHub Desktop and a few others can additionally show changes in image files like .jpg, .png, etc. Let’s try it with the two screenshot in this episode!

1. Right-click the 1st screenshot (new file)
2. Download/save it into your repository folder, and commit it.
3. How do you now need to treat the 2nd screenshot (commit) to make GitHub Desktop compare it to the former?

Solution

You’ll want to save the 2nd image in your repository folder with the same name as the 1st. This will overwrite the 1st image in your file system, but once you commit the 2nd image you have both images available in the git history.

Key Points

• Files can be stored in a project’s working directory (which users see), the staging area (where the next commit is being built up) and the local repository (where commits are permanently recorded).

• Always write a log message when committing changes.