diff --git a/README.md b/README.md index 0f54c7140..adc4e2795 100644 --- a/README.md +++ b/README.md @@ -226,8 +226,8 @@ Here is how you can explore a GitHub repository with `jj`. -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 diff --git a/cli/src/commands/git/init.rs b/cli/src/commands/git/init.rs index 198cb8702..98a7afc94 100644 --- a/cli/src/commands/git/init.rs +++ b/cli/src/commands/git/init.rs @@ -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)] diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap index 869e2f898..8931cd950 100644 --- a/cli/tests/cli-reference@.md.snap +++ b/cli/tests/cli-reference@.md.snap @@ -1349,7 +1349,7 @@ Create a new Git backed repo * `--no-colocate` — Disable colocation of the Jujutsu repo with the 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`. diff --git a/docs/FAQ.md b/docs/FAQ.md index e79a81731..9958af304 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -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? +### 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 diff --git a/docs/bookmarks.md b/docs/bookmarks.md index a7ed7cb24..fc8878b23 100644 --- a/docs/bookmarks.md +++ b/docs/bookmarks.md @@ -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 diff --git a/docs/config.md b/docs/config.md index e88d43148..503bb9acb 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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. diff --git a/docs/git-compatibility.md b/docs/git-compatibility.md index 60e756380..7796a4c05 100644 --- a/docs/git-compatibility.md +++ b/docs/git-compatibility.md @@ -102,9 +102,9 @@ By default, the remote repository will be named `origin`. You can use a name of your choice by adding `--remote ` to the `jj git clone` command. -## Co-located Jujutsu/Git repos +## 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 diff --git a/docs/github.md b/docs/github.md index 65d9f5b3a..96ffc186d 100644 --- a/docs/github.md +++ b/docs/github.md @@ -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 diff --git a/docs/glossary.md b/docs/glossary.md index 5096c1be0..4adbd08b4 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -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 +## 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 diff --git a/docs/technical/concurrency.md b/docs/technical/concurrency.md index 1ee843e08..901365d6e 100644 --- a/docs/technical/concurrency.md +++ b/docs/technical/concurrency.md @@ -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.