From 69bc1f2b0f6c91f70aaee00b0b31f1bf31d38d51 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Wed, 3 Jan 2024 22:56:20 -0800 Subject: [PATCH] docs `branches.md`: insert definitions for related terms --- docs/branches.md | 21 +++++++++++++++++++++ docs/glossary.md | 8 ++++++++ 2 files changed, 29 insertions(+) diff --git a/docs/branches.md b/docs/branches.md index 0330827d7..aec2b0414 100644 --- a/docs/branches.md +++ b/docs/branches.md @@ -51,6 +51,27 @@ some remote. If you want to know the internals of branch tracking, consult the [Design Doc][design]. +### Terminology summary + +- A **remote branch** is a branch ref on the remote. `jj` can find out its + actual state only when it's actively communicating with the remote. However, + `jj` does store the last-seen position of the remote branch; this is the + commit `jj show @` would show. This notion is + completely analogous to Git's "remote-tracking branches". +- A **tracked (remote) branch** is defined above. You can make a remote branch + tracked with the [`jj branch track` command](#manually-tracking-a-branch), for + example. +- A **tracking (local) branch** is the local branch that `jj` tries to keep in + sync with the tracked remote branch. For example, after `jj branch track + mybranch@origin`, there will be a local branch `mybranch` that's tracking the + remote `mybranch@origin` branch. A local branch can track a branch of the same + name on 0 or more remotes. + +The notion of tracked branches serves a similar function to the Git notion of an +"upstream branch". Unlike Git, a single local branch can be tracking remote +branches on multiple remotes, and the names of the local and remote branches +must match. + ### Manually tracking a branch To track a branch permanently use `jj branch track @`. diff --git a/docs/glossary.md b/docs/glossary.md index 017d8720d..81a1f58df 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -173,6 +173,14 @@ A tree object represents a snapshot of a directory in the repository. Tree objects are defined recursively; each tree object only has the files and directories contained directly in the directory it represents. +## Tracked branches and tracking branches + +A remote branch can be made "tracked" with the `jj branch track` command. This +results in a "tracking" local branch that tracks the remote branch. + +See [the branches documentation](branches.md#terminology-summary) for a more +detailed definition of these terms. + ## Visible commits Visible commits are the commits you see in `jj log -r 'all()'`. They are the