You may have used the git add command. It is one of the first commands a developer runs when
initialising a new repository, or creating a commit. You may have a vague intuition of what it does. In
this post, I will try to provide structure to this intuition by exploring some of the concepts used
by Git to make git add work.
Two states of files
Each file in your working tree can be either of these two states: tracked and untracked.
Tracked files
Files that were present in one of the previous snapshots (commits), as well as any newly created files that have been staged by you. Further, tracked files can be:
- unmodified: Files that are part of one of the previous commits, and have not been modified in the working tree.
- modified: Files that are part of one of the previous commits, but have been modified in the working tree.
- staged: Files that have been moved to the staging area.
Untracked files
Any file that is not tracked is said to be untracked, i.e., any file that is not part of a previous commit and not in your staging area.
Lifecycle of a file
When you clone a git repository, all the files are tracked. You will modify the files to make something meaningful, making them modified. Then, you can add those modified files to the staging area and commit all the files in the staging area.
Lifecycle of a file in Git. Image courtesy
How to get the current state of files in your Git repository?
You can use git status. When you run this command and see the following output, it means that
there aren’t any modified, staged or untracked files (which Git is aware of).
$ git status
On branch main
Your branch is up-to-date with 'origin/main'.
nothing to commit, working tree clean
git status gives a pretty good overview of modified files and untracked files which can be staged,
and staged files which can be committed.
Creating untracked files and tracking them
When you create a new file, you are creating an untracked file. It will be listed under the section
Untracked files when you run git status. You can use git add to track the file and add it to
the staging area.
For example, if you create a new file called untracked.json, you can track it by running:
git add untracked.json
After staging the file, it is shown under the section Changes to be committed when you run
git status.
Staging modified files
A tracked file which is modified is displayed under the section Changes not staged for commit
when you run git status.
Running git add on an already tracked, but modified, file just moves the file to the
staging area. For example, if you modified a tracked file - tracked.json, this command will add it
to the staging area:
git add tracked.json
git add acts as a multi-purpose command. It can be used to track an untracked file
as well as stage a modified file.
Modifying staged files
After staging the file tracked.json, if you make a change to the file again, then the file will be
listed under both the sections: Changes to be committed and Changes not staged for commit.
This means that when you perform a commit next time, only the changes made before staging will be committed. The version currently present in the working tree will not go into the commit. This is important to know when you are working with Git - only the changes in the staging area will go into the next commit.
If you want to stage the new changes made to tracked.json, then you can re-run:
git add tracked.json
Final thoughts
We have seen that the innocuous git add command is very versatile in its ability to handle both tracked
and untracked files. Understanding what changes will go into the next commit is essential to extract
the most out of Git.