mirrors/jj
1
0
Fork 0
mirror of https://github.com/jj-vcs/jj.git synced 2025-12-23 06:01:01 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: fix and improve colocation docs

Browse source 
Follows up on 7c0328f

Fixes #7776
This commit is contained in:
Ilya Grigoriev 2025-10-28 19:47:52 -07:00 • committed by Ilya Grigoriev
parent f7256f611c
commit c32b476645
4 changed files with 83 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

26
cli/src/commands/git/clone.rs
View file

@ -44,8 +44,6 @@ use crate::git_util::with_remote_git_callbacks;
use crate::ui::Ui;
/// Create a new repo backed by a clone of a Git repo
///
/// The Git repo will be a bare git repo stored inside the `.jj/` directory.
#[derive(clap::Args, Clone, Debug)]
pub struct GitCloneArgs {
/// URL or path of the Git repo to clone
@ -62,10 +60,32 @@ pub struct GitCloneArgs {
/// Name of the newly created remote
#[arg(long = "remote", default_value = "origin")]
remote_name: RemoteNameBuf,
/// Whether or not to colocate the Jujutsu repo with the git repo
/// Colocate the Jujutsu repo with the git repo
///
/// Specifies that the `jj` repo should also be a valid `git` repo, allowing
/// the use of both `jj` and `git` commands in the same directory.
///
/// The repository will contain a `.git` dir in the top-level. Regular Git
/// tools will be able to operate on the repo.
///
/// **This is the default**, and this option has no effect, unless the
/// [git.colocate config] is set to `false`.
///
/// [git.colocate config]:
/// https://jj-vcs.github.io/jj/latest/config/#default-colocation
#[arg(long)]
colocate: bool,
/// Disable colocation of the Jujutsu repo with the git repo
///
/// Prevent Git tools that are unaware of `jj` and regular Git commands from
/// operating on the repo. The Git repository that stores most of the
/// repo data will be hidden inside a sub-directory of the `.jj`
/// directory.
///
/// See [colocation docs] for some minor advantages of non-colocated repos.
///
/// [colocation docs]:
/// https://jj-vcs.github.io/jj/latest/git-compatibility/#colocated-jujutsugit-repos
#[arg(long, conflicts_with = "colocate")]
no_colocate: bool,
/// Create a shallow clone of the given depth

28
cli/src/commands/git/init.rs
View file

@ -56,19 +56,35 @@ pub struct GitInitArgs {
#[arg(default_value = ".", value_hint = clap::ValueHint::DirPath)]
destination: String,
/// Specifies that the `jj` repo should also be a valid
/// `git` repo, allowing the use of both `jj` and `git` commands
/// in the same directory.
/// Colocate the Jujutsu repo with the git repo
///
/// This is done by placing the backing git repo into a `.git` directory in
/// the root of the `jj` repo along with the `.jj` directory. If the `.git`
/// directory already exists, all the existing commits will be imported.
/// Specifies that the `jj` repo should also be a valid `git` repo, allowing
/// the use of both `jj` and `git` commands in the same directory.
///
/// The repository will contain a `.git` dir in the top-level. Regular Git
/// tools will be able to operate on the repo.
///
/// **This is the default**, and this option has no effect, unless the
/// [git.colocate config] is set to `false`.
///
/// This option is mutually exclusive with `--git-repo`.
///
/// [git.colocate config]:
/// https://jj-vcs.github.io/jj/latest/config/#default-colocation
#[arg(long, conflicts_with = "git_repo")]
colocate: bool,
/// Disable colocation of the Jujutsu repo with the git repo
///
/// Prevent Git tools that are unaware of `jj` and regular Git commands from
/// operating on the repo. The Git repository that stores most of the
/// repo data will be hidden inside a sub-directory of the `.jj`
/// directory.
///
/// See [colocation docs] for some minor advantages of non-colocated repos.
///
/// [colocation docs]:
/// https://jj-vcs.github.io/jj/latest/git-compatibility/#colocated-jujutsugit-repos
#[arg(long, conflicts_with = "colocate")]
no_colocate: bool,

34
cli/tests/cli-reference@.md.snap
View file

@ -1304,8 +1304,6 @@ See this [comparison], including a [table of commands].
Create a new repo backed by a clone of a Git repo
The Git repo will be a bare git repo stored inside the `.jj/` directory.
**Usage:** `jj git clone [OPTIONS] <SOURCE> [DESTINATION]`
###### **Arguments:**
@ -1320,8 +1318,22 @@ The Git repo will be a bare git repo stored inside the `.jj/` directory.
* `--remote <REMOTE_NAME>` — Name of the newly created remote
Default value: `origin`
* `--colocate` — Whether or not to colocate the Jujutsu repo with the git repo
* `--colocate` — Colocate the Jujutsu repo with the git repo
Specifies that the `jj` repo should also be a valid `git` repo, allowing the use of both `jj` and `git` commands in the same directory.
The repository will contain a `.git` dir in the top-level. Regular Git tools will be able to operate on the repo.
**This is the default**, and this option has no effect, unless the [git.colocate config] is set to `false`.
[git.colocate config]: https://jj-vcs.github.io/jj/latest/config/#default-colocation
* `--no-colocate` — Disable colocation of the Jujutsu repo with the git repo
Prevent Git tools that are unaware of `jj` and regular Git commands from operating on the repo. The Git repository that stores most of the repo data will be hidden inside a sub-directory of the `.jj` directory.
See [colocation docs] for some minor advantages of non-colocated repos.
[colocation docs]: https://jj-vcs.github.io/jj/latest/git-compatibility/#colocated-jujutsugit-repos
* `--depth <DEPTH>` — Create a shallow clone of the given depth
* `--fetch-tags <FETCH_TAGS>` — Configure when to fetch tags
@ -1446,12 +1458,24 @@ Create a new Git backed repo
###### **Options:**
* `--colocate` — Specifies that the `jj` repo should also be a valid `git` repo, allowing the use of both `jj` and `git` commands in the same directory.
* `--colocate` — Colocate the Jujutsu repo with the git repo
This is done by placing the backing git repo into a `.git` directory in the root of the `jj` repo along with the `.jj` directory. If the `.git` directory already exists, all the existing commits will be imported.
Specifies that the `jj` repo should also be a valid `git` repo, allowing the use of both `jj` and `git` commands in the same directory.
The repository will contain a `.git` dir in the top-level. Regular Git tools will be able to operate on the repo.
**This is the default**, and this option has no effect, unless the [git.colocate config] is set to `false`.
This option is mutually exclusive with `--git-repo`.
[git.colocate config]: https://jj-vcs.github.io/jj/latest/config/#default-colocation
* `--no-colocate` — Disable colocation of the Jujutsu repo with the git repo
Prevent Git tools that are unaware of `jj` and regular Git commands from operating on the repo. The Git repository that stores most of the repo data will be hidden inside a sub-directory of the `.jj` directory.
See [colocation docs] for some minor advantages of non-colocated repos.
[colocation docs]: https://jj-vcs.github.io/jj/latest/git-compatibility/#colocated-jujutsugit-repos
* `--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 colocated repo.

14
docs/git-compatibility.md
View file

@ -123,11 +123,15 @@ 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 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
`git.colocate = false`.
You can disable colocation with the `--no-colocate` flag on the commands `jj git
init` and `jj git clone` or by setting the configuration `git.colocate = false`.
Much of the repo data will still be stored in the Git repository format, but the
Git repository will be hidden inside a sub-directory of the `.jj` directory.
Moreover, unless you explicitly use the `jj git import` and `jj git export`
commands, that Git repository will either have no branches at all (not even a
main branch) or will have branches that are out of date with jj's bookmarks.
Colocation can be disabled because it does have some disadvantages:
* Interleaving `jj` and `git` commands increases the chance of confusing branch
conflicts or [conflicted (AKA divergent) change