ilyagr.bsky.social
just playing with tangled
1# Working copy
2
3
4## Introduction
5
6The working copy is where the current working-copy commit's files are written so
7you can interact with them. It is also where files are read from in order to
8create new commits (though there are many other ways of creating new commits).
9
10Unlike most other VCSs, Jujutsu will automatically create commits from the
11working-copy contents when they have changed. Most `jj` commands you run will
12commit the working-copy changes if they have changed. The resulting revision
13will replace the previous working-copy revision.
14
15Also unlike most other VCSs, added files are implicitly tracked by default. That
16means that if you add a new file to the working copy, it will be automatically
17committed once you run e.g. `jj st`. Similarly, if you remove a file from the
18working copy, it will implicitly be untracked.
19
20The `snapshot.auto-track` config option controls which paths get automatically
21tracked when they're added to the working copy. See the
22[fileset documentation](filesets.md) for the syntax. Files with paths matching
23[ignore files](#ignored-files) are never tracked automatically.
24
25You can use `jj file untrack` to untrack a file while keeping it in the working
26copy. However, first [ignore](#ignored-files) them or remove them from the
27`snapshot.auto-track` patterns; otherwise they will be immediately tracked again.
28
29
30## Conflicts
31
32When you check out a commit with conflicts, those conflicts need to be
33represented in the working copy somehow. However, the file system doesn't
34understand conflicts. Jujutsu's solution is to add conflict markers to
35conflicted files when it writes them to the working copy. It also keeps track of
36the (typically 3) different parts involved in the conflict. Whenever it scans
37the working copy thereafter, it parses the conflict markers and recreates the
38conflict state from them. You can resolve conflicts by replacing the conflict
39markers by the resolved text. You don't need to resolve all conflicts at once.
40You can even resolve part of a conflict by updating the different parts of the
41conflict marker.
42
43To resolve conflicts in a commit, use `jj new <commit>` to create a working-copy
44commit on top. You would then have the same conflicts in the working-copy
45commit. Once you have resolved the conflicts, you can inspect the conflict
46resolutions with `jj diff`. Then run `jj squash` to move the conflict
47resolutions into the conflicted commit. Alternatively, you can edit the commit
48with conflicts directly in the working copy by using `jj edit <commit>`. The
49main disadvantage of that is that it's harder to inspect the conflict
50resolutions.
51
52With the `jj resolve` command, you can use an external merge tool to resolve
53conflicts that have 2 sides and a base. There is not yet a good way of
54resolving conflicts between directories, files, and symlinks
55(https://github.com/jj-vcs/jj/issues/19). You can use `jj restore` to choose
56one side of the conflict, but there's no way to even see where the involved
57parts came from.
58
59
60## Ignored files
61
62You probably don't want build outputs and temporary files to be under version
63control. You can tell Jujutsu to not automatically track certain files by using
64`.gitignore` files (there's no such thing as `.jjignore` yet).
65See https://git-scm.com/docs/gitignore for details about the format.
66`.gitignore` files are supported in any directory in the working copy, as well
67as in `$XDG_CONFIG_HOME/git/ignore` and `$GIT_DIR/info/exclude`.
68
69Ignored files are never tracked automatically (regardless of the value of
70`snapshot.auto-track`), but files that were already tracked will remain tracked
71even if they match ignore patterns. You can untrack such files with the
72`jj file untrack` command.
73
74
75## Workspaces
76
77You can have multiple working copies backed by a single repo. Use
78`jj workspace add` to create a new working copy. The working copy will have a
79`.jj/` directory linked to the main repo. The working copy and the `.jj/`
80directory together is called a "workspace". Each workspace can have a different
81commit checked out.
82
83Having multiple workspaces can be useful for running long-running tests in a one
84while you continue developing in another, for example. If needed,
85`jj workspace root` prints the root path of the current workspace.
86
87When you're done using a workspace, use `jj workspace forget` to make the repo
88forget about it. The files can be deleted from disk separately (either before or
89after).
90
91## Stale working copy
92
93Almost all commands go through three main steps:
94
951. Snapshot the working copy (which gets recorded as an operation)
962. Create new commits etc. "in memory" and record that as a new operation
973. Update the working copy to match the new operation, i.e. to the commit that
98 the operation says that `@` should point to
99
100If step 3 doesn't happen for some reason, the working copy is considered
101"stale". We can detect that because the working copy (`.jj/working_copy/`)
102keeps track of which operation it was last updated to. When the working copy is
103stale, use `jj workspace update-stale` to update the files in the working copy.
104
105A common reason that step 3 doesn't happen for a working copy is that you
106rewrote the commit from another workspace. When you modify workspace A's
107working-copy commit from workspace B, workspace A's working copy will become
108stale.
109
110A working copy can also become stale because some error, such as `^C` prevented
111step 3 from completing. It's also possible that it was successfully updated in
112step 3 but the operation has then been lost (e.g. by `jj op abandon` or
113"spontaneously" by certain storage backends). If the operation has been lost,
114then `jj workspace update-stale` will create a recovery commit with the
115contents of the working copy but parented to the current operation's
116working-copy commit.