Tracking changes

Overview

In the following, we introduce the basic Git change workflow in context of our example.

Tips for instructors

• The goal is to get the participants familar with the basic Git change workflow.
• It is important to explain the purpose of every step and, particularly, the concept of the staging area.
• Please encourage them to create focused commits and good commit messages.

Checkpoints:

• Please make sure that the participants could follow up after every commit cycle.

Quiz tips:

• Decide which channel you want to use to collect the answers from your participants.
• Read out the question and all the answers.
• Give a clear sign when the participants should give their answer.
• Explain all answers separately.

First commit cycle: Add a new file to the repository

First, we want to start collecting information about planet Mars:

• Create a new file named mars.txt:
  • touch mars.txt - Creates a new, empty file named mars.txt.
  • Edit the file mars.txt and add the following:
    • Add the following line: Cold and dry, but everything in my favorite color
    • Please make sure that you added a closing blank line at the end of the file. The blank line is important to make sure that Git properly shows the changes between different versions.
    • Please make sure that you saved the file. You can check it by running the command cat mars.txt which prints the actual file content.
  • git status - Shows the current status of the planets repository:
    • The output indicates that there is one new file (might be indicated by red colored text output).
    • This file is not yet under version control.
• Put the file under version control:
  • git add mars.txt - Adds the new file to the repository. Git tracks from now on the changes to this file.
  • git status - Indicates the changed repository status:
    • There is one new file.
    • This file has been put under version control (might be indicated by green colored text output).
    • This file is not yet committed.
• Record the changes in the version history:
  • git commit -m "Start notes on Mars as base" - Creates the first commit (the so-called root commit) which records the changes in the history of the repository.
  • git log - Displays the history of the planets repository which shows one commit including its commit ID (full SHA-1 hash), the commit author (your configured name and email address), the commit date, and the commit message (full message).
  • git status - Indicates that there are no uncommitted changes anymore.

Congratulations - You performed your first commit!

Second commit cycle: Change an existing file of the repository

Now, we want to collect further information about Mars and focus on Wolfman:

• Edit the file mars.txt and change the following:
  • Add the following line: The two moons may be a problem for Wolfman
  • Please make sure that you added a closing blank line and saved the file properly.
  • git status - Shows that the file mars.txt has been modified (might be indicated by red colored text output).
• Let us take a look at the actual changes:
  • git diff - Shows all changes in comparison to the last committed version.
  • In our case, the output indicates that we have added one new line to the file mars.txt.
• Add the changes to the repository:
  • git add mars.txt - Adds the changes to the repository and marks them for the next commit.
  • These changes are collected in the so-called staging area.
  • git status - Indicates that these changes go into the next commit (might be indicated by green colored text output).
• Record the changes in the version history:
  • git commit -m "Add concerns about effect of Mars' moons on Wolfman" - Creates the second commit which records the changes in the version history.
  • git log - Shows the second entry in the version history. The first commit is its parent commit.
  • git status - Indicates that there are no uncommitted changes anymore.

We performed the basic Git change workflow for the second time:

• Modify: First, do your changes (e.g., add new files, change / remove files already under version control).
• Add: Add the changes which should go into the next commit into the staging area.
• Commit: Record the accumulated changes of the staging area in the version history.

The Software Carpentries, CC-BY 4.0

Excurse: Writing good commit messages

• Git requires a commit message for every commit:
  • The easiest way to add a commit message is using the -m option of git commit command.
  • If you do not add a commit message directly, Git will open an editor to let you enter the commit message.
• The first commit message line represents the subject of the commit and explains what the commit is about. Good commit subjects are important because they help you and others to orientate in the version history.
• We use the following template for first commit line: When applied, this change will Add your commit subject here (e.g., When applied, this change will Discuss Mars climate issues for Dracula.
• Please see the blog post How to Write a Git Commit Message and Conventional Commits for more information about writing “good” commit messages.

Third commit cycle: Local vs. staged changes

Finally, we want to add information about the Mummy:

• Edit the file mars.txt and change the following (Modify):
  • Add the following line: But the Mummy will appreciate a lack of humidity
  • Please make sure that you added a closing blank line and saved the file properly.
• Add the changes to the repository (Add):
  • git add mars.txt - Adds the changes to the staging area.
• Let us take a look at the actual changes:
  • git diff - Indicates no changes because they have been already transferred in the staging area.
  • git diff --staged - Shows the newly added line. It shows the differences between the staging area and the last commit. You can use it to find out about the changes which are part of your next commit.
• Record the changes to the file in the version history (Commit):
  • git commit -m "Discuss concerns about Mars' climate for Mummy" - Creates the third commit which records the changes in the version history.
  • git log - Shows the third entry in the version history.
  • git log --oneline - The option --oneline provides a much more compact view of the history.
  • git status - Indicates that there are no uncommitted changes anymore.

We performed the basic Git change workflow for the third time:

• Git allows you to build your next commit in the staging area from your different modifications step-by-step.
• This approach helps you to create commits which are focused on one aspect and do not mix unrelated changes.
• If you find it hard to find a good commit message subject, you might have accumulated too many unrelated changes in one commit.

The Software Carpentries, CC-BY 4.0

Additional git add tips

• You can use git add -i or git add --interactive to add only parts of a file to the staging area. This tutorial provides a brief overview of its usage.
• You can use git add . to add multiples changes to staging area at once. But please be careful with this shortcut as you might end up accidently adding many unwanted changes such as temporary files!

Quiz time

Choosing a commit message

Which of the following commit messages would be most appropriate for the last commit made to mars.txt?

1. “Changes”
2. “Added line ‘But the Mummy will appreciate the lack of humidity’ to mars.txt”
3. “Discuss effects of Mars’ climate on the Mummy”

Answer

• Answer 1 is not descriptive enough, and the purpose of the commit is unclear.
• Answer 2 is redundant. Instead you can use git diff to see what changed in this commit.
• Answer 3 is good: short, descriptive, and imperative.

Committing changes to Git

Which command(s) below would save the changes of new-file.txt to the local Git repository?

1. git commit -m "Add recent changes"
   

2. git init new-file.txt
   git commit -m "Add recent changes"
   

3. git add new-file.txt
   git commit -m "Add recent changes"
   

4. git commit -m new-file.txt "Add recent changes"
   

Answer

• Answer 1: Would only create a commit if the changes to the file are already staged.
• Answer 2: Would try to create a new repository.
• Answer 3: Is correct. First add the file to the staging area, then commit.
• Answer 4: Would try to commit a file named “Add recent changes” with the message “new-file.txt”.

Key points

• We introduced the basic Git change workflow:
  • Modify: Change your files.
  • Add: Add the changes via git add into the staging area.
  • Commit: Record the changes of the staging area via git commit in the version history.
• 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). git status helps you to keep the overview.
• Keep your commits focused on one aspect and do not mix unrelated changes.
• Write a commit message that accurately describes your changes.