Stage Changes (git add)

What Does Staging Changes Mean?

Once you have modified your files in your working directory, the next step is to stage those changes in the index to include in the next commit. You can stage changes using git add <file> command. When you stage files, roughly Git performs:

• Git creates blob object extracting the contents of <file> and stores the snapshot as Git object inside .git/objects directory.

• Git updates the index (staging area) that reflect the meaning: <file> should point this new blob for the next commit.

You can say that when you stage the file to include in the next commit, Git creates a draft for itself to reflect the next snapshot of your project.

Common Usage Patterns

Here are the common usage patterns of git add:

Adding Related Changes

Including all the files related to single feature or fix is the best way to add files in staging area where you will include multiple files all relating to single task. For example:

git add feature.py main.py README.md

Adding Source Directory

For adding source files, adding source directory seems obvious:

git add src/

Adding Single File

You can also add a single file to staging area and this is often done to include config files:

git add config.yml

Adding Whole Project Directory

Adding the whole project directory is what the most beginner do which should almost always should be ignored in any real projects. It is easy to use but it is often against the principle of including atomic changes and hence no real project should use it unless all the files are subject to one particular feature of the project:

git add .

Best Practices

While git add <file> is pretty simple and easy to use in order to stages changes, here are the few best practices and nuances you need to follow while staging files which will make your and your teammates life easier:

Stage Only Necessary Files

git add . will stage all the files and it seems easy to do it such way as you don’t have to review which files to stage for the next commit. But it is usually the bad idea. What you should do instead is include only the changes which you want to include as part of next commit. For example, if you now introduces library, then usually adding /lib directory is the good idea rahter than adding the whole project. The best approach is to take time to review your changes using git status, git diff, etc. before adding in stage area.

Atomic Changes

Add the files reflecting the particular changes in your project like feature, bug fix, etc. You should include all the files related to that feature or bug fix to maintain the atomic nature which also helps to revert changes easily when something bad happens.

Use .gitignore

.gitignore file may not be directly related to git add but it prevents the accidental add of files in staging area. For eg: if you accidently add git add .env file which includes API key, .gitignore can prevent this from happening if you have include .env in git ignore pattern.