ilyagr.bsky.social
just playing with tangled
1# Operation log
2
3
4## Introduction
5
6Jujutsu records each operation that modifies the repo in the "operation log".
7You can see the log with `jj op log`. Each operation object contains a snapshot
8of how the repo looked at the end of the operation. We call this snapshot a
9"view" object. The view contains information about where each bookmark, tag, and
10Git ref (in Git-backed repos) pointed, as well as the set of heads in the repo,
11and the current working-copy commit in each workspace. The operation object also
12(in addition to the view) contains pointers to the operation(s) immediately
13before it, as well as metadata about the operation, such as timestamps,
14username, hostname, description.
15
16The operation log allows you to undo an operation (`jj [op] undo`), which doesn't
17need to be the most recent one. It also lets you restore the entire repo to the
18way it looked at an earlier point (`jj op restore`).
19
20When referring to operations, you can use `@` to represent the current
21operation.
22
23The following operators are supported:
24
25* `x-`: Parents of `x` (e.g. `@-`)
26* `x+`: Children of `x`
27
28
29## divergent operations
30
31One benefit of the operation log (and the reason for its creation) is that it
32allows lock-free concurrency -- you can run concurrent `jj` commands without
33corrupting the repo, even if you run the commands on different machines that
34access the repo via a distributed file system (as long as the file system
35guarantees that a write is only visible once previous writes are visible). When
36you run a `jj` command, it will start by loading the repo at the latest
37operation. It will not see any changes written by concurrent commands. If there
38are conflicts, you will be informed of them by subsequent `jj st` and/or
39`jj log` commands.
40
41As an example, let's say you had started editing the description of a change and
42then also update the contents of the change (maybe because you had forgotten the
43editor). When you eventually close your editor, the command will succeed and
44e.g. `jj log` will indicate that the change has diverged.
45
46
47## Loading an old version of the repo
48
49The top-level `--at-operation/--at-op` option allows you to load the repo at a
50specific operation. This can be useful for understanding how your repo got into
51the current state. It can be even more useful for understanding why someone
52else's repo got into its current state.
53
54When you use `--at-op`, the automatic snapshotting of the working copy will not
55take place. When referring to a revision with the `@` symbol (as many commands
56do by default), that will resolve to the working-copy commit recorded in the
57operation's view (which is actually how it always works -- it's just the
58snapshotting that's skipped with `--at-op`).
59
60As a top-level option, `--at-op` can be passed to any command. However, you
61will typically only want to run read-only commands. For example, `jj log`,
62`jj st`, and `jj diff` all make sense. It's still possible to run e.g.
63`jj --at-op=<some operation ID> describe`. That's equivalent to having started
64`jj describe` back when the specified operation was the most recent operation
65and then let it run until now (which can be done for that particular command by
66not closing the editor). There's practically no good reason to do that other
67than to simulate concurrent commands.