From 391bd3a207a9b0bdc680ff71bd321132f00ebf45 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Sun, 16 Apr 2023 21:30:36 -0700 Subject: [PATCH] docs: make co-located repos more prominent, more details At this point, they are stable enough that I think we should advertise them and encourage their use. This also explains some caveats. --- README.md | 4 +++ docs/git-compatibility.md | 69 ++++++++++++++++++++++++++++++--------- 2 files changed, 57 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 90f43fb57d..f903a0b1b0 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,10 @@ add functionality that cannot easily be added to the Git backend. +You can even have a ["co-located" local +repository](docs/git-compatibility.md#co-located-jujutsugit-repos) where you can +use both `jj` and `git` commands interchangeably. + ### The working copy is automatically committed Jujutsu uses a real commit to represent the working copy. Checking out a commit diff --git a/docs/git-compatibility.md b/docs/git-compatibility.md index 00ca1edd0d..5b4c286338 100644 --- a/docs/git-compatibility.md +++ b/docs/git-compatibility.md @@ -85,22 +85,6 @@ commits will be accessible in both repos. Use `jj git import` to update the Jujutsu repo with changes made in the Git repo. Use `jj git export` to update the Git repo with changes made in the Jujutsu repo. -### Co-located Jujutsu/Git repos - -If you initialize the Jujutsu repo in the same working copy as the Git repo by -running `jj init --git-repo=.`, then the import and export will happen -automatically on every command (because not doing that makes it very confusing -when the working copy has changed in Git but not in Jujutsu or vice versa). We -call such repos "co-located". - -This mode is meant to make it easier to start using readonly `jj` commands in an -existing Git repo. You should then be able to switch to using mutating `jj` -commands and readonly Git commands. It's also useful when tools (e.g. build -tools) expect a Git repo to be present. - -There are some bugs and surprising behavior related to `jj undo` in this mode, -such as #922. - ## Creating a repo by cloning a Git repo To create a Jujutsu repo from a remote Git URL, use `jj git clone @@ -109,6 +93,59 @@ https://github.com/octocat/Hello-World` will clone GitHub's "Hello-World" repo into a directory by the same name. +## Co-located Jujutsu/Git repos + +A "co-located" Jujutsu repo is a hybrid Jujutsu/Git repo. These can be created +with `jj git clone --colocate` or if you initialize the Jujutsu repo in an +existing Git repo by running `jj init --git-repo=.`. 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. + +This mode is very convenient useful when tools (e.g. build tools) expect a Git +repo to be present. + +It is allowed to mix `jj` and `git` commands in such a repo in any order. +However, it may be easier to keep track of what is going on if you generally use +read-only `git` commands and use `jj` for any commands that mutate the repo, or +vice-versa. + +You can even 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 a +"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. + +* Interleaving `jj` and `git` commands increases the chance of confusing branch + conflicts or conflicted (AKA divergent) change ids. These never lose data, but + can be annoying. + +* Git tools will have trouble with revisions that contain conflicted files. While + `jj` renders these files with conflict markers in the working copy, they are + stored in a non-human-readable fashion inside the repo. Git tools will often + see this non-human-readable representation. + +* When a `jj` branch is conflicted, the position of the branch in the Git repo + will disagree with one or more of the conflicted positions. The state of that + branch in git will be labeled as though it belongs to a remote named "git", + e.g. `branch@git`. + +* Jujutsu will ignore Git's staging area. It will not understand merge conflicts + as Git represents them, unfinished `git rebase` states, as well as other less + common states a Git repository can be in. + +* Colocated repositories are less resilient to + [concurrency](technical/concurrency.md#syncing-with-rsync-nfs-dropbox-etc) + issues if you share the repo using an NFS filesystem or Dropbox. In general, + such use of Jujustsu is not currently thoroughly tested. + +* There may still be bugs when interleaving mutating `jj` and `git` commands, + usually having to do with a branch pointer ending up in the wrong place. We + are working on the known ones, and are not aware of any major ones. Please + report any new ones you find, or if any of the known bugs are less minor than + they appear. + + ## Branches TODO: Describe how branches are mapped