git-add

Add a file to the index

$ git add [path/to/file]

$ git add [[-A|--all]]

$ git add .

$ git add [[-u|--update]]

$ git add [[-f|--force]]

$ git add [[-p|--patch]]

$ git add [[-p|--patch]] [path/to/file]

$ git add [[-i|--interactive]]

git add [] [--] [...]
git add -A
git add -u
git add -p

<pathspec>...
    Specifies files or directories whose changes should be staged. If omitted, git add typically acts on the current directory and its subdirectories, similar to git add .

-A, --all
    Stages all changes (new, modified, and deleted files) across the entire working tree, regardless of the current directory.

-u, --update
    Stages changes only for files that are already tracked by Git. This includes modifications and deletions but excludes new, untracked files.

-p, --patch
    Enters interactive patch mode, allowing you to review and selectively stage individual hunks (blocks of changes) within files. This is useful for splitting a single file's modifications into multiple commits.

-i, --interactive
    Starts an interactive shell where you can choose various options like staging, unstaging, or seeing status of files.

-f, --force
    Allows adding files that are ignored by .gitignore, or files that would otherwise be rejected for being outside the current Git repository.

-n, --dry-run
    Shows what would be added without actually performing the staging operation.

-v, --verbose
    Be verbose, reporting files as they are added.

The git add command is fundamental to Git's workflow, responsible for moving changes from the working directory into the staging area (also known as the index). This intermediate step allows developers to prepare a specific set of changes for the subsequent commit.

When you modify, create, or delete files in your working directory, Git initially considers these changes untracked or unstaged. git add brings these changes into the staging area, creating a snapshot of what will be included in the next commit. This enables granular control, allowing users to craft focused and atomic commits by selecting only relevant changes, even if multiple modifications have been made across various files.

Common usage involves adding individual files (e.g., git add file.txt), an entire directory, or all changes in the repository (e.g., git add . or git add -A). Without explicitly running git add, your modifications will not be part of the next git commit, remaining in the working directory as unstaged changes. This command empowers precise control over the commit history.

git add only stages changes; it does not save them permanently to the repository. A subsequent git commit command is required to record the staged changes.

If you stage a file and then make further modifications to it, those new modifications are not staged. You must run git add again to stage the very latest version.

Using git add . or git add -A can inadvertently stage unwanted files (e.g., build artifacts, temporary files) if they are not properly listed in a .gitignore file.

The staging area, or index, is a crucial intermediate layer between your working directory and your Git repository. git add populates this area, allowing you to prepare a snapshot of your project's state. This separation enables developers to make numerous changes in their working directory, but only commit specific, related modifications, fostering cleaner and more manageable commit histories.

While git rm is commonly used to remove files from both the working directory and the index, git add -u or git add -A can also stage the deletion of files you've manually removed from your working directory. Git detects the absence of a tracked file and stages its removal, ready for the next commit.

The concept of a staging area or index is a cornerstone of Git's design, introduced by Linus Torvalds with the initial release of Git in 2005. git add has been integral to this design from the beginning, allowing developers to carefully curate the content of each commit. Features like interactive patch mode (-p) were added later to enhance this control, making git add a continuously evolving and powerful tool within the Git ecosystem.

git commit(1), git status(1), git reset(1), git rm(1), git mv(1)