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