Branch basics

What you will be able to do

Try a new idea on its own line of work, without changing the work that is already correct. Teams do almost every change this way.

Before you startWhat to know and to have readyAbout 25 minutes

What you need to know

• The working tree, the staging area and the commit history, from Track a first change: Three places for your changes.
• How to stage and commit a change, and read git log --oneline, from Track a first change: Worked example: Amira’s first commit.

What you need on your computer

• The repository ~/projects/ticket-notes with at least two commits, and the file tickets.txt. You made them in Track a first change: Guided practice: make your first commits.

• In the repository, git status shows nothing to commit, working tree clean. If it shows changes, commit them first.

• If the repository is missing, do Set up Git: Step 3: make a repository again. Then do the guided practice of Track a first change.

• If the repository is missing or broken, a script can make the start state of this lesson again. In ~/projects, run:

  git clone https://github.com/Nextia-Intelligence/nextia-learning-labs.git
  sh nextia-learning-labs/C14/setup.sh m02-l01 --reset

  Run the git clone command only once. If you already have the nextia-learning-labs folder, run git -C nextia-learning-labs pull instead. Pull-request sequence: Set up the practice lab explains the script in full. The script makes ~/projects/c14-lab/ticket-notes with the three commits from Track a first change on main. Its hashes are the same as in this lesson: 763ec59, 49397ba and d8ae027. The commit that you make in this lesson has your name and time, so its hash is different from 999a7c4. This is expected. Then use ~/projects/c14-lab in place of ~/projects in this lesson. --reset deletes an older c14-lab folder first, but your ~/projects/ticket-notes does not change.

• The hashes in this lesson come from Amira’s repository. Your hashes are different. Use the ones from your own git log.

A branch is a label on a commit

In Module 1, every commit went onto main. main is a branch: a name that points to one commit. When you make a new commit, Git moves the branch label forward to the new commit. The label always points to the newest commit of that line of work.

You can make more branches. Each one is a separate label, so each line of work can move forward on its own. A new branch costs almost nothing: Git does not copy your files. It only writes the new label.

How does Git know which branch you are on? It uses HEAD: a pointer to the branch that you are on now. When you commit, Git moves the branch that HEAD points to. The other branches do not move.

Branches are labels. Here, main points to d8ae027 and add-priorities points to the newer commit 999a7c4. HEAD shows that you are on main.

Each commit is identified by its commit hash, which you met in Module 1. A branch name changes as the branch moves, but a hash always means the same commit. Use a hash when you must talk about one exact commit.

Worked example: a branch for priority levels

Amira wants to add priority levels to the ticket notes. She is not sure that her team will agree, so she uses a new branch. First, she looks at her branches and her history:

Terminal

git branch
git log --oneline

Output

* main
d8ae027 (HEAD -> main) Add first ticket note
49397ba Describe who the notes are for
763ec59 Add README

git branch lists the branches. The * marks the branch that she is on. In the log, HEAD -> main shows the same thing: HEAD points to main, and main points to d8ae027.

She makes a branch called add-priorities and switches to it in one step. The -c option means “create”:

Terminal

git switch -c add-priorities
git branch

Output

Switched to a new branch 'add-priorities'
* add-priorities
  main

Now she makes priorities.txt with one line, Priority levels: low, normal, urgent., and commits it:

Terminal

git add priorities.txt
git commit -m "Add priority levels"
git log --oneline

Output

[add-priorities 999a7c4] Add priority levels
 1 file changed, 1 insertion(+)
 create mode 100644 priorities.txt
999a7c4 (HEAD -> add-priorities) Add priority levels
d8ae027 (main) Add first ticket note
49397ba Describe who the notes are for
763ec59 Add README

The new commit is on add-priorities. main did not move: it still points to d8ae027. This is the situation in the diagram above, but with HEAD on add-priorities.

Next, she switches back to main and lists the files:

Terminal

git switch main
ls

Output

Switched to branch 'main'
README.md  tickets.txt

priorities.txt is gone from the folder. This is correct. When you switch branches, Git changes the files in the working tree to match the commit of that branch. The file is safe in commit 999a7c4. When she runs git switch add-priorities, the file comes back.

To see all branches at the same time, she adds --all:

Terminal

git log --oneline --all

Output

999a7c4 (add-priorities) Add priority levels
d8ae027 (HEAD -> main) Add first ticket note
49397ba Describe who the notes are for
763ec59 Add README

Guided practice: work on a branch

1. In ~/projects/ticket-notes, run git status. The output must include working tree clean. If not, commit or remove your changes first.

2. Make a branch and switch to it:

   git switch -c add-priorities

   The output is Switched to a new branch 'add-priorities'.

3. In your editor, make priorities.txt with the line Priority levels: low, normal, urgent. Save it.

4. Stage and commit the file:

   git add priorities.txt
   git commit -m "Add priority levels"

5. Run git log --oneline --all. The newest commit has (HEAD -> add-priorities). main is on the commit before it.

6. Switch to main:

   git switch main

7. Run ls. priorities.txt is not in the list.

8. Switch back with git switch add-priorities, and run ls again. priorities.txt is in the list.

9. Switch to main again before you continue.

Your turn: a second branch

Make a second branch from main called add-contacts. On it, make contacts.txt with the names of a help desk team, and commit it.

Then answer these questions with git log --oneline --all and ls:

1. Which commit does each of your three branches point to?
2. When you are on add-contacts, is priorities.txt in the folder? Why?

Show the answers

1. main points to the commit that it pointed to before the lesson. add-priorities and add-contacts each point to their own new commit.
2. No. You made add-contacts from main, and main does not contain priorities.txt. Each branch only contains the commits on its own line of work.

Note

In older guides, you can see git checkout used to switch branches. git switch does the same job and is easier to read. It is in Git 2.23 and later.

Common mistake

My change followed me to the other branch

Symptom: you edit tickets.txt on main, but you do not commit. Then you run git switch add-priorities. Git switches, and shows:

Switched to branch 'add-priorities'
M  tickets.txt

Your change is now in the working tree of add-priorities.

Cause: changes that you did not commit do not belong to a branch. They stay in the working tree when you switch. Git only stops the switch if a change would be lost, and then it shows an error.

Fix:

1. Run git switch main to go back.
2. Commit the change on main if it belongs there.

To prevent this, run git status before you switch. Switch only when the output says working tree clean.

Common mistake

Invalid reference

Symptom: git switch add-priority shows fatal: invalid reference: add-priority.

Cause: no branch has that name. Usually it is a typing mistake. Here the name is add-priorities, not add-priority.

Fix: run git branch to see the correct names, then switch again.

Check your understanding

Predict: Amira is on add-priorities. She makes two more commits. Which branch labels move, and does main change?

Show the answer

Only add-priorities moves. It moves forward once for each commit, so it ends on the second new commit. main does not change, because HEAD points to add-priorities, and Git moves only the branch that HEAD points to.

Check your understanding

Practical check: show which branch you are on, and which commit each branch points to, with one command.

Show the answer

Run git log --oneline --all. Each branch name is next to the commit that it points to. HEAD -> shows the branch that you are on. You can also use git branch -v, which lists each branch with its commit hash.

Recap

• A branch is a label that points to one commit. It moves forward when you commit on it.
• HEAD points to the branch that you are on. git branch and git log --oneline --all show it.
• git switch -c name makes a branch and switches to it. git switch name switches to a branch that exists.
• When you switch, Git changes the files to match that branch. Changes that you did not commit stay in the working tree.

Next: Synchronize deliberately