Appearance
Making Changes: The Edit-Stage-Commit Cycle
You have a Git repository. You want to change a file. Git does not track your work automatically. You tell Git what to save and when. This guide walks through that cycle.
The three-step workflow
Every change you make goes through three states:
| State | What it means | Where it lives |
|---|---|---|
| Working directory | You edited a file. Git sees the change but has not recorded it. | Your filesystem |
| Staging area (index) | You marked the change for the next commit. Git has a snapshot of it. | .git/index |
| Committed | Git saved the change permanently in the object database. | .git/objects |
You move a change through these states with three commands:
edit -> git add -> git commitStep by step
1. Check what Git sees
Before making changes, look at the current state:
bash
git statusOutput for a clean repository:
On branch main
nothing to commit, working tree clean2. Edit a file
Open hello.txt in any text editor. Add a line:
Hello, world!
This is my first change.Save the file.
3. See what changed
bash
git statusOn branch main
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: hello.txtGit sees the file changed. The change is in the working directory, not staged.
4. Stage the change
bash
git add hello.txtNow check status again:
bash
git statusOn branch main
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
modified: hello.txtThe change moved from "not staged" to "staged". Git has a copy of the new version ready to commit.
5. Commit the change
bash
git commit -m "Add second line to hello.txt"[main a1b2c3d] Add second line to hello.txt
1 file changed, 1 insertion(+), 1 deletion(-)Git recorded the change permanently. The commit message describes what you did.
What happens to the files
Before and after each command:
Working directory:
hello.txt: "Hello, world!\nThis is my first change.\n"
After git add:
Staging area now matches the working directory.
hello.txt on disk is unchanged.
After git commit:
A new commit object exists in .git/objects.
The branch pointer moved forward.
hello.txt on disk is still there, unchanged.The files on disk never move or disappear. Git only copies snapshots into its database.
What's happening here
When you run git add, Git reads the file, hashes its content, stores a blob in .git/objects, and writes an entry in the index (.git/index). The index is a binary file that maps filenames to blob hashes.
When you run git commit, Git builds a tree object from the index, creates a commit object that points to that tree, and updates the current branch ref to point to the new commit.
Common mistakes
| Mistake | What happens | How to fix |
|---|---|---|
| Editing but not staging | Git tracks nothing. Changes are lost on checkout or reset. | Run git add before git commit. |
| Staging but not committing | Changes are safe in the index but not recorded as a commit. | Run git commit. |
| Staging a file then editing it again | The staged version is the old one. The new edit is unstaged. | Run git add again to stage the latest version. |
Committing without -m | Git opens your default editor. If you close without saving, the commit is aborted. | Write a message and save. |
git add . from the wrong directory | Stages everything in the current directory and below. | Check git status first. Use git add <file> for precise staging. |
Key commands reference
| Command | What it does |
|---|---|
git status | Show which files are changed, staged, or untracked. |
git add <file> | Stage a file for commit. |
git add . | Stage all changes in the current directory. |
git commit -m "msg" | Commit staged changes with a message. |
git restore <file> | Discard unstaged changes in the working directory. |
git restore --staged <file> | Unstage a file without losing changes. |
git diff | Show unstaged changes. |
git diff --staged | Show staged changes. |