Git Basics: Commits, Branches and Merges

The three places your work lives

Git keeps your changes in three places, and most early confusion comes from not knowing which one a change is in.

1. The working directory: the files as you see and edit them.
2. The staging area (also called the index): a holding area where you collect the changes you want in the next commit.
3. The repository: the permanent history of commits.

The usual flow is to edit files, stage the changes you want to record, then commit them. Staging looks like an extra step, but it lets you decide exactly what goes into each commit.

Step 1: create or copy a repository

To start tracking a folder, run this inside it:

git init

To copy an existing project, including its full history:

git clone <address-of-repository>

Either way you end up with a folder that Git is watching. A hidden .git directory holds the history; avoid editing it by hand.

Step 2: see what has changed

git status

This lists files that are modified, files that are staged, and new files Git is not yet tracking. Get into the habit of running it often. It also hints at the next command you might want.

To see the actual edits line by line:

git diff

Without arguments, this shows changes that are not yet staged. Adding --staged shows what is staged and about to be committed.

Step 3: stage and commit

Suppose you have edited notes.txt and created plan.txt. To stage both:

git add notes.txt plan.txt

Then record the commit:

git commit -m "Add project plan and update notes"

The message after -m describes the change. Writing good ones is a skill in itself, covered by the advice on commit messages elsewhere in this cluster. For now, keep them short, specific and in the same tense each time.

Staging individual files is useful. If you changed three files but only two belong to the same idea, stage and commit those two first, then do the third separately. That keeps the history easy to follow.

To look back at what you have recorded:

git log --oneline

Each line shows a shortened identifier and the message. The identifier uniquely names that commit, so you can refer to it later.

Step 4: keep generated files out

Some files should not be tracked: compiled output, temporary files, local settings, and anything containing passwords. List patterns for these in a file named .gitignore at the top of the project, one per line, and commit that file. Git then stops offering those files for staging. This only affects files not already tracked.

Step 5: create a branch

A branch is a movable label pointing at a commit. Creating one is cheap, so use branches freely for separate pieces of work.

git switch -c add-calibration-notes

This creates a branch with that name and moves you onto it. Older guides use git checkout -b for the same purpose, and it still works. To see your branches:

git branch

The current one is marked with an asterisk. Commits you make now belong to this branch. The main branch stays where it was, so you can experiment without disturbing it. How teams decide on names and lifetimes for these branches is the subject of branching strategies.

Step 6: merge the branch back

When the work on your branch is finished, return to the branch you want to update, often called main, and merge:

git switch main
git merge add-calibration-notes

There are two common outcomes:

• Fast-forward. If main has not moved since you branched, Git simply moves the main label forward to your latest commit. No new commit is created.
• Merge commit. If main has also gained commits, Git combines both lines of work and records a new commit with two parents.

Once merged, you can delete the finished branch:

git branch -d add-calibration-notes

The -d option refuses to delete a branch that has not been merged, which is a useful safety net.

If both lines changed the same part of a file, Git stops and reports a conflict. That is normal and fixable, and the careful routine for it is described in the guide to merge conflicts.

Step 7: share work with others

Everything above happens on your own machine. To exchange commits with a shared repository:

git pull
git push

git pull fetches new commits from the shared copy and combines them with yours. git push sends your commits to it. A sensible routine is to pull before starting work and again before pushing, so that you integrate other people’s changes in small pieces. On many teams you push a branch and ask for a review through a pull request rather than merging into main yourself.

A small worked session

Putting the steps together:

git switch -c fix-typo
(edit the README here)
git status
git add README
git commit -m "Fix typo in setup instructions"
git switch main
git merge fix-typo
git branch -d fix-typo

That is the whole cycle: branch, edit, stage, commit, merge, tidy up. Most daily Git use is variations on it.

Common beginner stumbles

• Forgetting to stage. git commit only records what is staged. If a change is missing from the commit, run git status to see whether it was left behind.
• Committing on the wrong branch. Check which branch you are on with git status before you start.
• Huge commits. Large, mixed commits are hard to review and hard to undo. Commit in small logical steps.
• Panic after a mistake. Most mistakes in Git are recoverable if the work was committed. Stop, read the status, and look up how to undo changes safely before trying anything drastic.

Command options and defaults can differ between Git versions and tools, so check your installed version’s built-in help, for example git help commit, when something behaves differently from what you expect.