Introduction

Adding files to a Git repository really means staging content for the next commit. git add does not push anything to a remote and it does not create the commit by itself. Once you understand the working tree, staging area, and commit flow, the command becomes much easier to use correctly.

Understand the Working Tree and Staging Area

Git has an extra layer between your files and your commit history: the index, usually called the staging area. When you edit a file, the change exists only in the working tree until you stage it.

git status
git add app.py
git status

After git add app.py, the current contents of app.py move into the staging area. They are not committed yet. They are only prepared for the next commit.

That distinction matters because you can keep editing the file after staging it. Git will then show both staged and unstaged changes for the same file.

Add New Files and Modified Files

The same git add command handles both new files and already tracked files.

1touch README.md
2git add README.md
3
4echo "print('hello')" > app.py
5git add app.py

If the file was untracked, Git starts tracking it. If it was already tracked, Git stages the new content. There is no separate “add new file” versus “update existing file” command.

Choose the Right Form of git add

Specific paths are the safest form.

git add src/main.py
git add docs/README.md

You can also add broader scopes:

git add .
git add -A
git add -u

These variants are different:

• 'git add . stages changes below the current directory'
• 'git add -A stages additions, modifications, and deletions across the repository'
• 'git add -u stages modifications and deletions for already tracked files'

That difference becomes important when files were deleted or when you are working from a subdirectory instead of the repository root.

Use Patch Mode for Clean Commits

One of Git’s best features is patch mode.

git add -p

This lets you stage selected hunks instead of entire files. It is ideal when one file contains both a bug fix and unrelated cleanup. Staging by hunk keeps commits focused and easier to review.

A good workflow is:

1git status
2git add -p
3git diff --cached
4git commit -m "Fix user signup validation"

git diff --cached shows exactly what will go into the next commit.

Use .gitignore for Files That Should Never Be Added

Not everything in the working directory belongs in the repository. Build artifacts, local secrets, dependency folders, and logs usually belong in .gitignore.

1node_modules/
2.env
3dist/
4*.log

.gitignore stops new matching files from being staged accidentally. It does not automatically untrack files that were already committed earlier, so that distinction matters too.

Undo a Staging Mistake Without Losing Work

If you staged the wrong file, remove it from the index while keeping the local edits.

git restore --staged app.py

Older tutorials often show git reset HEAD app.py. That still works, but git restore --staged is clearer because it describes exactly what is happening.

Common Pitfalls

• Thinking git add commits the file instead of merely staging it.
• Using git add . from a subdirectory and assuming the whole repository is staged.
• Forgetting that a file edited again after staging now has both staged and unstaged changes.
• Committing generated files, secrets, or local environment data because .gitignore was missing or incomplete.
• Avoiding git add -p and ending up with noisy mixed-purpose commits.

Summary

• 'git add stages content for the next commit; it does not create the commit itself.'
• The same command stages both new files and modified tracked files.
• 'git add -A, git add ., and git add -u behave differently, especially around deletions and current directory scope.'
• Patch mode is the best tool for precise, reviewable commits.
• Use .gitignore and git diff --cached to keep the repository history clean.