git-p4son 0.6.0__tar.gz → 0.8.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. git_p4son-0.8.0/PKG-INFO +1353 -0
  2. git_p4son-0.8.0/README.md +1330 -0
  3. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/__init__.py +2 -2
  4. git_p4son-0.8.0/git_p4son/alias.py +163 -0
  5. git_p4son-0.8.0/git_p4son/backend.py +136 -0
  6. git_p4son-0.8.0/git_p4son/changelist_store.py +329 -0
  7. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/cli.py +195 -146
  8. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/common.py +102 -21
  9. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/complete.py +86 -40
  10. git_p4son-0.8.0/git_p4son/completions/git-p4son-jj.bash +53 -0
  11. git_p4son-0.8.0/git_p4son/completions/git-p4son-jj.ps1 +73 -0
  12. git_p4son-0.8.0/git_p4son/completions/git-p4son-jj.zsh +40 -0
  13. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/completions/git-p4son.bash +7 -2
  14. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/config.py +13 -48
  15. git_p4son-0.8.0/git_p4son/git.py +643 -0
  16. git_p4son-0.8.0/git_p4son/git_backend.py +191 -0
  17. git_p4son-0.8.0/git_p4son/hooks.py +61 -0
  18. git_p4son-0.8.0/git_p4son/included.py +131 -0
  19. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/init.py +86 -11
  20. git_p4son-0.8.0/git_p4son/jj.py +548 -0
  21. git_p4son-0.8.0/git_p4son/jj_backend.py +262 -0
  22. git_p4son-0.8.0/git_p4son/jj_lock.py +95 -0
  23. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/lib.py +82 -35
  24. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/list_changes.py +4 -2
  25. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/log.py +23 -4
  26. git_p4son-0.8.0/git_p4son/new.py +140 -0
  27. git_p4son-0.8.0/git_p4son/per_commit.py +120 -0
  28. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/perforce.py +60 -26
  29. git_p4son-0.8.0/git_p4son/review_tools.py +168 -0
  30. git_p4son-0.8.0/git_p4son/scripts.py +64 -0
  31. git_p4son-0.8.0/git_p4son/skill/SKILL.md +10 -0
  32. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/skill/git-p4son.md +106 -51
  33. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/sync.py +92 -82
  34. git_p4son-0.8.0/git_p4son/sync_branch.py +28 -0
  35. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/sync_merge.py +5 -2
  36. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/sync_split_users.py +13 -12
  37. git_p4son-0.8.0/git_p4son/toml_writer.py +54 -0
  38. git_p4son-0.8.0/git_p4son/update.py +195 -0
  39. git_p4son-0.8.0/git_p4son/words.py +27 -0
  40. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/writable.py +10 -9
  41. git_p4son-0.8.0/git_p4son.egg-info/PKG-INFO +1353 -0
  42. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son.egg-info/SOURCES.txt +24 -4
  43. {git_p4son-0.6.0 → git_p4son-0.8.0}/pyproject.toml +23 -3
  44. git_p4son-0.8.0/tests/test_alias.py +286 -0
  45. git_p4son-0.8.0/tests/test_catch_up.py +264 -0
  46. git_p4son-0.8.0/tests/test_changelist_store.py +436 -0
  47. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_cli.py +186 -91
  48. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_common.py +43 -3
  49. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_complete.py +47 -13
  50. git_p4son-0.8.0/tests/test_completion_scripts.py +199 -0
  51. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_config.py +2 -1
  52. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_git.py +173 -60
  53. git_p4son-0.8.0/tests/test_git_backend.py +188 -0
  54. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_hooks.py +19 -85
  55. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_init.py +270 -12
  56. git_p4son-0.8.0/tests/test_isolation.py +39 -0
  57. git_p4son-0.8.0/tests/test_jj.py +952 -0
  58. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_lib.py +122 -17
  59. git_p4son-0.8.0/tests/test_list_changes.py +50 -0
  60. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_log.py +38 -2
  61. git_p4son-0.8.0/tests/test_new.py +560 -0
  62. git_p4son-0.8.0/tests/test_per_commit.py +187 -0
  63. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_perforce.py +60 -24
  64. git_p4son-0.8.0/tests/test_review_tools.py +216 -0
  65. git_p4son-0.8.0/tests/test_scripts.py +89 -0
  66. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_sync.py +206 -161
  67. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_sync_merge.py +8 -8
  68. git_p4son-0.8.0/tests/test_toml_writer.py +35 -0
  69. git_p4son-0.8.0/tests/test_update.py +513 -0
  70. git_p4son-0.6.0/PKG-INFO +0 -932
  71. git_p4son-0.6.0/README.md +0 -909
  72. git_p4son-0.6.0/git_p4son/alias.py +0 -126
  73. git_p4son-0.6.0/git_p4son/changelist_store.py +0 -130
  74. git_p4son-0.6.0/git_p4son/git.py +0 -396
  75. git_p4son-0.6.0/git_p4son/hooks.py +0 -112
  76. git_p4son-0.6.0/git_p4son/new.py +0 -38
  77. git_p4son-0.6.0/git_p4son/rebase_todo.py +0 -158
  78. git_p4son-0.6.0/git_p4son/review.py +0 -36
  79. git_p4son-0.6.0/git_p4son/skill/SKILL.md +0 -8
  80. git_p4son-0.6.0/git_p4son/update.py +0 -59
  81. git_p4son-0.6.0/git_p4son.egg-info/PKG-INFO +0 -932
  82. git_p4son-0.6.0/tests/test_alias.py +0 -195
  83. git_p4son-0.6.0/tests/test_changelist_store.py +0 -190
  84. git_p4son-0.6.0/tests/test_list_changes.py +0 -31
  85. git_p4son-0.6.0/tests/test_new.py +0 -131
  86. git_p4son-0.6.0/tests/test_rebase_todo.py +0 -219
  87. git_p4son-0.6.0/tests/test_review.py +0 -111
  88. git_p4son-0.6.0/tests/test_update.py +0 -211
  89. {git_p4son-0.6.0 → git_p4son-0.8.0}/LICENSE +0 -0
  90. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/__main__.py +0 -0
  91. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/completions/_git-p4son +0 -0
  92. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/completions/git-p4son.ps1 +0 -0
  93. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/depot.py +0 -0
  94. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/description.py +0 -0
  95. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/processes.py +0 -0
  96. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son/skill.py +0 -0
  97. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son.egg-info/dependency_links.txt +0 -0
  98. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son.egg-info/entry_points.txt +0 -0
  99. {git_p4son-0.6.0 → git_p4son-0.8.0}/git_p4son.egg-info/top_level.txt +0 -0
  100. {git_p4son-0.6.0 → git_p4son-0.8.0}/setup.cfg +0 -0
  101. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_depot.py +0 -0
  102. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_description.py +0 -0
  103. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_processes.py +0 -0
  104. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_skill.py +0 -0
  105. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_sync_split_users.py +0 -0
  106. {git_p4son-0.6.0 → git_p4son-0.8.0}/tests/test_writable.py +0 -0
@@ -0,0 +1,1353 @@
1
+ Metadata-Version: 2.4
2
+ Name: git-p4son
3
+ Version: 0.8.0
4
+ Summary: Utility for keeping a Perforce workspace and local git or jj repo in sync
5
+ Author-email: Andreas Andersson <andreas@neoboid.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/neoboid/git-p4son
8
+ Project-URL: Repository, https://github.com/neoboid/git-p4son
9
+ Project-URL: Issues, https://github.com/neoboid/git-p4son/issues
10
+ Project-URL: Changelog, https://github.com/neoboid/git-p4son/blob/main/CHANGELOG.md
11
+ Keywords: perforce,git,jj,jujutsu,version-control,sync
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Version Control
19
+ Requires-Python: >=3.11
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Dynamic: license-file
23
+
24
+ # Git Perforcesson
25
+
26
+ `git-p4son` lets you work in a Perforce workspace with a local git repository, or a colocated
27
+ [Jujutsu (jj)](#jujutsu-jj) one, so you can use the familiar local development flow even though your project uses
28
+ Perforce for source control.
29
+
30
+ A `main` branch (a bookmark in jj) is kept in sync with your Perforce workspace, one commit per changelist. You work
31
+ on feature branches or jj changes and rebase them onto `main` after a sync; with jj, `sync` rebases the change you
32
+ sync from for you.
33
+
34
+ When your changes are ready, `git-p4son` creates the changelist and shelves it for a Swarm review. It can post each
35
+ commit as a patch of its own, so reviewers see the changes in the order you made them, much like a pull request.
36
+ Updates fold in only the new commits.
37
+
38
+ With jj, `git-p4son` works on the jj change: the changelist's alias follows the change through rewrites, the message
39
+ comes from its description, and `jj p4son` runs every command.
40
+
41
+ ## On big workspaces
42
+ Sometimes git struggles to keep entire perforce workspaces in the repo, like when working
43
+ on a Unreal Engine game with all source code in the workspace. If so, it helps to edit
44
+ `.gitignore` and include only the subdirectories in which you work, the rest of the files
45
+ will still be managed by perforce of course.
46
+
47
+ ## Usage Example
48
+
49
+ Here's a typical workflow when developing a feature using `git-p4son`:
50
+
51
+ ```sh
52
+ # Sync main with latest changes from perforce
53
+ git checkout main
54
+ git p4son sync
55
+
56
+ # Start work on a new feature
57
+ git checkout -b my-fancy-feature
58
+
59
+ # Change some code
60
+ git add .
61
+ git commit -m "Feature part1"
62
+
63
+ # Sync to the latest changelist affecting the workspace
64
+ git checkout main
65
+ git p4son sync
66
+
67
+ # Rebase your changes on main
68
+ git checkout my-fancy-feature
69
+ git rebase main
70
+
71
+ # Change even more code
72
+ git add .
73
+ git commit -m "Feature part2"
74
+
75
+ # Create a Swarm review with all commits since main in one go.
76
+ # Each commit is checked out in turn and gets a shelf of its own in the
77
+ # review, then you are back on your branch.
78
+ # An alias called "my-fancy-feature" (derived from the branch name) is
79
+ # saved so you can refer to this CL by name in follow-up commands.
80
+ git p4son review -m "My fancy feature" -b main
81
+
82
+ # After review feedback, make more changes
83
+ git add .
84
+ git commit -m "Address review feedback"
85
+
86
+ # Update the changelist with latest commit, re-open files, and re-shelve.
87
+ # The changelist is looked up by branch name automatically.
88
+ git p4son update --shelve
89
+
90
+ # After approval, submit in p4v
91
+
92
+ # Sync to the latest changelist from perforce
93
+ git checkout main
94
+ git p4son sync
95
+
96
+ # Force remove old branch as you don't need it anymore
97
+ git branch -D my-fancy-feature
98
+
99
+ # Remove changelist alias for the branch
100
+ git p4son alias delete my-fancy-feature
101
+
102
+ # Start working on the next feature
103
+ git checkout -b my-next-fancy-feature
104
+ ```
105
+
106
+ ### With jj
107
+
108
+ The same workflow in a [colocated jj workspace](#jujutsu-jj), with the [`jj p4son` alias](#the-jj-p4son-alias):
109
+
110
+ ```sh
111
+ # Start work on a new feature
112
+ jj new main -m "Feature part1"
113
+ # Change some code, which jj snapshots into the change
114
+
115
+ # Sync main from any change: the change you are on is rebased onto it
116
+ jj p4son sync
117
+
118
+ # Change even more code in a change of its own
119
+ jj new -m "Feature part2"
120
+ jj bookmark create my-fancy-feature
121
+
122
+ # Create a Swarm review with every change since main, one shelf each.
123
+ # The alias is named after the bookmark and records the jj change.
124
+ jj p4son review -m "My fancy feature" -b main
125
+
126
+ # After review feedback, add a change and move the bookmark to it
127
+ jj new -m "Address review feedback"
128
+ jj bookmark set my-fancy-feature -r @
129
+ jj p4son update --shelve
130
+
131
+ # After approval, submit in p4v, then abandon the submitted changes before
132
+ # syncing, which deletes the bookmark too
133
+ jj abandon main..my-fancy-feature
134
+ jj p4son alias delete my-fancy-feature
135
+ jj p4son sync
136
+
137
+ # Start working on the next feature
138
+ jj new main -m "Next fancy feature"
139
+ ```
140
+
141
+ `sync` only rebases the change you sync from, and the stack above it. Bring other bookmarks up to date with
142
+ `jj rebase -b <bookmark> -d main`.
143
+
144
+ ## Installation
145
+
146
+ ```sh
147
+ pip install git-p4son
148
+ ```
149
+
150
+ Requires Python 3.11 or later.
151
+
152
+ ### Updating
153
+
154
+ ```sh
155
+ pip install --upgrade git-p4son
156
+ ```
157
+
158
+ For tab completion (zsh and PowerShell), see [Shell Completions](#shell-completions). To let Claude Code drive
159
+ git-p4son, see [Claude Code Skill](#claude-code-skill).
160
+
161
+ ## Development
162
+
163
+ To install from source in editable mode:
164
+
165
+ ```sh
166
+ git clone https://github.com/neoboid/git-p4son.git
167
+ cd git-p4son
168
+ pip install -e .
169
+ ```
170
+
171
+ The `-e` flag installs the package in "editable" mode, meaning changes to the code are immediately available
172
+ without reinstalling. This is also handy if you want to auto-update git-p4son whenever you pull from GitHub.
173
+
174
+ git-p4son only uses Python standard library modules - no additional packages are required.
175
+
176
+ Run the tests with `python -m pytest tests/` (`pip install pytest`). With `pytest-xdist` installed, add
177
+ `-n auto --maxprocesses 8` to run them in parallel, which is about three times faster.
178
+
179
+ ### Git Hooks
180
+
181
+ The repository includes git hooks in the `hooks/` directory:
182
+
183
+ - **pre-commit** - verifies that staged Python files are formatted with `autopep8`. Install it with
184
+ `pip install autopep8`.
185
+ - **pre-push** - runs the test suite and blocks the push if any test fails. It needs `pytest` installed, and runs
186
+ the tests in parallel when `pytest-xdist` is too.
187
+
188
+ To activate the hooks, run:
189
+
190
+ ```sh
191
+ scripts/setup-hooks.sh
192
+ ```
193
+
194
+ This configures `core.hooksPath` so git uses the hooks from the repository. You only need to run this once after
195
+ cloning.
196
+
197
+ ## Setup
198
+
199
+ These steps set up git-p4son in an existing Perforce workspace. You only need to do this once.
200
+
201
+ 1. **Sync your workspace to a known changelist.** Pick a changelist to use as the starting point for your git
202
+ history:
203
+ ```sh
204
+ p4 sync //...@12345
205
+ ```
206
+
207
+ 2. **Run `git p4son init`.** This can be anywhere inside your Perforce workspace - it doesn't have to be at the
208
+ root:
209
+ ```sh
210
+ cd /path/to/your/workspace # or a subdirectory of it
211
+ git p4son init
212
+ ```
213
+ The command verifies that you are inside a P4 workspace, prompts you to select a depot
214
+ root (entire workspace or current directory subtree), runs `git init`, sets up `.gitignore` (copying from
215
+ `.p4ignore` if available), and creates an initial commit.
216
+ With jj 0.41 or newer installed, it also offers to colocate jj and to add the `jj p4son` alias, see
217
+ [Jujutsu (jj)](#jujutsu-jj).
218
+
219
+ 3. **Review `.gitignore`.** Edit the file to ensure build artifacts and other unwanted files are excluded.
220
+
221
+ 4. **Add and commit all files manually the first time**
222
+ ```sh
223
+ git add .
224
+ git commit -m "Initial submit all files"
225
+ ```
226
+
227
+ 5. **Run `git p4son sync`** to get your first official sync commit
228
+ ```sh
229
+ git p4son sync
230
+ ```
231
+ This creates a commit with message that records the CL you have synced.
232
+
233
+ From here, branch off `main` for local development. See the [Usage Example](#usage-example) for a typical
234
+ workflow.
235
+
236
+ ### How sync handles writable files
237
+
238
+ When you switch branches with `git checkout`, git removes the read-only flag on every file it writes. This means
239
+ that when you switch back to `main` for a sync, Perforce may refuse to overwrite those files because they are
240
+ writable. git-p4son handles these automatically by classifying each writable file:
241
+
242
+ **writable-unchanged** - The file on disk is identical to the last sync (only the read-only flag was removed
243
+ by git). This is the common case after switching branches. git-p4son detects this by comparing git blob IDs against
244
+ the last sync commit that touched the file, restores the read-only flag, and lets the sync overwrite the file.
245
+
246
+ **writable-changed** - The file on disk differs from the last sync. This happens when you manually edit a file
247
+ on `main` and commit it to git without submitting to Perforce. git-p4son lets the sync overwrite the file and
248
+ includes it in the sync commit (so the commit reflects pure Perforce state), then three-way merges your local
249
+ changes on top of the new Perforce content - similar to a `git rebase`. If the merge is clean, the result appears
250
+ as an unstaged change. If there are conflicts, standard conflict markers are inserted for you to resolve.
251
+
252
+ **added both locally and in Perforce** - A file you committed to git is also being added by Perforce (p4 has never
253
+ synced it to your workspace). There is no common baseline, so git-p4son merges the two versions against an empty
254
+ base: identical content merges cleanly, otherwise the file gets a single conflict block containing both full
255
+ versions for you to resolve.
256
+
257
+ **binary files** - Binary files that have local changes cannot be three-way merged. git-p4son restores your local
258
+ version to disk after the sync commit so it shows up in `git status` for you to handle manually.
259
+
260
+ **added locally, deleted upstream** - A file with local changes in git was deleted in Perforce. git-p4son lets the
261
+ delete stand and warns you - your version remains available in git history.
262
+
263
+ **deleted locally, added upstream** - A file you deleted from git was modified in Perforce. The Perforce version is
264
+ kept in the sync commit. You can delete it again if you want.
265
+
266
+ **ignored** - Files ignored by `.gitignore` are skipped with a warning. These are outside git's domain and should
267
+ be managed manually or via Perforce directly.
268
+
269
+ After syncing, git-p4son prints a summary of how each writable file was handled, and instructs you to review and
270
+ commit any files that need attention.
271
+
272
+ **Workspaces with `allwrite`** - When your client spec has the `allwrite` option, every file is writable by design,
273
+ so the read-only flag carries no information about local changes. git-p4son classifies files exactly as above (the
274
+ verdict comes from git, not from the flag), but leaves the write bit alone on files it finds unchanged: Perforce
275
+ compares digests before refusing to overwrite a writable file, and unchanged files pass that check. Only files with
276
+ local changes are made read-only for the duration of the sync, since those are the ones Perforce would otherwise
277
+ refuse to overwrite. The same digest check applies to git-ignored files: unchanged ones sync normally, and after the
278
+ sync git-p4son lists the ones Perforce skipped because they were modified locally.
279
+
280
+ **Writable mode** - With [writable mode](#writable-command) on, the files a sync touches are made writable again after
281
+ the sync if git tracks them. The sync itself works as described above, since the workspace is not `allwrite`.
282
+
283
+ ## Configuration
284
+
285
+ git-p4son keeps its per-repository settings in `.git-p4son/config.toml`. `init`, `writable` and `sync-split-users`
286
+ write most of them; the rest you edit by hand.
287
+
288
+ - `[depot] root` (string, set by `init`): the depot path `sync` syncs, e.g. `//$(workspace)` or
289
+ `//$(workspace)/Engine`. See [Init Command](#init-command)
290
+ - `[core] writable` (`true` or `false`, default `false`): [writable mode](#writable-command), which keeps
291
+ git-tracked files writable
292
+ - `[core] backend` (`"auto"`, `"git"` or `"jj"`, default `"auto"`): the tool git-p4son follows for the change, the
293
+ base and the branch. `auto` means jj in a [jj workspace](#jujutsu-jj) and git otherwise
294
+ - `[sync] branch` (string, set by `init`): the sync branch, which `sync` commits onto from whatever branch you are
295
+ on. Without it, `sync` uses `main`. See [Sync Command](#sync-command)
296
+ - `[sync] split-users` (list of strings, default empty): the users whose changelists `sync` gives a commit each;
297
+ `$(user)` stands for you. See [Split users](#split-users)
298
+ - `[sync] blocking-processes` (list of strings, default empty): processes that stop a sync while they run. See
299
+ [Blocking processes](#blocking-processes)
300
+ - `[review-tool] default` (string, default `"swarm"`): the [review tool](#review-tools) `new --review` and `review`
301
+ push to without `--review-tool`
302
+ - `[review-tool.<name>]` (table): a [review tool](#review-tools)'s `command`, and its `new` and `update` arguments
303
+ - `[core.script-runners]` (table, Windows only): the command that runs a hook script, by file extension.
304
+ See [Hooks](#hooks). The old `[hooks.extension-associations]` is still read, and `core.script-runners` wins where
305
+ both name an extension
306
+
307
+ For example:
308
+
309
+ ```toml
310
+ [depot]
311
+ root = "//$(workspace)"
312
+
313
+ [core]
314
+ writable = true
315
+
316
+ [sync]
317
+ split-users = ["$(user)", "alice"]
318
+ blocking-processes = ["UnrealEditor"]
319
+ ```
320
+
321
+ A value of the wrong type, such as `writable = "true"` or `split-users = "alice"`, or a file that is not valid TOML,
322
+ stops the command with an error naming the setting, so a typo is never silently ignored.
323
+
324
+ ## Usage
325
+
326
+ git-p4son provides eleven commands: `init`, `sync`, `sync-split-users`, `new`, `update`, `review`,
327
+ `list-changes`, `alias`, `writable`, `completion`, and `skill`.
328
+
329
+ To see help for any command, use `-h`:
330
+
331
+ ```sh
332
+ git p4son -h
333
+ git p4son sync -h
334
+ ```
335
+
336
+ **Note:** When invoking via `git p4son`, the `--help` flag is intercepted by git (to look for man pages). Use `-h`
337
+ instead, or `git p4son -- --help` to force it through.
338
+ Alternatively, call the executable directly: `git-p4son --help`.
339
+
340
+ **Global options:**
341
+ - `-v, --verbose`: Show verbose output (commands, elapsed times, raw subprocess output)
342
+ - `--version`: Show program version
343
+
344
+ ### Init Command
345
+
346
+ Initialize a git repository inside a Perforce workspace:
347
+
348
+ ```sh
349
+ git p4son init
350
+ ```
351
+
352
+ This command checks that it runs in a Perforce workspace, then asks for the depot root, writable mode, split users,
353
+ the Claude Code skill and jj. It then sets up `.gitignore`, runs `git init` and creates a first commit holding only
354
+ `.gitignore`. It ends by listing the next steps.
355
+
356
+ The depot root determines which part of the Perforce workspace git-p4son syncs. You can choose to sync the entire
357
+ workspace or just the directory's subtree where the git root is placed. The selection is saved in
358
+ `.git-p4son/config.toml` and used by all subsequent commands.
359
+
360
+ Nothing in `.git-p4son/` belongs in git. The folder has its own `.gitignore` that ignores everything in it, so there
361
+ is no need to list it in the workspace `.gitignore`.
362
+
363
+ The saved root uses a `$(workspace)` placeholder for the workspace (client) name, e.g.
364
+ `root = "//$(workspace)/Engine"`. git-p4son substitutes the live workspace name each time it runs, so renaming
365
+ the Perforce workspace does not break the config. You can still store a concrete name (e.g. `//my-workspace/Engine`)
366
+ by hand-editing `config.toml`; both forms work.
367
+
368
+ The `.gitignore` is set up using this priority:
369
+ - If `.gitignore` already exists, it is left as is
370
+ - If `.p4ignore` exists, it is copied to `.gitignore` as a starting point
371
+ - Otherwise, an empty `.gitignore` is created
372
+
373
+ `init` also asks whether to turn on [writable mode](#writable-command), defaulting to the current setting. It only
374
+ saves the answer; run `git p4son writable apply` once your files are committed to update their permissions.
375
+
376
+ `init` then asks whether to sync your own changelists individually, making you a [split user](#split-users).
377
+ The default is the current setting. Yes adds a `$(user)` entry to the split users and no removes it; other split
378
+ users are left alone.
379
+
380
+ `init` records the [sync branch](#sync-command) as `[sync] branch`. In a repository it creates, that's the branch
381
+ `HEAD` is on. In an existing one, it's `main` if there is one, else the branch `HEAD` is on, else one you pick from
382
+ the local branches. It keeps a branch already set.
383
+
384
+ If Claude Code is installed, `init` offers to install the [Claude Code skill](#claude-code-skill). An
385
+ already installed skill is refreshed without asking.
386
+
387
+ With jj 0.41 or newer installed, `init` offers two things for [jj](#jujutsu-jj):
388
+
389
+ - **Colocating jj**, when the workspace has no `.jj` folder: "Use jj in this workspace too (colocated)?", default
390
+ no. On yes, in an existing repository it runs `jj git init --colocate` as its last step, so jj imports the branch
391
+ as a bookmark. It sets jj's [line endings](#line-endings) to match git's from jj's first snapshot on. In a
392
+ repository it creates, it lists the same commands as next steps after your initial commit instead, since jj would
393
+ otherwise snapshot every file before you have reviewed `.gitignore`.
394
+ - **The [`jj p4son` alias](#the-jj-p4son-alias)**, when the workspace has a `.jj` folder, or is to get one, and
395
+ jj's config has no `aliases.p4son`: default yes. It adds the alias to jj's user config.
396
+
397
+ Running `init` again asks neither once they are done.
398
+
399
+ ### Sync Command
400
+
401
+ Sync local git repository with a Perforce workspace:
402
+
403
+ ```sh
404
+ git p4son sync [changelist ...] [--branch BRANCH] [--force] [--dry-run] [--split-user NAME ...] [--no-split]
405
+ [--ignore-blocking-processes]
406
+ ```
407
+
408
+ `sync` commits onto the sync branch, `[sync] branch` in `.git-p4son/config.toml`, which `init` sets and which
409
+ defaults to `main`. From another branch, it checks the sync branch out, syncs and commits, then returns you to
410
+ where you started, telling you to `git rebase` your branch onto the sync branch; it doesn't rebase for you. The
411
+ pre-sync and post-sync hooks run on the sync branch. You stay on the sync branch when:
412
+
413
+ - local changes were [merged back](#how-sync-handles-writable-files) into the work tree, for you to review and
414
+ commit there
415
+ - a sync fails partway, with the files as Perforce left them and the commits so far kept
416
+
417
+ A failing pre-sync hook, or anything else that stops `sync` before it syncs, returns you to where you started.
418
+
419
+ **Arguments:**
420
+ - `changelist` (optional): Changelist number, `last-synced` to re-sync the last synced changelist, or `head`
421
+ to sync to the latest changelist. Omit to sync to the latest changelist affecting the workspace. Several
422
+ strictly increasing changelist numbers may be given to sync each in sequence, producing one commit per
423
+ changelist. A trailing `head` may close out such a sequence to finish at the latest changelist.
424
+
425
+ `sync` requires clean git and Perforce workspaces: no uncommitted changes, untracked files included, and no
426
+ git-tracked files opened in Perforce. It checks them after any [blocking processes](#blocking-processes) and before
427
+ the [pre-sync hooks](#pre-sync-hook).
428
+
429
+ **Options:**
430
+ - `--branch BRANCH`: Commit onto this branch instead of `[sync] branch`. With the jj backend, the bookmark to move
431
+ to each sync commit
432
+ - `--no-rebase`: With the jj backend, leave the changes you started from where they are, instead of rebasing them
433
+ onto the [sync bookmark](#syncing-a-bookmark)
434
+ - `-f, --force`: Allow syncing to changelists older than the current one
435
+ - `-n, --dry-run`: Print the resolved sync sequence without syncing. The arguments are validated as for a
436
+ real sync, but nothing else runs: no clean-workspace checks, no hooks, and no prompts. Ends with
437
+ `Dry run, nothing changed`
438
+ - `-u, --split-user NAME`: Also split out this user's changelists, on top of the configured
439
+ [split users](#split-users). Repeat to give several users. Each name is checked against the Perforce server.
440
+ - `--no-split`: Ignore the configured split users for this sync. Users given with `--split-user` are still split
441
+ out, so `--no-split -u alice` splits out only alice's changelists.
442
+ - `--ignore-blocking-processes`: Sync even while a [blocking process](#blocking-processes) is running.
443
+
444
+ **Examples:**
445
+ ```sh
446
+ git p4son sync # sync to latest
447
+ git p4son sync head # sync to latest (explicit)
448
+ git p4son sync 12345
449
+ git p4son sync 123 156 178 # sync each changelist in sequence, one commit each
450
+ git p4son sync 123 156 head # sync 123, 156, then the latest changelist
451
+ git p4son sync last-synced
452
+ git p4son sync 12345 --force
453
+ git p4son sync --dry-run # show the changelists a sync to latest would visit
454
+ git p4son sync -u alice # also split out alice's changelists
455
+ git p4son sync --no-split # sync without splitting out the configured split users
456
+ git p4son sync --branch p4 # commit onto the p4 branch this time
457
+ ```
458
+
459
+ #### Blocking processes
460
+
461
+ Syncing while e.g. the Unreal editor is open lets p4 replace assets the editor still has loaded, so the editor
462
+ keeps working against files that no longer match what is on disk. List such processes in `.git-p4son/config.toml`
463
+ and `sync` refuses to start while any of them is running:
464
+
465
+ ```toml
466
+ [sync]
467
+ blocking-processes = ["UnrealEditor", "UnrealLightmass"]
468
+ ```
469
+
470
+ Names are matched with any `.exe` suffix stripped and case ignored, so a single entry covers `UnrealEditor.exe` on
471
+ Windows and `UnrealEditor` on macOS. The check runs before the clean-workspace checks and the pre-sync hooks. A
472
+ [malformed setting](#configuration), or a process list that cannot be read, aborts the sync rather than silently
473
+ skipping the check.
474
+
475
+ Pass `--ignore-blocking-processes` to sync once without the check, or remove the setting to turn it off for good.
476
+
477
+ #### Split users
478
+
479
+ Syncing straight to the latest changelist lumps your own submitted changelists together with everyone else's in a
480
+ single commit. Split users fix that: for each changelist a split user submitted since the last sync, `sync` first
481
+ syncs the changelist submitted immediately before it, so every changelist they submitted becomes a commit containing
482
+ nothing but their own change.
483
+
484
+ The split users are stored in `.git-p4son/config.toml`, and edited with the
485
+ [`sync-split-users` command](#sync-split-users-command) or by answering yes in `init`:
486
+
487
+ ```toml
488
+ [sync]
489
+ split-users = ["$(user)", "alice"]
490
+ ```
491
+
492
+ `$(user)` stands for the current Perforce user (from `p4 info`), resolved each time `sync` runs, so the config
493
+ survives a change of user, the same way `$(workspace)` works in the depot root.
494
+
495
+ For example, with the last sync at CL 100, your own changelists at 102 and 105, and the latest changelist at 106,
496
+ `sync` visits `101 102 104 105 106`, producing five commits where CL 102 and CL 105 each hold only your change.
497
+ Changelists given on the command line are all still visited, with the split points merged in: `sync 103 head`
498
+ visits `101 102 103 104 105 106`.
499
+
500
+ Splitting only moves forward from a previous sync. The first sync, `last-synced`, and syncing to an older changelist
501
+ with `--force` are never split. Without any split users, `sync` makes no extra Perforce queries.
502
+
503
+ Finding the split users' changelists costs one Perforce query per split user, listing their changelists in the range
504
+ being synced, then one batched query that checks each changelist found touched the workspace and finds the one before
505
+ it. None of them scans the files of every changelist in the range, which on a large range can exceed the server's
506
+ `maxscanrows`. They run after the blocking processes check, the clean-workspace checks and the pre-sync hooks, so a
507
+ running blocking process, a dirty workspace or a hook that aborts the sync says so before that work. `--dry-run` skips
508
+ the checks and hooks but still shows the resulting sequence.
509
+
510
+ #### Hooks
511
+
512
+ `sync` runs the [pre-sync](#pre-sync-hook) and [post-sync](#post-sync-hook) hooks.
513
+
514
+ ### Sync-Split-Users Command
515
+
516
+ Show or edit the [split users](#split-users), the Perforce users whose changelists `sync` gives a commit each:
517
+
518
+ ```sh
519
+ git p4son sync-split-users # list the split users (same as list)
520
+ git p4son sync-split-users list
521
+ git p4son sync-split-users add --me # add yourself, stored as $(user)
522
+ git p4son sync-split-users add alice bob
523
+ git p4son sync-split-users delete alice
524
+ git p4son sync-split-users delete --me
525
+ ```
526
+
527
+ - `list` prints one user per line. `$(user)` is shown with the name it stands for, e.g. `$(user) (alice)`.
528
+ - `add` checks every name against the Perforce server first, since a misspelled name would never match a
529
+ changelist. If any name is not a Perforce user, nothing is added. Names are stored as the server spells them,
530
+ and a name that is already a split user is skipped.
531
+ - `delete` removes names regardless of case. If any name is not a split user, nothing is removed.
532
+
533
+ `--me` adds or removes the `$(user)` entry. A quoted `'$(user)'` does the same, but the quotes matter: unquoted,
534
+ bash, zsh and PowerShell run `$(user)` as a command substitution.
535
+
536
+ ### New Command
537
+
538
+ Create a new Perforce changelist and add changed files to it. Description will contain an enumerated list of git commits
539
+ since the base branch. Optionally creates a review, in Swarm or another [review tool](#review-tools).
540
+
541
+ Opening files requires a clean git workspace, untracked files included; `new` refuses to run otherwise. The check
542
+ is skipped with `--no-edit`. After opening files, unchanged ones are reverted (see
543
+ [Keeping the changelist in sync with git](#keeping-the-changelist-in-sync-with-git)).
544
+
545
+ ```sh
546
+ git p4son new -b BASE_BRANCH [-m <message> | -F <file>] [alias] [--force] [--dry-run] [--no-edit]
547
+ [--no-alias] [--no-commit-list] [--shelve] [--review] [--review-tool NAME] [--per-commit]
548
+ ```
549
+
550
+ **Arguments:**
551
+ - `alias` (optional): Alias name to save the new changelist number under. Defaults to the current branch name.
552
+
553
+ **Options:**
554
+ - `-m, --message MESSAGE`: Changelist description message. Defaults to the HEAD commit subject
555
+ - `-F, --file FILE`: Read the changelist description message from a file instead of `-m`. The message may span
556
+ multiple lines
557
+ - `--no-commit-list`: Leave the enumerated commit list out of the changelist description, so it holds only the
558
+ message
559
+ - `-b, --base-branch BASE_BRANCH`: Required. The base the change starts from, for enumerating commits and finding
560
+ changed files: a branch or bookmark, or a commit exactly one points at. The alias records it by name, as a commit
561
+ would go stale after a sync and rebase, along with the commits since it the changelist includes, so `update`
562
+ knows where the next ones start. With `--no-alias` any commit will do
563
+ - `-f, --force`: Overwrite an existing alias file
564
+ - `-n, --dry-run`: Pretend and print what would be done, but do not execute. Ends with `Dry run, nothing changed`
565
+ - `--no-edit`: Skip opening changed files for edit in Perforce
566
+ - `--no-alias`: Skip saving a changelist alias
567
+ - `--shelve`: Shelve the changelist after creating it
568
+ - `--review`: Shelve and create a review with the default [review tool](#review-tools), Swarm unless
569
+ `[review-tool] default` names another. For Swarm, adds the `#review` keyword
570
+ - `--review-tool NAME`: Push the review to this review tool instead of the default one: `swarm`, or a
571
+ `[review-tool.NAME]` in `.git-p4son/config.toml`. Implies `--review`. The alias records the tool, which
572
+ `update --shelve` then runs
573
+ - `--per-commit`: Create the changelist on the first commit since the base branch, then update it once per later
574
+ commit, as described below. Refuses `--no-edit` and `--no-alias`
575
+
576
+ With `--per-commit`, `new` checks out the first commit since the base branch and runs `git p4son new` on it, then
577
+ checks out each later commit and runs `git p4son update` on it, and finally returns to where you started. With
578
+ `--shelve` or `--review`, every step shelves, so each commit shows up as its own patch in the review. With Swarm,
579
+ every step but the last sleeps 5 seconds to give Perforce/Swarm time to process the shelf; another review tool runs
580
+ once per step instead. It needs a clean git workspace even with `--dry-run`. [`review`](#review-command) is
581
+ `new --review --per-commit`, and describes the steps, the dry run and resuming after a failed step.
582
+
583
+ **Examples:**
584
+ ```sh
585
+ git p4son new -m "Add feature" -b main
586
+ git p4son new -m "Fix bug" myalias -b main
587
+ git p4son new -m "Fix bug" --no-alias -b HEAD~1
588
+ git p4son new -m "New feature" --review -b main
589
+ git p4son new -m "New feature" --shelve --per-commit -b main # a shelf per commit, without a Swarm review
590
+ ```
591
+
592
+ ### Update Command
593
+
594
+ Update an existing Perforce changelist with the commits it doesn't include yet. The message above the commit list
595
+ is kept unless `-m` or `-F` replaces it. By default also opens changed files for edit, and reverts files that are no
596
+ longer part of the git change (see
597
+ [Keeping the changelist in sync with git](#keeping-the-changelist-in-sync-with-git)). Opening files requires a
598
+ clean git workspace, untracked files included; `update` refuses to run otherwise. The check is skipped with
599
+ `--no-edit`.
600
+
601
+ **Changelists made by `new` or `review`.** Their alias records the base, by name, and the commits since it the
602
+ changelist includes, by their jj change IDs or, with git, their author dates, which survive rebases and amends.
603
+ `update` folds in the commits it doesn't know: it appends their subjects to the commit list, opens their files, and
604
+ records them. The entries the list already has are left as they are, so an entry you reworded in the changelist
605
+ stays as you wrote it. Every update counts, shelved or not.
606
+
607
+ - `-b` only chooses which files to open, from that commit on, for example `-b main` to open them all again after a
608
+ manual `p4 revert`. The commit list is still only appended to. A `-b` above the last included commit is refused,
609
+ as the commits it skips would be counted without being opened.
610
+ - An included commit that is gone from the branch, dropped or squashed into another, gets a warning, and the update
611
+ goes on with the new commits. Its patch stays in the review: to undo a shelved commit, revert it in a new commit.
612
+ - A new commit below included ones is refused, as its own patch would undo the included commits above it. Move it
613
+ after them, then update again.
614
+ - An amend, or a squash into an included commit, keeps the commit's identity, so `update` sees no new commit. With
615
+ nothing new, `update` opens every file since the base, which takes in what the amend added. With new commits as
616
+ well, run `update -b main` to open them.
617
+
618
+ **After a sync.** A shelf holds whole files, so once a sync has changed files the changelist touches, its next shelf
619
+ would mix those changes into the next commit's patch. So when `update --shelve` finds that the base moved since the
620
+ last shelve, the branch was rebased onto it, and it changed such a file, it first inserts an empty commit, `Rebase
621
+ onto CL <N>`, right after the last included commit, with the commits after it rebased onto it. Its shelf is a patch
622
+ of its own, holding what the sync changed, and its entry keeps the commit list matching the patches.
623
+
624
+ - With `--per-commit`, it's the first step. Without it, `update --shelve` shelves twice: at the rebase commit, then at
625
+ the tip.
626
+ - An update without `--shelve` leaves the catch-up to the next one that shelves, and a changelist that was never
627
+ shelved has no patches to catch up. A dry run says what it would insert.
628
+
629
+ **Other changelists**, whose alias records nothing (made by `alias new` or an older git-p4son), or named by a number
630
+ no alias holds: the commits since the base branch, `HEAD~1` by default, replace their existing entries in the
631
+ commit list (matched by subject) and new ones are appended; entries outside the range are kept and the list is
632
+ renumbered.
633
+
634
+ With `--per-commit`, `update` runs once per commit instead of once for the whole range, the way `new --per-commit`
635
+ and `review` do after creating the changelist. It checks out each commit in turn, oldest first, runs the update on
636
+ it, and returns to where you started. With `--shelve`, every commit gets a shelf of its own and so shows up as its
637
+ own patch in the Swarm review.
638
+
639
+ - **With a record,** plain `update --per-commit --shelve` runs on exactly the commits the changelist doesn't include
640
+ yet. `-b` is refused there, as it would shelve included commits again.
641
+ - **Without one,** pass the range: `update -b HEAD~2 --per-commit --shelve` updates the changelist with the last two
642
+ commits, one at a time. The base is resolved once, before the first step, so a relative base like `HEAD~2` means
643
+ the same commit for every step.
644
+
645
+ `-m`/`-F` is applied on the first step only. It needs a clean git workspace, also with `--no-edit`. If a step
646
+ fails, `update` returns to where you started and names the step and commit that failed. The error ends with the
647
+ command that resumes after the last commit that worked, so earlier commits get no second shelf; with a record,
648
+ running the same command again does the same.
649
+
650
+ ```sh
651
+ git p4son update [changelist] [-m <message> | -F <file>] [--base-branch BASE_BRANCH] [--dry-run]
652
+ [--no-commit-list] [--no-edit] [--shelve] [--per-commit]
653
+ ```
654
+
655
+ **Arguments:**
656
+ - `changelist` (optional): Changelist number or named alias to update. Defaults to the current branch name.
657
+
658
+ **Options:**
659
+ - `-m, --message MESSAGE`: Replace the changelist description message above the commit list. The commit list is
660
+ kept and updated as usual, and so is a Swarm `#review` keyword on a line of its own at the end of the description
661
+ - `-F, --file FILE`: Like `-m`, but read the message from a file. The message may span multiple lines
662
+ - `-b, --base-branch BASE_BRANCH`: Where the commits to fold in start, for the commit list and the files to open.
663
+ Defaults to after the last commit the changelist includes, when its alias records that, else to `HEAD~1`
664
+ - `-n, --dry-run`: Pretend and print what would be done, but do not execute. Ends with `Dry run, nothing changed`
665
+ - `--no-commit-list`: Leave the enumerated commit list as it is. Without `-m` or `-F` the description is not
666
+ touched at all
667
+ - `--no-edit`: Skip opening changed files for edit in Perforce. With a record, the new commits are then neither
668
+ appended nor counted, so the next update that opens files includes them
669
+ - `--shelve`: Re-shelve the changelist after updating. For a review in a [review tool](#review-tools) other than
670
+ Swarm, as the alias records it, the tool then runs for the new shelf
671
+ - `--per-commit`: Update the changelist once per commit it doesn't include yet, or since the base branch without
672
+ a record, oldest first, with each commit checked out in turn. With `--shelve`, steps sleep 5 seconds between them
673
+ to give Perforce/Swarm time to process each shelf, unless another review tool has the changelist. `--dry-run`
674
+ prints the steps, one per commit
675
+
676
+ **Examples:**
677
+ ```sh
678
+ git p4son update # fold the new commits into the changelist for the current branch
679
+ git p4son update --shelve # update and re-shelve
680
+ git p4son update 12345
681
+ git p4son update myalias -b main # open every file of the change again
682
+ git p4son update -F description.txt # replace the message, e.g. after review feedback
683
+ git p4son update --per-commit --shelve # one shelf for each commit the changelist doesn't include yet
684
+ git p4son update 12345 -b HEAD~2 --per-commit --shelve # no record: the last two commits
685
+ ```
686
+
687
+ ### Keeping the changelist in sync with git
688
+
689
+ `new` and `update` open every file changed since the base branch in the changelist. A file can later stop being
690
+ part of the change, for example when a later commit undoes an edit, or a file is added in one commit and deleted
691
+ in the next. Such files would otherwise stay opened as no-ops, so after opening files both commands revert them:
692
+
693
+ - Files opened for edit that are unchanged compared to the depot are reverted with `p4 revert -a`. Changed files
694
+ stay opened.
695
+ - Files opened for add that are missing from disk are reverted.
696
+ - Files opened for delete that git still has (deleted in one commit, restored in a later one) are reverted and
697
+ restored from git.
698
+
699
+ Only files git-p4son has authority over are touched: files tracked by git, and files opened for add that are
700
+ missing from disk. Anything else in the changelist, such as binaries that only exist in Perforce and were opened
701
+ by hand, is left alone even when unchanged. Files opened with other actions (`move/add`, `integrate`, ...) are
702
+ also left alone. This step is skipped with `--no-edit`.
703
+
704
+ Shelving (`--shelve`, `--review`) replaces the whole shelf with the changelist's opened files using
705
+ `p4 shelve -r -a leaveunchanged`, so the shelf never holds stale files, and unchanged files that are still opened
706
+ are left out of it.
707
+
708
+ ### Review Command
709
+
710
+ Create a review with one shelf per commit. `review` is short for `git p4son new --review --per-commit`, taking the
711
+ same arguments apart from `--review`, `--per-commit`, `--shelve`, `--no-edit` and `--no-alias`. It checks out the first
712
+ commit since the base branch and runs `git p4son new --review` on it, then checks out each later commit and runs
713
+ `git p4son update --shelve`, and finally returns to where you started. With Swarm, every step but the last sleeps 5
714
+ seconds to give Perforce/Swarm time to process the shelf. Another [review tool](#review-tools) runs once per step
715
+ instead, with no sleep. The commits are reviewed where they are: to review them on top of the latest
716
+ `main`, rebase first. Like `new`, it needs a clean git workspace, untracked files included, and checks it even with
717
+ `--dry-run`.
718
+
719
+ ```sh
720
+ git p4son review -b BASE_BRANCH [alias] [-m <message> | -F <file>] [--force] [--dry-run] [--no-commit-list]
721
+ [--review-tool NAME]
722
+ ```
723
+
724
+ **Arguments:**
725
+ - `alias` (optional): Alias name for the new changelist. Defaults to the current branch name.
726
+
727
+ **Options:**
728
+ - `-m, --message MESSAGE`: Changelist description message. Defaults to the HEAD commit subject
729
+ - `-F, --file FILE`: Read the changelist description message from a file instead of `-m`. The message may span
730
+ multiple lines
731
+ - `-b, --base-branch BASE_BRANCH`: Required. The base the change starts from, to find commits since: a branch or
732
+ bookmark, or a commit exactly one points at, which the alias records as for [`new`](#new-command)
733
+ - `-f, --force`: Overwrite an existing alias file
734
+ - `-n, --dry-run`: Print the steps, one per commit, without running them. Ends with `Dry run, nothing changed`
735
+ - `--no-commit-list`: Leave the enumerated commit list out of the changelist description. Passed on to `new` and
736
+ each `update` step
737
+
738
+ A dry run prints the plan like this, with the base resolved to the commit every step uses; the message, which only
739
+ the first step gets, is printed below it:
740
+
741
+ ```
742
+ abc1234 First commit: git p4son new my-feature --review -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
743
+ def5678 Second commit: git p4son update my-feature --shelve -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
744
+ ghi9012 Third commit: git p4son update my-feature --shelve -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
745
+ ```
746
+
747
+ If a step fails, `review` returns to where you started and names the step and commit that failed. Once the first
748
+ step has created the changelist, the error also says how to finish: after fixing the problem, run the
749
+ `git p4son update my-feature --shelve --per-commit -b <commit>` it prints, which resumes after the last commit that
750
+ worked.
751
+
752
+ **Examples:**
753
+ ```sh
754
+ # Review all commits since main (alias defaults to branch name)
755
+ git p4son review -m "Add my feature" -b main
756
+
757
+ # Review a branch's only commit: HEAD~1 is main's commit, so the alias records main
758
+ git p4son review -m "Fix bug" -b HEAD~1
759
+
760
+ # Preview the steps without running them
761
+ git p4son review -m "Add my feature" -b main --dry-run
762
+
763
+ # Take a multi-line description from a file
764
+ git p4son review -F description.txt -b main
765
+ ```
766
+
767
+ ### List-Changes Command
768
+
769
+ List commit subjects since a base branch in chronological order (oldest first):
770
+
771
+ ```sh
772
+ git p4son list-changes [--base-branch BASE_BRANCH] [--porcelain]
773
+ ```
774
+
775
+ **Options:**
776
+ - `-b, --base-branch BASE_BRANCH`: Base branch to compare against. Default is `HEAD~1`.
777
+ - `--porcelain`: Print only the numbered list, and nothing when there are no changes, for scripts and agents. Errors
778
+ still go to stderr.
779
+
780
+ **Examples:**
781
+ ```sh
782
+ git p4son list-changes
783
+ git p4son list-changes --base-branch main
784
+ git p4son list-changes --base-branch main --porcelain
785
+ ```
786
+
787
+ This command is useful for generating changelist descriptions by listing all commit messages since the base branch,
788
+ numbered sequentially.
789
+
790
+ ### Alias Command
791
+
792
+ Manage changelist aliases, stored one per file as `.git-p4son/aliases/<alias>.toml` (`changelist = 12345`, and
793
+ with the jj backend `change = "<change ID>"`, the [jj change](#jujutsu-jj) it was made for). An alias that `new` or
794
+ `review` saved also records the changelist's base and the commits since it it includes, which
795
+ [`update`](#update-command) goes on from: `base`, `base_commit` and `included`, a list of the commits' identities.
796
+ Aliases saved by older versions in `.git-p4son/changelists/` keep working, and move to `.git-p4son/aliases/` when
797
+ written, or all at once with `alias clean`.
798
+
799
+ #### alias list
800
+
801
+ List all aliases and their changelist numbers:
802
+
803
+ ```sh
804
+ git p4son alias list
805
+ ```
806
+
807
+ **Examples:**
808
+ ```sh
809
+ git p4son alias list
810
+ ```
811
+
812
+ #### alias show
813
+
814
+ Print the changelist number saved under an alias:
815
+
816
+ ```sh
817
+ git p4son alias show [alias]
818
+ ```
819
+
820
+ Only the number is printed to stdout, so scripts and AI agents can capture it, e.g. to find the changelist that
821
+ `new` or `review` created. Exits with an error if the alias does not exist.
822
+
823
+ **Arguments:**
824
+ - `alias` (optional): Alias name to show. Defaults to the current branch name.
825
+
826
+ **Examples:**
827
+ ```sh
828
+ git p4son alias show # changelist for current branch
829
+ git p4son alias show myfeature
830
+ p4 describe -s $(git p4son alias show)
831
+ ```
832
+
833
+ #### alias new
834
+
835
+ Save a changelist number under a named alias:
836
+
837
+ ```sh
838
+ git p4son alias new <changelist> [alias] [--force]
839
+ ```
840
+
841
+ **Arguments:**
842
+ - `changelist`: Changelist number to save
843
+ - `alias` (optional): Alias name to save the changelist number under. Defaults to the current branch name.
844
+
845
+ **Options:**
846
+ - `-f, --force`: Overwrite an existing alias file
847
+
848
+ **Examples:**
849
+ ```sh
850
+ git p4son alias new 12345 # alias defaults to branch name
851
+ git p4son alias new 12345 myfeature
852
+ git p4son alias new 67890 myfeature -f
853
+ ```
854
+
855
+ #### alias delete
856
+
857
+ Delete a changelist alias, or all of them:
858
+
859
+ ```sh
860
+ git p4son alias delete [alias | --all]
861
+ ```
862
+
863
+ **Arguments:**
864
+ - `alias` (optional): Alias name to delete. Defaults to the current branch name.
865
+
866
+ **Options:**
867
+ - `--all`: Delete all aliases without prompting, whether their changelists are pending or not. To delete only those
868
+ that are not, use `alias clean`. An alias that can't be deleted is reported and skipped, and the command then exits
869
+ with 1
870
+
871
+ **Examples:**
872
+ ```sh
873
+ git p4son alias delete # delete alias for current branch
874
+ git p4son alias delete myfeature
875
+ git p4son alias delete --all
876
+ ```
877
+
878
+ #### alias clean
879
+
880
+ Delete the aliases whose changelist is no longer pending, as it was submitted or deleted:
881
+
882
+ ```sh
883
+ git p4son alias clean [-n] [--porcelain]
884
+ ```
885
+
886
+ It first moves any aliases still in `.git-p4son/changelists/` to `.git-p4son/aliases/`, then goes through the aliases
887
+ in name order, each under a heading of its own: it looks up the alias's changelist in Perforce and deletes the alias
888
+ if the changelist was submitted or doesn't exist. If p4 answers neither that nor pending for a changelist, it stops
889
+ there, leaving that alias and the ones after it. A submit that renumbers the changelist leaves its old number behind,
890
+ which counts as gone too. With the jj backend, an alias whose [jj change](#jujutsu-jj) is gone but whose changelist
891
+ is still pending is kept; `alias list` marks it `(gone)`, and `alias delete` removes it.
892
+
893
+ It ends under an `Alias clean done` heading with how many aliases it deleted and kept. If any couldn't be deleted,
894
+ that line is a warning with how many failed, followed by an error, and the command exits with 1.
895
+
896
+ To delete specific aliases, use `alias list` and `alias delete`.
897
+
898
+ **Options:**
899
+ - `-n, --dry-run`: List the aliases that would be deleted, without deleting or moving any. Ends with
900
+ `Dry run, nothing changed`
901
+ - `--porcelain`: Print only one `<action> <alias> <CL>` line per alias, for scripts and agents. The action is `kept`,
902
+ `deleted`, or `failed` when the alias couldn't be deleted; with `-n` it is `would-keep` or `would-delete`. Errors
903
+ still go to stderr. A `failed` alias makes the exit code 1, after the lines for all aliases; a stop exits with 1,
904
+ with no line for the alias it stopped at or those after it.
905
+
906
+ **Examples:**
907
+ ```sh
908
+ git p4son alias clean -n # see which aliases would go
909
+ git p4son alias clean
910
+ git p4son alias clean --porcelain # e.g. "deleted feature-login 12345"
911
+ ```
912
+
913
+ ### Writable Command
914
+
915
+ Writable mode keeps git-tracked files writable, so you can edit them without running `p4 edit` first. git-p4son
916
+ opens changed files in Perforce itself when you run `new`, `update` or `review`. Git-ignored files, such as content
917
+ and other Perforce-only files, stay read-only and are checked out through Perforce as usual.
918
+
919
+ ```sh
920
+ git p4son writable # Show whether writable mode is on
921
+ git p4son writable enable # Turn writable mode on, then apply it
922
+ git p4son writable disable # Turn writable mode off, then apply it
923
+ git p4son writable apply # Make git-tracked files match the current mode
924
+ ```
925
+
926
+ `apply` makes every git-tracked file writable when the mode is on. When it's off, it makes them read-only, except
927
+ files opened in Perforce in any changelist. On a workspace with the `allwrite` option, making files read-only is
928
+ skipped, since the client spec wants every file writable. Git-ignored files are never changed.
929
+
930
+ The setting is stored in `.git-p4son/config.toml`:
931
+
932
+ ```toml
933
+ [core]
934
+ writable = true
935
+ ```
936
+
937
+ With the mode on, `sync` makes the files it synced writable again if git tracks them, since Perforce writes synced
938
+ files read-only. Files made read-only outside git-p4son, for example by submitting from P4V, `p4 revert`, or "Get
939
+ Latest" in P4V, stay read-only until a later sync touches them. Run `git p4son writable apply` to fix them right
940
+ away.
941
+
942
+ This replaces the `post-sync` hook some users run to make every tracked file writable after a sync.
943
+
944
+ Turning the mode off also makes tracked files whose Perforce type carries the `+w` (always writable) modifier
945
+ read-only. The next sync of such a file makes it writable again.
946
+
947
+ ### Completion Command
948
+
949
+ Print the path to a shell completion script:
950
+
951
+ ```sh
952
+ git-p4son completion <shell> [--dirname]
953
+ ```
954
+
955
+ **Arguments:**
956
+ - `shell`: Shell to print completion script path for (`bash`, `zsh`, or `powershell`)
957
+
958
+ **Options:**
959
+ - `-d, --dirname`: Print the directory containing the completion script instead of the full file path
960
+
961
+ See [Shell Completions](#shell-completions) below for installation instructions.
962
+
963
+ ### Skill Command
964
+
965
+ Install or show the [Claude Code skill](#claude-code-skill):
966
+
967
+ ```sh
968
+ git p4son skill install # install the skill for your user
969
+ git p4son skill show # print the instructions the skill gives to AI agents
970
+ ```
971
+
972
+ `show` also prints the workspace's own [overrides](#workspace-overrides) from `.git-p4son/skill-override.md`, if it
973
+ has any.
974
+
975
+ ### The `branch` keyword
976
+
977
+ Most commands that accept an alias or changelist argument default to the current branch name. You can also pass the
978
+ `branch` keyword explicitly - it resolves to an alias name derived from the current git branch.
979
+
980
+ The keyword cannot be used in a detached HEAD state. Use `--no-alias` (on `new`) or supply an explicit
981
+ alias name instead.
982
+
983
+ ## Review Tools
984
+
985
+ `new --review` and `review` create a review in Swarm by default: the description gets a `#review` keyword, and Swarm
986
+ picks up each shelf. A team that reviews with another tool, one that has to be run to post each shelf, configures the
987
+ tool's command line under a name of its choosing in `.git-p4son/config.toml`:
988
+
989
+ ```toml
990
+ [review-tool]
991
+ default = "my-tool"
992
+
993
+ [review-tool.my-tool]
994
+ command = ["python", "tools/my-review.py", "--p4port", "$(p4port)", "--changelist", "$(changelist)"]
995
+ new = ["create"]
996
+ update = ["update"]
997
+ ```
998
+
999
+ `--review-tool my-tool` pushes a review to it, and `default` makes it the default, so `--review-tool swarm` picks
1000
+ Swarm again. The alias records the changelist's tool, so `update --shelve` runs it again without naming it; to move a
1001
+ change to another tool, delete the changelist and its alias and create the review again. `--no-alias` is refused with
1002
+ any tool but Swarm.
1003
+
1004
+ With a review tool other than Swarm, there is no `#review` keyword, and after each shelve of the review git-p4son runs
1005
+ `command` from the workspace root, once per commit with `review`. On the shelve of `new`, the `new` arguments are
1006
+ added to it, to create the review, and on the shelves of `update` the `update` ones, to add the new shelf as a
1007
+ revision of it. If the first run fails, the `update --shelve` that reruns it still gets the `new` arguments, as the
1008
+ review doesn't exist yet. Both are optional; without one, `command` runs as it is.
1009
+
1010
+ `command`, `new` and `update` are lists, one string per argument; a single string is refused. No shell runs them,
1011
+ so they work the same on every platform and never need quoting. A program named by a relative path, such as
1012
+ `tools/review.exe`, is found from the workspace root, and a bare name, such as `python`, on `PATH`. A `.cmd` or `.ps1`
1013
+ script on Windows needs its interpreter named, such as `["pwsh", "-File", "tools/my-review.ps1"]`. `$(name)` in an
1014
+ argument is replaced:
1015
+
1016
+ - `$(changelist)`: the pending changelist number
1017
+ - `$(workspace)`: the Perforce client workspace name
1018
+ - `$(user)`: the Perforce user
1019
+ - `$(p4port)`: the server address, as `p4 set P4PORT` gives it
1020
+ - any other name: the environment variable of that name, which on Windows ignores case. A name that is neither fails
1021
+ the command before anything runs
1022
+
1023
+ A replaced value stays within its argument, spaces and all. The command is echoed with the values in, so it can be
1024
+ rerun by hand; that also shows any token passed through an environment variable. Anything more, such as settings
1025
+ files or a sign-in, goes in a wrapper script of your own that the command runs.
1026
+
1027
+ The first run can sign in or open a browser; later ones run once per shelve, often as the steps of a per-commit run,
1028
+ so keep them non-interactive. A tool that exits with a non-zero code fails the command. `review` then stops at that
1029
+ commit with the command that resumes it, which shelves the commit again and reruns the tool, and `new` names the
1030
+ `update <alias> --shelve` that reruns it once the tool works. `--dry-run` says which tool would run. The tool runs on
1031
+ the terminal, so its output shows as it is written and it can prompt. Like a hook, it runs under git-p4son's
1032
+ [jj lock](#locking-and-the-git-workflow), so it must not run jj commands that snapshot.
1033
+
1034
+ ## Hooks
1035
+
1036
+ Hooks work similarly to git hooks. They are executables (unix)/scripts (windows) that you place in
1037
+ the `.git-p4son/hooks/[hook-name]/` directory. These scripts will be called to add or modify behavior
1038
+ at defined times during git-p4son operations. Scripts get run in filename (lexicographically) sorted
1039
+ order.
1040
+
1041
+ The hook process CWD is the directory where git-p4son was invoked, and `GIT_P4SON_REPO_ROOT_DIR` is
1042
+ set to the git-p4son repository root. `GIT_P4SON_BACKEND` is `git` or `jj`, the [backend](#choosing-the-backend)
1043
+ the command runs with.
1044
+
1045
+ On Windows, `.ps1`, `.sh`, and `.py` files are run with
1046
+ `powershell.exe -NoProfile -ExecutionPolicy Bypass -File`, `bash.exe`, and `python.exe` respectively.
1047
+ Customize or add Windows script runners in `.git-p4son/config.toml`:
1048
+
1049
+ ```toml
1050
+ [core.script-runners]
1051
+ ".ps1" = ["pwsh.exe", "-NoProfile", "-File"]
1052
+ ".nu" = "nu.exe"
1053
+ ```
1054
+
1055
+ Non-executable or unrecognized hook files, and invalid runner entries, are skipped with a warning.
1056
+
1057
+ ### pre-sync hook
1058
+
1059
+ Before `git-p4son sync` syncs any changelist, git-p4son runs executable hooks from
1060
+ `.git-p4son/hooks/pre-sync/`. All of them run, and if any exits with a non-zero code the sync is aborted before
1061
+ any changelist is synced. When a sequence of changelists is synced, the pre-sync hooks run only once,
1062
+ before the first sync.
1063
+
1064
+ ### post-sync hook
1065
+
1066
+ After a successful `git-p4son sync` that actually performs sync work, git-p4son runs executable hooks from
1067
+ `.git-p4son/hooks/post-sync/`. They don't run when the workspace is already at the requested changelist.
1068
+
1069
+ ## Jujutsu (jj)
1070
+
1071
+ git-p4son detects a jj workspace colocated with the git repository, which needs jj 0.41 or newer. CI tests both
1072
+ 0.41 and the latest jj release, and the minimum only rises with a note in the CHANGELOG. Separate jj workspaces,
1073
+ sparse working copies, and conflicted or divergent changes are not supported. Without a `.jj` folder, nothing
1074
+ changes.
1075
+
1076
+ ### The jj p4son alias
1077
+
1078
+ jj has no external subcommands, but an alias can run git-p4son, so `jj p4son sync` runs `git p4son sync`. Add it
1079
+ once per machine to jj's user config, or let `init` offer it. From jj 0.42, an alias can carry a doc, which jj's
1080
+ shell completion shows next to `p4son`:
1081
+
1082
+ ```sh
1083
+ jj config set --user aliases.p4son '{ definition = ["util", "exec", "--", "git-p4son"], doc = "Run git-p4son" }'
1084
+ ```
1085
+
1086
+ With jj 0.41, set `aliases.p4son` to the list alone, `'["util", "exec", "--", "git-p4son"]'`. `init` writes
1087
+ whichever form the installed jj supports.
1088
+
1089
+ `jj util exec` neither locks nor snapshots, so `jj p4son` behaves exactly as `git p4son`, and git-p4son's messages
1090
+ keep saying `git p4son`. Run it from inside the workspace: `jj -R other-workspace p4son` would still run in the
1091
+ current directory, so git-p4son refuses with "Run jj p4son from inside the workspace; -R is not supported." Shell
1092
+ completion for `jj p4son` needs [a hook of its own](#jj-p4son).
1093
+
1094
+ ### Choosing the backend
1095
+
1096
+ The backend is the tool git-p4son follows for the change, the base and the branch: git or jj. By default it is jj
1097
+ in a jj workspace and git otherwise. To choose, set `core.backend` in `.git-p4son/config.toml`, or put the global
1098
+ `--backend` flag before the command, which overrides the setting:
1099
+
1100
+ ```toml
1101
+ [core]
1102
+ backend = "git" # "auto" (the default), "git" or "jj"
1103
+ ```
1104
+
1105
+ ```sh
1106
+ git p4son --backend git new -b main
1107
+ ```
1108
+
1109
+ `jj` outside a jj workspace is an error. In a jj workspace, the jj backend refuses to run when jj is missing or
1110
+ older than 0.41, and points to `--backend git`. The git backend needs no jj, and still holds jj's working-copy
1111
+ lock, which jj 0.41 or newer honours, so jj cannot snapshot halfway through a command.
1112
+
1113
+ With the jj backend in a jj workspace:
1114
+
1115
+ - `new`, `update` and `list-changes` work on the jj working change `@`. When `@` is empty, has no description or
1116
+ bookmark and has one parent, they work on that parent instead, so a fresh working change above a feature still
1117
+ refers to the feature.
1118
+ - `new` records the change's ID in the alias it saves, so later commands find the alias by change, whatever the
1119
+ change's bookmarks or description have become since. A new alias is named after the one local bookmark at the
1120
+ change, with `/` replaced by `-`, or, with no bookmark or several, after the first 8 letters of its change ID.
1121
+ - An alias records one change, and a change one alias: `new` refuses a change another alias records, naming it, and
1122
+ `--force` moves the record to the new alias. `alias new` records no change. `alias list` shows each recorded change,
1123
+ marked `(gone)` once jj no longer has it.
1124
+ - The default message is the first line of the change's description. Use `jj describe`, `-m` or `-F`.
1125
+ - `-b/--base-branch` takes a jj revision that resolves to one change, such as a bookmark, change ID or commit ID.
1126
+ Where it has a default, it's the change's parent rather than git's `HEAD~1`. `new` and `review` record it as a
1127
+ bookmark, so it has to name one, or resolve to a commit exactly one points at.
1128
+ - `new` and `update` use jj's snapshot of the working copy, check that it did not change while git-p4son took the
1129
+ lock, and refuse files jj left untracked. You do not need a separate committed change before opening files in
1130
+ Perforce. Before a Perforce revert overwrites a file, git-p4son saves the working file and puts it back
1131
+ afterwards, keeping its bytes, line endings and permissions instead of taking git's index version.
1132
+ - `init` holds jj's working-copy lock while it sets up the git repository. It also offers to colocate jj and to
1133
+ add the `jj p4son` alias, see [Init Command](#init-command).
1134
+
1135
+ For example:
1136
+
1137
+ ```sh
1138
+ jj git init --colocate # Add jj to an existing git-p4son repository (see Line endings), or answer yes in init
1139
+ jj p4son sync # From any change: syncs main, then rebases your changes onto it
1140
+
1141
+ jj new main -m "Fix login"
1142
+ # Edit files
1143
+ jj bookmark create fix-login
1144
+ jj p4son new -b main --review
1145
+ # Edit more files
1146
+ jj p4son update -b main --shelve
1147
+ ```
1148
+
1149
+ ### Syncing a bookmark
1150
+
1151
+ `sync` works from any change, as with git. It moves the sync bookmark, `[sync] branch` or `--branch`, defaulting
1152
+ to `main`, to each sync commit:
1153
+
1154
+ 1. It puts the bookmark's files on disk. Your working change keeps its content in jj, which snapshotted it first.
1155
+ 2. It syncs and commits, then releases jj's lock.
1156
+ 3. It rebases the changes you started from onto the moved bookmark, as `jj rebase -b <your change> -d main`, and
1157
+ lists any change that got conflicts, which jj records rather than stopping on.
1158
+ 4. It returns you to where you started: `jj edit` on the change you were editing, or `jj new` above it.
1159
+
1160
+ From the sync bookmark itself, nothing is rebased. `--no-rebase` skips the rebase and still returns you.
1161
+
1162
+ `sync` refuses when the sync bookmark points at the working change itself, which a sync would make part of the
1163
+ bookmark's history. Move the bookmark back with `jj bookmark set main -r @- --allow-backwards`, or, to keep the edits
1164
+ as a change on it, run `jj describe` and `jj new`.
1165
+
1166
+ You stay on the sync bookmark when:
1167
+
1168
+ - local changes were merged back: they are in a new working change on it, for you to review, and your changes are
1169
+ still rebased
1170
+ - a sync fails partway: jj's next command puts a new working change there, holding the files as Perforce left them,
1171
+ and nothing is rebased
1172
+ - the rebase fails: sync reports it with the `jj rebase` command to run and a non-zero exit code, and the sync is
1173
+ not undone
1174
+
1175
+ A failing pre-sync hook, or anything else before the first sync, puts your working change's files back.
1176
+
1177
+ `sync` still stages and commits with git, including git attributes and filters, and sets `core.autocrlf` to match
1178
+ jj's line ending conversion.
1179
+
1180
+ ### Line endings
1181
+
1182
+ jj writes the working files by its `working-copy.eol-conversion`, and git by its `core.autocrlf`. When the two
1183
+ disagree, jj and git see different line endings, and jj fills changes with line ending edits. Set them to go
1184
+ together:
1185
+
1186
+ | git's `core.autocrlf` | jj's `working-copy.eol-conversion` |
1187
+ | --- | --- |
1188
+ | `false`, the default | `none`, the default |
1189
+ | `true`, the default in Git for Windows | `input-output` |
1190
+ | `input` | `input` |
1191
+
1192
+ On the jj backend, git-p4son warns when they disagree, and names the jj setting that matches git, for example
1193
+ `jj config set --repo working-copy.eol-conversion input-output`. The check reads only `core.autocrlf`: `text` and
1194
+ `eol` attributes in a `.gitattributes` override it in git, and jj doesn't read them.
1195
+
1196
+ Set it before jj's first snapshot, as `jj git init --colocate` takes one. Once jj has recorded the files with the
1197
+ wrong line endings, a later setting doesn't fix them, as jj only reads the files again when they change. `init`
1198
+ colocates with the matching setting, and to colocate by hand, pass it to the init too:
1199
+
1200
+ ```sh
1201
+ jj --config working-copy.eol-conversion=input-output git init --colocate
1202
+ jj config set --repo working-copy.eol-conversion input-output
1203
+ ```
1204
+
1205
+ If you colocated without it, and jj shows every text file as changed, colocate again before doing anything else in
1206
+ jj. Don't `jj restore` that change: it holds every file the first snapshot added, and restoring it deletes them from
1207
+ disk, including your untracked work. Colocating again leaves the files alone:
1208
+
1209
+ ```sh
1210
+ rm -rf .jj # Remove-Item -Recurse -Force .jj in PowerShell
1211
+ git reset # Drops the entries jj added to git's index
1212
+ jj --config working-copy.eol-conversion=input-output git init --colocate
1213
+ jj config set --repo working-copy.eol-conversion input-output
1214
+ ```
1215
+
1216
+ If git ignores folders only by matching without case, see [Ignored files](#ignored-files): `git p4son init`
1217
+ colocates with both settings.
1218
+
1219
+ ### Ignored files
1220
+
1221
+ git matches `.gitignore` patterns without case when `core.ignorecase` is true, the default on Windows and macOS. jj
1222
+ always matches them with case, so it would track a `Thirdparty/` folder that git ignores through `ThirdParty/`.
1223
+
1224
+ To keep jj from tracking them, git-p4son leaves each such folder, or file, out of jj's `snapshot.auto-track` for the
1225
+ repository, building on any value you have, for example `(all()) ~ root:Some/Plugin/Source/Thirdparty`. That's
1226
+ jj's own setting, so it works whatever `.gitignore` re-includes with `!`, which would outrank `.git/info/exclude`,
1227
+ and it leaves git alone. `jj status` then lists the folders under "Untracked paths". As the repository's value holds
1228
+ yours, a later change to your user-level `snapshot.auto-track` doesn't reach the repository.
1229
+
1230
+ git-p4son does so when `init` colocates, passing the setting to `jj git init`, as jj snapshots straight away, and in
1231
+ the steps it lists for colocating a repository it creates by hand. It also does so at the end of each sync on the jj
1232
+ backend, as a sync can bring in new folders. To let jj track such a folder again, remove its `root:"..."` from
1233
+ `snapshot.auto-track`, with `jj config edit --repo`.
1234
+
1235
+ If jj tracks such files anyway, for example in a workspace colocated before git-p4son did this, git-p4son warns about
1236
+ the ones the change you're working on adds, unless it's a commit in the sync branch's history, which git made. The
1237
+ warning lists the `jj config set` that leaves them out and the `jj file untrack` command that stops tracking them,
1238
+ which leaves the files on disk. Both are quoted to paste into cmd, PowerShell or a POSIX shell alike. They name a
1239
+ folder only when git tracks nothing else in it, so files git tracks stay tracked. Files you track on purpose, with
1240
+ `jj file track --include-ignored`, are left alone.
1241
+
1242
+ ### Locking, and the git workflow
1243
+
1244
+ git-p4son holds jj's working-copy lock while commands run, including sync hooks and temporary Perforce reverts,
1245
+ so other jj processes cannot snapshot files halfway through. A busy lock stops the command. Queries during the
1246
+ command use a pinned jj operation without snapshotting.
1247
+
1248
+ jj's first snapshot and final reconciliation happen outside the lock, and so do sync's rebase and return, so
1249
+ another jj command can import the finished git changes before git-p4son does: this is not one atomic jj
1250
+ transaction. `--verbose` logs the jj operation git-p4son pinned at the start. The lock does not keep out
1251
+ editors, git commands or other jj workspaces. If a command fails, look at the workspace before continuing: the
1252
+ lock is released, but Perforce operations that completed are not undone.
1253
+
1254
+ Hooks must not run ordinary jj commands, which would wait for the lock their caller holds. Read-only queries such
1255
+ as `jj --at-op=@ log` avoid snapshotting and the git import. A hook that runs git-p4son itself needs
1256
+ `--backend git`, which reuses the caller's lock.
1257
+
1258
+ `review`, `new --per-commit` and `update --per-commit` run once per commit since the base, up to the jj change, as they
1259
+ do in git. Under jj's lock, each step puts its commit's files on disk with git, and the working change's files go back
1260
+ at the end, also when a step fails, so jj sees no change. No jj command runs, and untracked and ignored files are left
1261
+ alone. They refuse to start if files changed after jj's snapshot, as the checkouts would overwrite them:
1262
+
1263
+ ```sh
1264
+ git p4son review -b main
1265
+ git p4son update --per-commit --shelve -b main
1266
+ ```
1267
+
1268
+ To use the git workflow on purpose, put `--backend git` **before** the command. This uses git branches, `HEAD` and
1269
+ git's clean-workspace check.
1270
+
1271
+ ## Claude Code Skill
1272
+
1273
+ git-p4son ships a skill for Claude Code that teaches it how git-p4son is meant to be used: keeping `main` in sync
1274
+ with Perforce, never submitting on your behalf, creating reviews with full control of the changelist description,
1275
+ updating them after feedback, and cleaning up after a submit. With it installed, you can
1276
+ ask Claude to sync, put a branch up for review or address review feedback, and it will use git-p4son to do it.
1277
+
1278
+ Install it once for your user:
1279
+
1280
+ ```sh
1281
+ git p4son skill install
1282
+ ```
1283
+
1284
+ This writes `~/.claude/skills/git-p4son/SKILL.md` (under `$CLAUDE_CONFIG_DIR` if set). `init` offers to do the same.
1285
+ The skill is installed for your user rather than in the workspace, where it would show up as an untracked file and
1286
+ block `sync`, `new` and `update`.
1287
+
1288
+ The installed file is only a short stub: it tells Claude when the skill applies and to run `git p4son skill show`,
1289
+ which prints the full instructions from the installed git-p4son. So the instructions always match your version of
1290
+ git-p4son, and upgrading with pip needs no reinstall. Run `git p4son skill show` yourself to read what Claude is told.
1291
+
1292
+ ### Workspace overrides
1293
+
1294
+ To teach Claude something that only holds for one workspace, such as a team's submit conventions, write it in
1295
+ `.git-p4son/skill-override.md`. Run inside that workspace, `skill show` prints it after the shipped instructions,
1296
+ under a heading saying it takes precedence where the two disagree. Start your own headings at `###`, since they land
1297
+ under that `##` heading. The file lives in `.git-p4son/`, so git ignores it and reinstalling the skill leaves it alone.
1298
+
1299
+ Claude picks the skill up on its own when you work in a git-p4son workspace. You can also invoke it directly with
1300
+ `/git-p4son`.
1301
+
1302
+ ## Shell Completions
1303
+
1304
+ Tab completion is available for bash, zsh, and PowerShell, including commands, flags, and dynamic alias names.
1305
+
1306
+ ### bash
1307
+
1308
+ Add the following to `~/.bashrc`:
1309
+
1310
+ ```bash
1311
+ source $(git-p4son completion bash)
1312
+ ```
1313
+
1314
+ ### zsh
1315
+
1316
+ Add the following to `~/.zshrc` before `compinit`:
1317
+
1318
+ ```zsh
1319
+ fpath=($(git-p4son completion -d zsh) $fpath)
1320
+ autoload -Uz compinit && compinit
1321
+ ```
1322
+
1323
+ ### PowerShell
1324
+
1325
+ Add the following to your PowerShell profile (`$PROFILE`):
1326
+
1327
+ ```powershell
1328
+ . $(git-p4son completion powershell)
1329
+ ```
1330
+
1331
+ All three enable completion for `git p4son <TAB>` and `git-p4son <TAB>`.
1332
+
1333
+ ### jj p4son
1334
+
1335
+ jj completes an alias's arguments as file paths, so `jj p4son <TAB>` needs a hook of its own. It completes the words
1336
+ after `p4son` as `git p4son` does, skipping jj's global options such as `-R` or `--color` before it, and hands every
1337
+ other `jj` completion to jj's own. Load it after jj's completion; the PowerShell hook needs PowerShell 7 (`pwsh`):
1338
+
1339
+ ```bash
1340
+ source $(git-p4son completion bash --jj) # ~/.bashrc
1341
+ ```
1342
+
1343
+ ```zsh
1344
+ source $(git-p4son completion zsh --jj) # ~/.zshrc, after compinit
1345
+ ```
1346
+
1347
+ ```powershell
1348
+ . $(git-p4son completion powershell --jj) # $PROFILE
1349
+ ```
1350
+
1351
+ Each loads the `git p4son` completion for its shell too. If you named the alias something other than `p4son`, set
1352
+ `GIT_P4SON_JJ_ALIAS` to its name.
1353
+