From a6e1bc830970e2256312f4a49b64e8398f5b8d28 Mon Sep 17 00:00:00 2001 From: Philip Metzger 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 | 68 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/docs/branches.md b/docs/branches.md index 58fd09f0b..894dfcba4 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,70 @@ 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[^1] and fetches all branches by default, +which is confusing users coming from Git. To smoothen the transition branch +tracking was introduced. + +### What does `git.auto-local-branch` actually do? + +Jujutsu's fetch operations consist of several steps. First `jj git fetch` +fetches all Git refs under `/refs/remotes/origin` (or, if you have +multiple remotes `/refs/remotes/` for each remote). +Then Jujutsu stores these refs as remote tracking branches. Finally, by default, +Jujutsu creates local branches for them. This is similar to Mercurial, which +fetches all it's Booksmarks (equivalent to Git branches) by default. + +There are two ways to disable the creation (or modification) of the local +branches by `jj git fetch`: + + * You can use `jj branch untrack @` to stop tracking + specific branches when fetching from specific remotes. + * You can set `git.auto-local-branch = false` to change the default behavior. + Then, Jujutsu will only create local branches for remote branches which you + explicitly track with `jj branch track@`. + +### Tracking a branch + +To track a branch permanently use `jj branch track @`. +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 @ # Example: jj branch track my-feature@origin +$ # From this point on, branch is tracked and will always be imported. +$ jj git fetch # Update the repository +$ jj new # 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 @ # 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 +128,6 @@ 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). + +[^1]: Tracking in this context means if `jj` should create a local branch for a remote branch. +[design]: design/tracking-branches.md