Tracking, adding and committing changes
git status
shows the status of a repository.
- 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 add
puts files in the staging area.
git commit
saves the staged content as a new commit in the local repository.
- Write a commit message that accurately describes your changes.
First let’s make sure we’re still in the right directory. You should be in the recipes directory.
cd ~/Desktop/recipes
Let’s create a file called guacamole.qmd
that contains the basic structure of our first recipe. We’ll use nano to edit the file; you can use whatever editor you like. In particular, this does not have to be the core.editor you set globally earlier. But remember, the steps to create or edit a new file will depend on the editor you choose (it might not be nano). For a refresher on text editors, check out “Which Editor?” in The Carpentries Unix Shell lesson.
nano guacamole.qmd
Put some text in your guacamole.qmd
file, for example:
(I am leaving instructions blank here to add in an example later of file modification)
# Guacamole recipe
## Ingredients
- Avocado
- Coriander
- Red onion
- Lemon juice
- Salt
## Instructions
Verify that the file was made, using ls
and cat
commands to explore the file.
If we check the status of our project again, Git tells us that it’s noticed the new file:
git status
On branch main
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
guacamole.qmd
nothing added to commit but untracked files present (use "git add" to track)
The “untracked files” message means that there’s a file in the directory that Git isn’t keeping track of. We can tell Git to track a file using git add
:
git add guacamole.qmd
and then check that the right thing happened:
git status
On branch main
No commits yet
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: guacamole.qmd
Git now knows that it’s supposed to keep track of guacamole.qmd, but it hasn’t recorded these changes as a commit yet. The file is in what is called the ‘staging area’.
If you think of Git as taking snapshots of changes over the life of a project, git add
specifies what will go in a snapshot (putting things in the staging area), and git commit
then actually takes the snapshot, and makes a permanent record of it (as a commit). If you don’t have anything staged when you type git commit
, Git will prompt you to use git commit -a
or git commit --all
, which is kind of like gathering everyone to take a group photo! However, it’s almost always better to explicitly add things to the staging area, because you might commit changes you forgot you made. (Going back to the group photo simile, you might get an extra with incomplete makeup walking on the stage for the picture because you used -a
!) Try to stage things manually, or you might find yourself searching for “git undo commit” more than you would like!
To get it to commit the staged files, we need to run one more command:
git commit -m "Create initial structure for a Guacamole recipe"
When we run git commit
, Git takes everything we have told it to save by using git add
and stores a copy permanently inside the special .git
directory. This permanent copy is called a commit (or revision) and its short identifier is f22b25e. Your commit may have another identifier.
We use the -m
flag (for “message”) to record a short, descriptive, and specific comment that will help us remember later on what we did and why. 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.
Good commit messages start with a brief (<50 characters) statement about the changes made in the commit. Generally, the message should complete the sentence “If applied, this commit will” . If you want to go into more detail, add a blank line between the summary line and your additional notes. Use this additional space to explain why you made changes and/or what their impact will be.
If we run git status
now:
git status
On branch main
nothing to commit, working tree clean
it tells us everything is up to date. If we want to know what we’ve done recently, we can ask Git to show us the project’s history using git log
, it will list all commits made to a repository in reverse chronological order. The listing for each commit includes the commit’s full identifier (which starts with the same characters as the short identifier printed by the git commit command earlier), the commit’s author, when it was created, and the log message Git was given when the commit was created.
Now suppose we add more information to the file. (Again, we’ll edit with nano
and then cat
the file to show its contents; you may use a different editor, and don’t need to cat
)
nano guacamole.qmd
Add some text (here I have now added instructions):
# Guacamole recipe
## Ingredients
- Avocado
- Coriander
- Red onion
- Lemon juice
- Salt
## Instructions
1. Mash the avocado
2. Finely chop the coriander and red onion
3. Add salt and lemon juice to taste
4. Enjoy!
When we run git status
now, it tells us that a file it already knows about has been modified:
git status
On branch main
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: guacamole.qmd
no changes added to commit (use "git add" and/or "git commit -a")
The last line is the key phrase: “no changes added to commit”. We have changed this file, but we haven’t told Git we will want to save those changes (which we do with git add
) nor have we saved them (which we do with git commit
). So let’s do that now.
git diff
It is good practice to always review our changes before saving them. We do this using git diff
. This shows us the differences between the current state of the file and the most recently saved version:
git diff
diff --git a/guacamole.qmd b/guacamole.qmd
index ad0d963..6249f4c 100644
--- a/guacamole.qmd
+++ b/guacamole.qmd
@@ -8,3 +8,7 @@
- Salt
## Instructions
+1. Mash the avocado
+2. Finely chop the coriander and red onion
+3. Add salt and lemon juice to taste
+4. Enjoy!
The output is cryptic because it is actually a series of commands for tools like editors and patch telling them how to reconstruct one file given the other. If we break it down into pieces:
- The first line tells us that Git is producing output similar to the Unix diff command comparing the old and new versions of the file.
- The second line tells exactly which versions of the file Git is comparing; ad0d963 and 6249f4c are unique computer-generated labels for those versions.
- The third and fourth lines once again show the name of the file being changed.
- The remaining lines are the most interesting, they show us the actual differences and the lines on which they occur. In particular, the + marker in the first column shows where we added a line.
It’s time to commit the modified version. Except remember, we need to git add
the file again first:
git add guacamole.qmd
git commit -m "Add instructions for basic guacamole"
[main 8a8041c] Add instructions for basic guacamole
1 file changed, 4 insertions(+)
Git insists that we add files to the set we want to commit before actually committing anything. This allows us to commit our changes in stages and capture changes in logical portions rather than only large batches. For example, suppose we’re adding a few citations to relevant research to our thesis. We might want to commit those additions, and the corresponding bibliography entries, but not commit some of our work drafting the conclusion (which we haven’t finished yet).
To allow for this, Git has a special staging area where it keeps track of things that have been added to the current changeset but not yet committed.
Other options for adding files
We can also add multiple files at once to the staging area, by specifiying all the files in one command:
git add guacamole.qmd groceries.qmd
Or, by using git add .
to add all files (new, modified, deleted files) in the current directory and subdirectories to the staging area:
git add .
Or, by using git add -A
to add all files (new, modified, deleted files) in the entire repository to the staging area:
git add -A
Don’t forget to then commit
your staged changes!