diff --git a/docs/git-compatibility.md b/docs/git-compatibility.md index b2137cc12..d1b97cc43 100644 --- a/docs/git-compatibility.md +++ b/docs/git-compatibility.md @@ -78,16 +78,16 @@ underlying Git repo will be inside of that directory (currently in To create a Jujutsu repo backed by a Git repo you already have on disk, use `jj init --git-repo= `. The repo will work similar to a [Git worktree](https://git-scm.com/docs/git-worktree), meaning that the working -copies and the record of the current checkout will be separate, but the 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. +copies files and the record of the working-copy commit will be separate, but the +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. -If you create 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 +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 current checkout has changed in Git but not in Jujutsu or vice versa). -This mode is meant to make it easier to start using readonly `jj` commands in an +when the working copy has changed in Git but not in Jujutsu or vice versa). 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. The mode is new and not tested much, and interleaving mutating `jj` and `git` commands might not work well (feel free diff --git a/docs/operation-log.md b/docs/operation-log.md index 9c0d594b2..931e0ac16 100644 --- a/docs/operation-log.md +++ b/docs/operation-log.md @@ -8,9 +8,10 @@ You can see the log with `jj op log`. Each operation object contains a snapshot of how the repo looked at the end of the operation. We call this snapshot a "view" object. The view contains information about where each branch, tag, and Git ref (in Git-backed repos) pointed, as well as the set of heads in the repo, -and the current checkout. The operation object also (in addition to the view) -contains pointers to the operation(s) immediately before it, as well as metadata -about the operation, such as timestamps, username, hostname, description. +and the current working-copy commit. The operation object also (in addition to +the view) contains pointers to the operation(s) immediately before it, as well +as metadata about the operation, such as timestamps, username, hostname, +description. The operation log allows you to undo an operation (`jj op undo`), which doesn't need to be the most recent one. It also lets you restore the entire repo to the @@ -44,11 +45,11 @@ else's repo got into its current state. When you use `--at-op`, the automatic snapshotting of the working copy will not take place. When referring to a revision with the `@` symbol (as many commands -do by default), that will resolve to the current checkout recorded in the +do by default), that will resolve to the working-copy commit recorded in the operation's view (which is actually how it always works -- it's just the snapshotting that's skipped with `--at-op`). -As a top-level option, `--at-op`, it can be passed to any command. However, you +As a top-level option, `--at-op` can be passed to any command. However, you will typically only want to run read-only commands. For example, `jj log`, `jj st`, and `jj diff` all make sense. It's still possible to run e.g. `jj --at-op= describe`. That's equivalent to having started diff --git a/docs/technical/concurrency.md b/docs/technical/concurrency.md index c3f0f08fd..548b37c30 100644 --- a/docs/technical/concurrency.md +++ b/docs/technical/concurrency.md @@ -55,7 +55,7 @@ what allows us to detect and merge concurrent operations. The operation log is similar to a commit DAG (such as in Git), but each commit object is instead an "operation" and each tree object is instead a "view". The view object contains the set of visible head commits, branches, tags, and the -current checkout. The operation object contains a pointer to the view object +working-copy commit. The operation object contains a pointer to the view object (like how commit objects point to tree objects), pointers to parent operation(s) (like how commit objects point to parent commit(s)), and metadata about the operation. These types are defined [here](../../lib/protos/op_store.proto). The diff --git a/docs/working-copy.md b/docs/working-copy.md index d2315f9d8..d69fdf2fc 100644 --- a/docs/working-copy.md +++ b/docs/working-copy.md @@ -3,9 +3,9 @@ ## Introduction -The working copy is where the current checkout's files are written so you can -interact with them. It also where files are read from in order to create new -commits (though there are many other ways of creating new commits). +The working copy is where the current working-copy commit's files are written so +you can interact with them. It also where files are read from in order to create +new commits (though there are many other ways of creating new commits). Unlike most other VCSs, Jujutsu will automatically create commits from the working-copy contents when they have changed. Most `jj` commands you run will @@ -26,18 +26,18 @@ This section only applies if you have set `ui.enable-open-commits = true` in your config. As described in the introduction, Jujutsu automatically rewrites the current -checkout with any changes from the working copy. That works well while you're -developing that revision. On the other hand, if you check out some existing -revision, you generally don't want changes to the working copy to automatically -rewrite that revision. Jujutsu has a concept of "open" and "closed" revisions to -solve this. When you check out a closed revision, Jujutsu will actually create a -new, *open* revision on top of it and check that out. The checked-out revision -is thus always open. When you are done making changes to the currently -checked-out revision, you close it by running `jj close`. That command then -updates to the rewritten revision (as most `jj` commands do), and since the -rewritten revision is now closed, it creates a new open revision on top. If you -check out a closed revision and make changes on top of it that you want to go -into the revision, use `jj squash`. +working-copy commit with any changes from the working copy. That works well +while you're developing that revision. On the other hand, if you check out some +existing revision, you generally don't want changes to the working copy to +automatically rewrite that revision. Jujutsu has a concept of "open" and +"closed" revisions to solve this. When you check out a closed revision, Jujutsu +will actually create a new, *open* revision on top of it and check that out. The +working-copy commit is thus always open. When you are done making changes to +the current working-copy commit, you close it by running `jj close`. That +command then updates to the rewritten revision (as most `jj` commands do), and +since the rewritten revision is now closed, it creates a new open revision on +top. If you check out a closed revision and make changes on top of it that you +want to go into the revision, use `jj squash`. ## Conflicts