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/branch_tracking.md`.

WIP: Not done yet
  • Loading branch information
PhilipMetzger committed Dec 5, 2023
1 parent a3d36b5 commit 273cabe
Showing 1 changed file with 44 additions and 1 deletion.
45 changes: 44 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,48 @@ 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 available in your local repository 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 git branch list --all
$ # Find the branch.
$ jj git branch track <name>
$ # 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.
$ jj branch untrack <name>
$ # 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 +106,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/branch_tracking.md

0 comments on commit 273cabe

Please sign in to comment.