Skip to content

Commit

Permalink
docs: Add branch tracking to branches.md.
Browse files Browse the repository at this point in the history
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`.
  • Loading branch information
PhilipMetzger committed Dec 6, 2023
1 parent c31b0f7 commit 8ccb35f
Showing 1 changed file with 48 additions and 1 deletion.
49 changes: 48 additions & 1 deletion docs/branches.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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

0 comments on commit 8ccb35f

Please sign in to comment.