Level 3 — Branches

Objective

Do a complete piece of work the way a team does: one issue, one branch, two commits, a published branch, a comparison, a merge, and a cleanup. This is the loop you will repeat for every change from now on, so the aim is to run it once slowly and see what each command reports.

Starting state

• The playground connected to your own private project, from Lab 2. git remote -v shows your project and git status says your branch tracks origin/main.
• main up to date: git switch main && git pull.
• A working tree with nothing uncommitted: git status says "nothing to commit, working tree clean".

Pretend issue #33 exists: "FAQ: add a question about Windows".

Instructions

1. Start from a current main and branch.

   $ git switch main
   $ git pull
   $ git switch -c docs/33-faq-windows

   Copy

   Already on 'main'
   Switched to a new branch 'docs/33-faq-windows'

   Checkpoint: git status says On branch docs/33-faq-windows.

2. First commit. Add a question at the end of docs/faq.md:

   ## Does it run on Windows?
   
   Yes, with Python 3.10 or newer.

   Copy

   Then:

   $ git add docs/faq.md
   $ git commit -m "docs: add Windows question to FAQ (#33)"

   Copy

   [docs/33-faq-windows 683cb88] docs: add Windows question to FAQ (#33)
    1 file changed, 4 insertions(+)

   Note the branch name in the output: the commit went to your branch, not to main.

3. Second commit. Add one more line to the same answer, for example See the installation guide for details., then:

   $ git commit -am "docs: link the installation guide from the FAQ (#33)"
   $ git log --oneline -2

   Copy

   0755cde docs: link the installation guide from the FAQ (#33)
   683cb88 docs: add Windows question to FAQ (#33)

4. Publish the branch.

   $ git push -u origin docs/33-faq-windows

   Copy

   To https://gitlab.com/you/trailguide.git
    * [new branch]      docs/33-faq-windows -> docs/33-faq-windows
   branch 'docs/33-faq-windows' set up to track 'origin/docs/33-faq-windows'.

   Checkpoint: refresh the project page. The branch appears in the branch list, and the platform offers to create a merge request from it.

5. Read what your branch adds, exactly as a reviewer will:

   $ git log --oneline main..docs/33-faq-windows

   Copy

   0755cde docs: link the installation guide from the FAQ (#33)
   683cb88 docs: add Windows question to FAQ (#33)

   $ git diff main...docs/33-faq-windows --stat

   Copy

    docs/faq.md | 6 ++++++
    1 file changed, 6 insertions(+)

   Two commits, one file, six added lines. That is the whole change.

6. See the tracking relationship.

   $ git branch -vv

   Copy

   * docs/33-faq-windows 0755cde [origin/docs/33-faq-windows] docs: link the installation guide from the FAQ (#33)
     main                a2bd5c9 [origin/main] Initial import of trailguide

   Each local branch, its newest commit, and the remote branch it tracks.

7. (Optional but realistic) Open a merge request on the website from docs/33-faq-windows into main, with Closes #33 in the description. Then merge it there and skip to step 9, because the platform will have done step 8 for you. To practise the command instead, close the merge request and continue.

8. Merge locally.

   $ git switch main
   $ git merge docs/33-faq-windows

   Copy

   Updating a2bd5c9..0755cde
   Fast-forward
    docs/faq.md | 6 ++++++
    1 file changed, 6 insertions(+)

   Fast-forward: nothing had changed on main, so the label simply moved (lesson 6.6). Push it:

   $ git push

   Copy

   To https://gitlab.com/you/trailguide.git
      a2bd5c9..0755cde  main -> main

9. Clean up both copies of the branch.

   $ git branch -d docs/33-faq-windows

   Copy

   Deleted branch docs/33-faq-windows (was 0755cde).

   $ git push origin --delete docs/33-faq-windows

   Copy

   To https://gitlab.com/you/trailguide.git
    - [deleted]         docs/33-faq-windows

   If you merged through the website with "delete source branch" ticked, the second command answers that the branch is already gone; run git fetch --prune instead.

10. Confirm the end state.

    $ git log --oneline --graph --decorate -3

    Copy

    * 0755cde (HEAD -> main, origin/main) docs: link the installation guide from the FAQ (#33)
    * 683cb88 docs: add Windows question to FAQ (#33)
    * a2bd5c9 Initial import of trailguide

Expected result

• main contains both commits, and local and remote agree (HEAD -> main, origin/main on the same commit).
• git branch lists only main.
• The branch is gone from the project page.
• Your FAQ has the new question.

Common mistakes

• Committing on main by mistake. The output of git commit names the branch; if it says [main …], see lesson 6.9 for the rescue: branch from where you are, then reset main.
• fatal: The current branch … has no upstream branch on the first push. Use -u origin <branch> once, as in step 4.
• git merge while still on the feature branch. That merges main into your branch instead (lesson 6.4). Read the first line of git status before merging.
• Deleting only the local branch. The name stays in everyone's branch list. Step 9 has both halves.
• A merge that is not a fast-forward. If main moved while you worked, step 8 makes a merge commit instead, which is correct and not a problem.

$ git switch main && git pull
$ git switch -c docs/33-faq-windows
# add the Windows question to docs/faq.md
$ git add docs/faq.md
$ git commit -m "docs: add Windows question to FAQ (#33)"
# add one more line to the same answer
$ git commit -am "docs: link the installation guide from the FAQ (#33)"
$ git push -u origin docs/33-faq-windows
$ git log --oneline main..docs/33-faq-windows
$ git diff main...docs/33-faq-windows --stat
$ git switch main
$ git merge docs/33-faq-windows
$ git push
$ git branch -d docs/33-faq-windows
$ git push origin --delete docs/33-faq-windows

What happened and why

Creating the branch cost nothing: one label at the commit main was on (lesson 6.1). Your two commits moved that label while main stayed put, which is why step 5 could show exactly what the branch adds. Publishing created the same branch on the server and linked the two, so git status could report ahead and behind. The merge was a fast-forward because main had gained nothing meanwhile, so no merge commit was needed. Deleting the branch removed two labels; every commit is still there, now reachable from main.

In real work step 7 replaces step 8: the merge request is where review and the pipeline happen, and the platform presses the merge button for you. The commands are worth knowing because they are what the button does.

Next: Level 4 adds a second person, and with them the first real conflict.