How to use the Git command git add

The git add command is a fundamental part of the Git version control system, serving as the first step in the three-stage process of making changes to your repository.

Running git add adds the target data to the “staging area”. Also referenced as the cache or index, the staging area is where files are temporarily stored before they are included as part of the next commit. This is how Git understands what's going to change between the current commit, or the HEAD, and the next commit.

This guide will explain how to use git add effectively. It will show you how to add single files, multiple files, directories, and more.

Basic use of Git add

• Adding a single file with git add: The basic syntax for adding a file to the staging area is:

  git add <file-name>

  Replace <file-name> with the name of the file you want to stage.

• Git add all files: To add all of the changes in your local working directory (including new, modified, and deleted files) to the staging area, run:

  git add .

  The period . represents the current directory. If you wish to add every change within the scope of the repo make sure you navigate to the root of the Git repository.

Additional ways to use the git add command

• Git add directory: To recursively add all files inside a directory (including all subdirectories), specify the directory path:

  git add <directory-path>

• Git add multiple files: You can stage multiple specific files at once by listing their file-paths:

  git add <file1> <file2> <file3>

• Git add all modified files: To stage all modified files without adding untracked (new) files, use:

  git add -u

Advanced Git add techniques

• Git add by glob pattern: You can use patterns to add files. For example, to add all .txt files:

  git add '*.txt'

  When using pattern matching, it’s helpful to use the --dry-run flag to see exactly which files will be staged before actually adding them.

• Git add chunks: For more control, you can add changes in chunks using:

  git add -p

  This command allows you to review your changes in small chunks across all of your different files. This is particularly useful for catching leftover scratch work like “TODOs” for example, and lets you be more intentional when adding changes to staging.

Best practices and additional information

• Understanding git add . vs git add -A: While git add . adds all changes in the current directory, git add -A adds all changes in the entire repository. Be mindful of your current directory when using these commands.

• Git add before commit: It’s best practice to always review your changes with git status before running git add to avoid staging unintended changes.

• Documentation and Help: For more detailed information on git add and its options, you can consult the use the help command:

  git add --help

  or visit the official Git documentation for further reading.

Using Graphite's CLI and the gt add command

Graphite’s CLI tool is designed to simplify complex Git operations while enabling advanced workflows such as pull request stacking. It builds on Git’s functionality with a more streamlined and developer-friendly interface, making it easier to manage both individual pull requests and stacked PRs.

Overview of the gt add command

The gt add command serves a similar purpose to Git’s git add, allowing you to stage changes to the index (or staging area). However, gt add extends this functionality with options that simplify and enhance workflows, particularly when working with stacked branches.

Here’s how gt add works in practice:

• Staging all changes with a single command: Instead of using git add ., which requires careful navigation to the desired directory, gt add can be run from any branch and integrates with Graphite’s PR stacking features. This ensures that staged changes are properly associated with the current branch.

• Interactive staging: For developers looking to add changes selectively, gt add supports chunked staging. Similar to git add -p, this feature allows you to review and stage changes incrementally.

Advantages of gt add over git add

• Consistency with stacked PR workflows: By integrating directly with the Graphite stack management model, gt add ensures that staged changes align with your branch hierarchy.
• Streamlined commands: Common flags like --all are optimized for use with the rest of the gt command suite, reducing the need for manual Git operations.
• Error reduction: Built-in safeguards, such as prompts and integrations with gt sync and gt restack, help prevent common errors like forgetting to rebase stacked branches.

For more information on Graphite’s CLI, visit the Graphite CLI documentation.