From 8ccb35fdcfdc086117a8466d05afb511ed306599 Mon Sep 17 00:00:00 2001
From: Philip Metzger <philipmetzger@bluewin.ch>
Date: Tue, 14 Nov 2023 22:51:59 +0100
Subject: [PATCH] docs: Add branch tracking to branches.md.

This tries to explain Jujutsu's branch tracking for a newcomer.
It is based on it's design doc in `docs/design/tracking-branches.md`.
---
 docs/branches.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/docs/branches.md b/docs/branches.md
index 58fd09f0b9..4814a3240f 100644
--- a/docs/branches.md
+++ b/docs/branches.md
@@ -11,7 +11,6 @@ pass a branch's name to commands that want a revision as argument. For example,
 `jj branch list` to list branches and `jj branch` to create, move, or delete
 branches. There is currently no concept of an active/current/checked-out branch.
 
-
 ## Remotes
 
 Jujutsu identifies a branch by its name across remotes (this is unlike Git and
@@ -41,6 +40,52 @@ branch `main`. If the local target had also moved compared to `main@origin`
 merged. If one is ahead of the other, then that target will be the new target.
 Otherwise, the local branch will be conflicted (see next section for details).
 
+As of December 2023 Jujutsu tracks and fetches all branches by default, which 
+is confusing users coming from Git and Mercurial. To smoothen the transition 
+branch tracking was introduced. 
+
+### Tracking a branch
+
+To track a branch permanently use `jj branch track <name-of-branch>`. It will 
+now be imported as a local branch until you untrack it or it is deleted on the 
+remote. 
+
+Example:
+
+```sh
+$ # List all available branches, as we want our colleague's branch.
+$ jj branch list --all
+$ # Find the branch.
+$ # [...]
+$ # Actually track the branch.
+$ jj branch track <name>@<remote> # Example: jj branch track my-feature@origin
+$ # From this point on, branch <name> is tracked and will always be imported.
+$ jj git fetch # Update the repository
+$ jj new <name> # Do some local testing, etc.
+```
+
+### Untracking a branch
+
+To no longer have a branch available in a repository, you can 
+`jj branch untrack` it. After that subsequent fetches will no longer copy the 
+branch into the local repository. 
+
+Example: 
+
+```sh
+$ # List all local and remote branches.
+$ jj branch list --all
+$ # Find the branch we no longer want to track.
+$ # [...]
+# # Actually untrack it.
+$ jj branch untrack <name>@<remote> # Example: jj branch untrack stuff@origin
+$ # From this point on, it won't be imported anymore. 
+```
+
+
+If you want to know the internals of branch tracking, consult the 
+[Design Doc][design].
+
 
 ## Conflicts
 
@@ -65,3 +110,5 @@ on top of the other with `jj rebase`.
 To resolve a conflicted state in a remote branch (e.g. `main@origin`), simply
 pull from the remote (e.g. `jj git fetch`). The conflict resolution will also
 propagate to the local branch (which was presumably also conflicted).
+
+[design]: design/tracking-branches.md