Understanding git-add commands

Git is a distributed revision control system, in which you can manipulate Git-repositories on your computer. It was originally developed by Linus Torvalds, the principal author of Linux.

It’s a great way to collaborate with teams who can work remotely. One of the most commonly used git command is the add command, which simply adds the updated files into the index, so that you can commit the changes into your repository.

Like other git commands, add comes with many flavors, which means by putting a different command after the git add, it would do the different thing, yet only those operations which are directly connected with “add” command. Note that git add will not add ignored files. In order to add the ignored files, you need to explicitly mention in the command line through -f (force) option.

Following are the synopsis of git add command, which you can see through git add --help or git help add.

git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--] [<pathspec>...]

Add and Add All

git add – This simple command adds a file to the commit. In order to use it, simply use git add followed by the filename that you want to add in the commit. It could be multiple files as well.

git add -A or git add --all – It adds all the updated files to the commit (excluding the files mentioned in .gitignore). It simply detects the files that have been changed recently. The status of your repository can be seen by the git status command. In addition, git commit -a will inhibit similar behavior.

git add . – It stages new and modified files in current folder and any subsequent subfolders. It does not stage any files outside of the scope of this folder.

Git Add Ignore

The git add commands with ignore in them, are more verbose commands than the shorter companions. The authors of Git like to be very verbose and very specific with commands.

git add --ignore-removal – It stages new and modified files only. Files which are removed in the working tree are not removed in the index. Use git rm <file> to remove a file from the index and working tree when used in companion with this.

git add --no-ignore-removal – This is identical as -A and --all above, and it records removal of items in the working tree. This is, if you delete a file from the terminal or explorer, this will record the action as if you used git rm <file>.

git add --ignore-errors – If there are any errors staging a file, this will ignore those errors and continue staging all successful files. One example where this may occur, is when you don’t have permissions to read some files.

git add . -A
error: open("error.txt"): Permission denied
error: unable to index file error.txt
fatal: adding files failed

Notice the fatal error, that tells us that Git failed.

git add . -A --ignore-errors
error: open("error.txt"): Permission denied
error: unable to index file error.txt

With --ignore-errors, there are still errors, but not any fatal ones.

git add --ignore-missing --dry-run <file> – This will allow the user to check if any of the given files would be ignored, no matter if they are already present in the working tree or not. Please note that this option can only be used together with --dry-run.

This option does not have any other value than to test that the .gitignore file have same rules or not.

If we are ignoring *.txt files (all text files), --ignore-missing would tell you if adding a file would be ignored or not when added with --all.

$ git add --ignore-missing --dry-run doesnotexist.asd

$ git add --ignore-missing --dry-run doesnotexist.txt
The following paths are ignored by one of your .gitignore files:
doesnotexist.txt
Use -f if you really want to add them.
fatal: no files added

Git Add -i or Git Add Interactive

git add -i or git add --interactive – This will open an interactive shell mode that lets you choose portions of a file to add to the next commit.

This will look something like this:

$ git add -i
staged unstaged path

*** Commands ***
1: status 2: update 3: revert 4: add untracked
5: patch 6: diff 7: quit 8: help

What now >

This command shows a little bit different view of the staging area. It’s almost the same as git status, but more informative. All your staged (changed in the repository) files will be listed on the left side and unstaged (not yet added changes) – on the right.

In order to use the shell mode and select a command you type a digit or the first letter of the corresponding command.

Check out the detailed git documentation for more explanations on how to use each of the commands.

Git Add -e or Git Add Edit

git add -e or git add --edit – This allows you to edit what should be committed on a per line level. The file in the working tree will not be modified, only what would be committed when you commit.

Git Add -f or Git Add Force

git add -f or git add --force – It will force the addition of ignored files. This should be used as minimum as possible.

Git Add -n or Git Add Dry Run

git add -n or git add --dry-run – This command will show a status of files, whether they exist and/or will be ignored.

Use this command if you would like to know if the file will be added or not. For example, if you have many files with same name in different subtrees that you can test your glob patterns like this: git add --dry-run --verbose-- filename.

 Git Add -N

git add -N or git add --intend-to-add – This command records only the fact that the path will be added later. No content will be actually added at this stage.

The command is useful if you don’t want to add all the content, but rather choose some chunks first. In this case you run git add -N first and then git add -p filename in order to select a patch you’d like to stage.

Git Add -p or Git Add Patch

git add -p or git add --patch -This command is a good use if you want to commit only some of the changes. For example, you could commit only 20 lines out of 100 lines that have been changed in a file. It will force git to break your changes into portions called hunks. You will then be able to stage the hunks.

git add -p filename – This command will break a content into hunks in this particular file.

When you run the command, you will see something like this:

Stage this hunk [y,n,q,a,d,/,s,e,?]?

The meaning of these options:

• y – stage this hunk
• n – don’t stage this hunk
• q – quit
• a – stage this hunk and all later hunks in the file
• d – don’t stage this hunk or any of the later hunks in the file
• / – search for a hunk according to the given regex
• s – split the current hunk into smaller hunks
• e – edit the current hunk manually
• ? – print help

It is worth to note that this command is nothing for a new file. If the file is totally new then you will need to add it first to the index with git add -N

Git Add Refresh

git add --refresh – On the opposite of it’s name, this command will only refresh the stat information in the index.

If you would like to update the index and stage its unstaged changes, but without adding unstaged files, run git update-index --again

Git Add -u or Git Add Update

git add -u or git add --update – This command will update and remove all currently tracked files in a directory. It will not add new files.

This command is a variation of git add -A command that will update, remove and add all files.

Git Add -v or Git Add Verbose

git add -v or --verbose – It will make the log more verbose, thus you will be able to see everything that might not be important for you.

Revert and undo Git Add

In order to simply revert the file that was mistakenly added by git add run:
git reset

Other commands:

git reset HEAD <file> – Undo add of a file, while preserving changes in the working tree.

git reset – Undo the stage (all adds), while preserving the local working tree.

git reset --hard – Undo everything (both adds and local uncommitted changes).

git reset --hard HEAD – Erase all change. This will not work with single files. Warning! Don’t use this command unless you know what you are doing! This command won’t only unstage files from you index, it will also completely erase all changes from your working copy!

Summing Up

Some terms used:

• ignored files – Files listed in .gitignore, which will not be added in the “index”.
• staged files – Files that have been changed in the repository, and now ready to add for the commit.
• unstaged files – Files that are not added to the index, and thus can’t be pushed into repository.

In most cases, it would be enough to use “git add -all” and “git add filename” for adding the changes to the index, as that’s the most common operation. The other commands are basically an alternative, and thus requires more attention.

git add command is arguably the building block of git commands, as that’s what you would do most of the times while working remotely on open-source projects.