mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2024-12-01 03:45:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: Add branch tracking to branches.md.

Browse source 
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`.
This commit is contained in:
Philip Metzger 2023-11-14 22:51:59 +01:00 committed by Philip Metzger
parent 15cca8a3f1
commit a6e1bc8309
1 changed files with 67 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
docs/branches.md
View file

@ -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).
<!-- TODO: Adjust this paragraph to the new defaults which were introduced in #2736 -->
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/<remote name>` 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 <branch-name>@<remote name>` 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<branch name>@<remote name>`.
### Tracking a branch
To track a branch permanently use `jj branch track <branch name>@<remote name>`.
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 <branch name>@<remote name> # 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 <branch name>@<remote name> # 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