docs: standardize usage of term "colocate" without the hyphen
Some checks are pending
binaries / Build binary artifacts (push) Waiting to run
website / prerelease-docs-build-deploy (ubuntu-24.04) (push) Waiting to run
Scorecards supply-chain security / Scorecards analysis (push) Waiting to run

The hyphen-less version is preferred since there are already existing
command flags and config options which use the hyphen-less variation.
This commit is contained in:
Benjamin Tan 2025-09-05 00:45:22 +08:00
parent 5b83c9899c
commit b70a12e2db
10 changed files with 33 additions and 33 deletions

View file

@ -226,8 +226,8 @@ Here is how you can explore a GitHub repository with `jj`.
<img src="demos/git_compat.png" />
You can even have a ["co-located" local
repository](https://jj-vcs.github.io/jj/latest/git-compatibility#co-located-jujutsugit-repos)
You can even have a [colocated local
repository](https://jj-vcs.github.io/jj/latest/git-compatibility#colocated-jujutsugit-repos)
where you can use both `jj` and `git` commands interchangeably.
### The working copy is automatically committed

View file

@ -78,7 +78,7 @@ pub struct GitInitArgs {
/// If the specified `--git-repo` path happens to be the same as
/// the `jj` repo path (both .jj and .git directories are in the
/// same working directory), then both `jj` and `git` commands
/// will work on the same repo. This is called a co-located repo.
/// will work on the same repo. This is called a colocated repo.
///
/// This option is mutually exclusive with `--colocate`.
#[arg(long, conflicts_with = "colocate", value_hint = clap::ValueHint::DirPath)]

View file

@ -1349,7 +1349,7 @@ Create a new Git backed repo
* `--no-colocate` — Disable colocation of the Jujutsu repo with the git repo
* `--git-repo <GIT_REPO>` — Specifies a path to an **existing** git repository to be used as the backing git repo for the newly created `jj` repo.
If the specified `--git-repo` path happens to be the same as the `jj` repo path (both .jj and .git directories are in the same working directory), then both `jj` and `git` commands will work on the same repo. This is called a co-located repo.
If the specified `--git-repo` path happens to be the same as the `jj` repo path (both .jj and .git directories are in the same working directory), then both `jj` and `git` commands will work on the same repo. This is called a colocated repo.
This option is mutually exclusive with `--colocate`.

View file

@ -93,9 +93,9 @@ Alternatively, you can use [jj-fzf](https://github.com/tim-janik/jj-fzf), where
The wiki lists additional TUIs and GUIs beyond the terminal: [GUI-and-TUI](https://github.com/jj-vcs/jj/wiki/GUI-and-TUI)
### Should I co-locate my repository?
### <a name="should-i-co-locate-my-repository"></a>Should I colocate my repository?
Co-locating a Jujutsu repository allows you to use both Jujutsu and Git in the
Colocating a Jujutsu repository allows you to use both Jujutsu and Git in the
same working copy. The benefits of doing so are:
- You can use Git commands when you're not sure how to do something with
@ -104,8 +104,8 @@ same working copy. The benefits of doing so are:
- Tooling that expects a Git repository still works (IDEs, build tooling, etc.)
The [co-location documentation describes the
drawbacks](git-compatibility.md#co-located-jujutsugit-repos) but the most
The [colocation documentation describes the
drawbacks](git-compatibility.md#colocated-jujutsugit-repos) but the most
important ones are:
- Interleaving `git` and `jj` commands may create confusing bookmark conflicts
@ -125,8 +125,8 @@ important ones are:
affected by this.
If you primarily use Jujutsu to modify the repository, the drawbacks are
unlikely to affect you. Try co-locating while you learn Jujutsu, then switch if
you find a specific reason not to co-locate.
unlikely to affect you. Try colocating while you learn Jujutsu, then switch if
you find a specific reason not to colocate.
### `jj` is said to record the working copy after `jj log` and every other command. Where can I see these automatic "saves"?
@ -575,7 +575,7 @@ be different from the original one, it wouldn't be deduplicated.
You'll have to manually invoke `git push` of `HEAD` on the underlying git repository
into the remote Gerrit bookmark `refs/for/$BRANCH`, where `$BRANCH` is the base
bookmark you want your changes to go to (e.g., `git push origin
HEAD:refs/for/main`). Using a [co-located][co-located] repo
HEAD:refs/for/main`). Using a [colocated][colocated] repo
will make the underlying git repo directly accessible from the working
directory.
@ -630,7 +630,7 @@ detect custom backends and more).
[change]: glossary.md#change
[change ID]: glossary.md#change-id
[co-located]: glossary.md#co-located-repos
[colocated]: glossary.md#colocated-repos
[commit ID]: glossary.md#commit-id
[commits]: glossary.md#commit
[config]: config.md

View file

@ -234,5 +234,5 @@ command itself through an alias (as `jj b`), and for its subcommands.
For example, `jj bookmark create BOOKMARK-NAME -r@` can be abbreviated as
`jj b c BOOKMARK-NAME -r@`.
[colocated-repos]: git-compatibility.md#co-located-jujutsugit-repos
[colocated-repos]: git-compatibility.md#colocated-jujutsugit-repos
[design]: design/tracking-branches.md

View file

@ -1450,7 +1450,7 @@ signature details.
### Default colocation
When creating a git-backed Jujutsu repository, you can disable "colocation" which
When creating a git-backed Jujutsu repository, you can disable colocation which
places the `.git` directory next to the `.jj` directory. Colocation allows some
amount of two-way interoperability, but it can perform worse in large repos.
@ -1458,7 +1458,7 @@ The setting `git.colocate` is a boolean option that controls whether or not the
`jj git init` and `jj git clone` commands should create colocated repositories
by default. By default, `git.colocate` is set to `true`.
See [Co-located Jujutsu/Git repos](git-compatibility.md#co-located-jujutsugit-repos) for more information.
See [Colocated Jujutsu/Git repos](git-compatibility.md#colocated-jujutsugit-repos) for more information.
### Default remotes for `jj git fetch` and `jj git push`
@ -1502,7 +1502,7 @@ local bookmark with the same name. This feature is disabled by default because i
may be undesirable in some repositories, e.g.:
- There is a remote with a lot of historical bookmarks that you don't
want to be exported to the co-located Git repo.
want to be exported to the colocated Git repo.
- There are multiple remotes with conflicting views of that bookmark,
resulting in an unhelpful conflicted state.

View file

@ -102,9 +102,9 @@ By default, the remote repository will be named `origin`. You can use
a name of your choice by adding `--remote <remote name>` to the `jj
git clone` command.
## Co-located Jujutsu/Git repos
## <a name="co-located-jujutsugit-repos"></a>Colocated Jujutsu/Git repos
A "co-located" Jujutsu repo is a hybrid Jujutsu/Git repo. This is the default
A colocated Jujutsu repo is a hybrid Jujutsu/Git repo. This is the default
for Git-backed repositories created with `jj git init` or `jj git clone`.
The Git repo and the Jujutsu repo then share the same working copy. Jujutsu will
import and export from and to the Git repo on every `jj` command automatically.
@ -124,7 +124,7 @@ You can undo the results of mutating `git` commands using `jj undo` and `jj op
restore`. Inside `jj op log`, changes by `git` will be represented as an "import
git refs" operation.
There are a few downsides to this mode of operation. Generally, using co-located
There are a few downsides to this mode of operation. Generally, using colocated
repos may require you to deal with more involved Jujutsu and Git concepts.
You can disable colocation with the `--no-colocate` flag on the commands
`jj git init` and `jj git clone` or by setting the configuration
@ -139,7 +139,7 @@ You can disable colocation with the `--no-colocate` flag on the commands
it because they automatically run `git fetch` in the background from time to
time.
* In co-located repos with a very large number of branches or other refs, `jj`
* In colocated repos with a very large number of branches or other refs, `jj`
commands can get noticeably slower because of the automatic `jj git import`
executed on each command. This can be mitigated by occasionally running `jj util
gc` to speed up the import (that command includes packing the Git refs).
@ -169,11 +169,11 @@ You can disable colocation with the `--no-colocate` flag on the commands
report any new ones you find, or if any of the known bugs are less minor than
they appear.
### Converting a repo into a co-located repo
### Converting a repo into a colocated repo
A Jujutsu repo backed by a Git repo has a full Git repo inside, so it is
technically possible (though not officially supported) to convert it into a
co-located repo like so:
colocated repo like so:
```bash
# Ignore the .jj directory in Git

View file

@ -57,14 +57,14 @@ changes.
[sync-issue]: https://github.com/jj-vcs/jj/issues/1039
## Working in a Git co-located repository
## Working in a Git colocated repository
After doing `jj git init`, which
[colocates](git-compatibility.md#co-located-jujutsugit-repos) the `.jj` and
[colocates](git-compatibility.md#colocated-jujutsugit-repos) the `.jj` and
`.git` directories, Git will be in a [detached HEAD state][detached], which is
unusual, as Git mainly works with named branches; jj does not.
In a co-located repository, every `jj` command will automatically synchronize
In a colocated repository, every `jj` command will automatically synchronize
Jujutsu's view of the repo with Git's view. For example, `jj commit` updates the
HEAD of the Git repository, enabling an incremental migration.
@ -175,7 +175,7 @@ You can find more information on that setting [here][auto-bookmark].
## Using GitHub CLI
GitHub CLI will have trouble finding the proper Git repository path in jj repos
that aren't [co-located](./git-compatibility.md#co-located-jujutsugit-repos)
that aren't [colocated](./git-compatibility.md#colocated-jujutsugit-repos)
(see [issue #1008]). You can configure the `$GIT_DIR` environment variable to
point it to the right path:
@ -192,7 +192,7 @@ export GIT_DIR=$PWD/.jj/repo/store/git
```
and run `direnv allow` to approve it for direnv to run. Then GitHub CLI will
work automatically even in repos that aren't co-located so you can execute
work automatically even in repos that aren't colocated so you can execute
commands like `gh issue list` normally.
[issue #1008]: https://github.com/jj-vcs/jj/issues/1008

View file

@ -38,7 +38,7 @@ branch](#anonymous-branch) or, less formally, a branch of the commit "tree"
might resemble a tree even when it's not mathematically a tree).
We also sometimes discuss Git's branches and branches on Git remotes. Locally,
these correspond to [bookmarks](#bookmark). In a co-located repository, each
these correspond to [bookmarks](#bookmark). In a colocated repository, each
local Git branch corresponds to a `jj` bookmark.
## Change
@ -79,14 +79,14 @@ long when using the Git backend. They are presented in regular hexadecimal
format at the end of the line in `jj log`, using 12 hexadecimal digits by
default. When using the Git backend, the commit ID is the Git commit ID.
## Co-located repos
## <a name="co-located-repos"></a>Colocated repos
When using the Git [backend](#backend) and the backing Git repository's `.git/`
directory is a sibling of `.jj/`, we call the repository "co-located". Most
directory is a sibling of `.jj/`, we call the repository colocated. Most
tools designed for Git can be easily used on such repositories. `jj` and `git`
commands can be used interchangeably.
See [here](git-compatibility.md#co-located-jujutsugit-repos) for details.
See [here](git-compatibility.md#colocated-jujutsugit-repos) for details.
## Conflict

View file

@ -54,8 +54,8 @@ entirely lock-free](https://github.com/jj-vcs/jj/issues/2193). If you know
about the bug, it is relatively easy to recover from.
Moreover, such use of Jujutsu is not currently thoroughly tested,
especially in the context of [co-located
repositories](../glossary.md#co-located-repos). While the contents of commits
especially in the context of [colocated
repositories](../glossary.md#colocated-repos). While the contents of commits
should be safe, concurrent modification of a repository from different computers
might conceivably lose some bookmark pointers. Note that, unlike in pure
Git, losing a bookmark pointer does not lead to losing commits.