git-p4son 0.4.2__tar.gz → 0.5.1__tar.gz

{git_p4son-0.4.2 → git_p4son-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-p4son
-Version: 0.4.2
+Version: 0.5.1
 Summary: Utility for keeping a Perforce workspace and local git repo in sync
 Author-email: Andreas Andersson <andreas@neoboid.com>
 License-Expression: MIT
@@ -118,7 +118,8 @@ Requires Python 3.11 or later.
 pip install --upgrade git-p4son
 ```
 
-For tab completion (zsh and PowerShell), see [Shell Completions](#shell-completions).
+For tab completion (zsh and PowerShell), see [Shell Completions](#shell-completions). To let Claude Code drive
+git-p4son, see [Claude Code Skill](#claude-code-skill).
 
 ## Development
 
@@ -198,8 +199,8 @@ workflow.
 ### How sync handles writable files
 
 When you switch branches with `git checkout`, git removes the read-only flag on every file it writes. This means
-that when you switch back to `main` for a sync, Perforce may report "Can't clobber writable file" errors. git-p4son
-handles these automatically by classifying each writable file:
+that when you switch back to `main` for a sync, Perforce may refuse to overwrite those files because they are
+writable. git-p4son handles these automatically by classifying each writable file:
 
 **writable-unchanged** - The file on disk is identical to the last sync (only the read-only flag was removed
 by git). This is the common case after switching branches. git-p4son detects this by comparing git blob IDs against
@@ -233,19 +234,19 @@ commit any files that need attention.
 
 **Workspaces with `allwrite`** - When your client spec has the `allwrite` option, every file is writable by design,
 so the read-only flag carries no information about local changes. git-p4son classifies files exactly as above (the
-verdict comes from git, not from the flag), but leaves the write bit alone on files it finds unchanged: with
-`noclobber` Perforce compares digests before refusing to overwrite a writable file, and unchanged files pass that
-check. Only files with local changes are made read-only for the duration of the sync, since those are the ones
-Perforce would otherwise refuse to overwrite. The same digest check applies to git-ignored files: unchanged ones sync
-normally, and after the sync git-p4son lists the ones Perforce skipped because they were modified locally.
+verdict comes from git, not from the flag), but leaves the write bit alone on files it finds unchanged: Perforce
+compares digests before refusing to overwrite a writable file, and unchanged files pass that check. Only files with
+local changes are made read-only for the duration of the sync, since those are the ones Perforce would otherwise
+refuse to overwrite. The same digest check applies to git-ignored files: unchanged ones sync normally, and after the
+sync git-p4son lists the ones Perforce skipped because they were modified locally.
 
 **Writable mode** - With [writable mode](#writable-command) on, the files a sync touches are made writable again after
 the sync if git tracks them. The sync itself works as described above, since the workspace is not `allwrite`.
 
 ## Usage
 
-git-p4son provides ten commands: `init`, `sync`, `sync-split`, `new`, `update`, `review`, `list-changes`,
-`alias`, `writable`, and `completion`.
+git-p4son provides eleven commands: `init`, `sync`, `sync-split-users`, `new`, `update`, `review`,
+`list-changes`, `alias`, `writable`, `completion`, and `skill`.
 
 To see help for any command, use `-h`:
 
@@ -293,12 +294,19 @@ The `.gitignore` is set up using this priority:
 `init` also asks whether to turn on [writable mode](#writable-command), defaulting to the current setting. It only
 saves the answer; run `git p4son writable apply` once your files are committed to update their permissions.
 
+`init` then asks whether to sync your own changelists individually, making you a [split user](#split-users).
+The default is the current setting. Yes adds a `$(user)` entry to the split users and no removes it; other split
+users are left alone.
+
+Finally, if Claude Code is installed, `init` offers to install the [Claude Code skill](#claude-code-skill). An
+already installed skill is refreshed without asking.
+
 ### Sync Command
 
 Sync local git repository with a Perforce workspace:
 
 ```sh
-git p4son sync [changelist ...] [--force] [--dry-run] [--ignore-blocking-processes]
+git p4son sync [changelist ...] [--force] [--dry-run] [--split-user NAME ...] [--no-split] [--ignore-blocking-processes]
 ```
 
 **Arguments:**
@@ -311,6 +319,10 @@ git p4son sync [changelist ...] [--force] [--dry-run] [--ignore-blocking-process
 - `-f, --force`: Allow syncing to changelists older than the current one.
 - `-n, --dry-run`: Print the resolved sync sequence without syncing. The arguments are validated as for a
   real sync, but nothing else runs: no clean-workspace checks, no hooks, and no prompts.
+- `-u, --split-user NAME`: Also split out this user's changelists, on top of the configured
+  [split users](#split-users). Repeat to give several users. Each name is checked against the Perforce server.
+- `--no-split`: Ignore the configured split users for this sync. Users given with `--split-user` are still split
+  out, so `--no-split -u alice` splits out only alice's changelists.
 - `--ignore-blocking-processes`: Sync even while a [blocking process](#blocking-processes) is running.
 
 **Examples:**
@@ -323,6 +335,8 @@ git p4son sync 123 156 head # sync 123, 156, then the latest changelist
 git p4son sync last-synced
 git p4son sync 12345 --force
 git p4son sync --dry-run    # show the changelists a sync to latest would visit
+git p4son sync -u alice     # also split out alice's changelists
+git p4son sync --no-split   # sync without splitting out the configured split users
 ```
 
 #### Blocking processes
@@ -343,6 +357,37 @@ skipping the check.
 
 Pass `--ignore-blocking-processes` to sync once without the check, or remove the setting to turn it off for good.
 
+#### Split users
+
+Syncing straight to the latest changelist lumps your own submitted changelists together with everyone else's in a
+single commit. Split users fix that: for each changelist a split user submitted since the last sync, `sync` first
+syncs the changelist submitted immediately before it, so every changelist they submitted becomes a commit containing
+nothing but their own change.
+
+The split users are stored in `.git-p4son/config.toml`, and edited with the
+[`sync-split-users` command](#sync-split-users-command) or by answering yes in `init`:
+
+```toml
+[sync]
+split-users = ["$(user)", "alice"]
+```
+
+`$(user)` stands for the current Perforce user (from `p4 info`), resolved each time `sync` runs, so the config
+survives a change of user, the same way `$(workspace)` works in the depot root.
+
+For example, with the last sync at CL 100, your own changelists at 102 and 105, and the latest changelist at 106,
+`sync` visits `101 102 104 105 106`, producing five commits where CL 102 and CL 105 each hold only your change.
+Changelists given on the command line are all still visited, with the split points merged in: `sync 103 head`
+visits `101 102 103 104 105 106`.
+
+Splitting only moves forward from a previous sync. The first sync, `last-synced`, and syncing to an older changelist
+with `--force` are never split. Without any split users, `sync` makes no extra Perforce queries.
+
+Finding the split users' changelists costs one extra Perforce query over the range being synced. It runs after the
+blocking processes check, the clean-workspace checks and the pre-sync hooks, so a running blocking process, a dirty
+workspace or a hook that aborts the sync says so before that work. `--dry-run` skips the checks and hooks but still
+shows the resulting sequence.
+
 #### pre-sync hook
 
 Before `git-p4son sync` syncs any changelist, git-p4son runs [hooks](#hooks) from
@@ -354,78 +399,51 @@ changelists is given, the pre-sync hooks run once, before the first sync.
 After a successful `git-p4son sync` that actually performs sync work, git-p4son runs [hooks](#hooks)
 from `.git-p4son/hooks/post-sync/`.
 
-### Sync-Split Command
-
-Sync forward from the last synced changelist, splitting selected users' changelists into their own commits:
+### Sync-Split-Users Command
 
-```sh
-git p4son sync-split [changelist] [--user NAME ...] [--dry-run] [--ignore-blocking-processes]
-```
-
-Syncing straight to the latest changelist lumps your own submitted changelists together with everyone
-else's in a single commit. `sync-split` resolves the sequence for you: it looks up the last synced
-changelist in the git log, asks Perforce which changelists the selected users submitted since then, and
-syncs the changelist submitted immediately before each of those first. The result is a git history where
-every changelist those users submitted is a commit containing nothing but their own change.
-
-By default the selected user is you (the current p4 user), which covers the common case of reviewing your
-own submits one at a time. Repeat `--user` to split out several people's changelists in the same run.
-
-It is equivalent to working out the numbers by hand and running
-`git p4son sync <before-theirs> <theirs> ... head`, and it delegates to `sync` once the sequence is
-resolved, so [pre-sync and post-sync hooks](#hooks), [blocking processes](#blocking-processes), writable-file
-merging, and the clean-workspace checks all behave exactly as they do for `sync`. The blocking processes check,
-the clean-workspace checks and the pre-sync hooks are the one thing that runs earlier: resolving the sequence
-costs several Perforce queries, so they go first, and a running blocking process, a dirty workspace or a hook
-that aborts the sync says so before that work. They run once for the whole sync, and not at all for a
-`--dry-run` or when there is nothing to sync.
-
-**Arguments:**
-- `changelist` (optional): Changelist number to sync up to, or `head` for the latest. Omit to sync to the
-  latest changelist affecting the workspace.
+Show or edit the [split users](#split-users), the Perforce users whose changelists `sync` gives a commit each:
 
-**Options:**
-- `-u, --user NAME`: Perforce user whose changelists to split into their own commits. Repeat the flag to
-  select several users. Defaults to the current p4 user (from `p4 info`).
-- `-n, --dry-run`: Print the resolved sync sequence without syncing.
-- `--ignore-blocking-processes`: Sync even while a [blocking process](#blocking-processes) is running.
-
-**Examples:**
 ```sh
-git p4son sync-split                  # sync to latest, your own changelists split out
-git p4son sync-split head             # same, explicit
-git p4son sync-split 12345            # stop at changelist 12345
-git p4son sync-split --dry-run        # show the sequence that would be synced
-git p4son sync-split -u alice         # split out alice's changelists instead of yours
-git p4son sync-split -u alice -u bob  # split out both alice's and bob's changelists
+git p4son sync-split-users                 # list the split users (same as list)
+git p4son sync-split-users list
+git p4son sync-split-users add --me        # add yourself, stored as $(user)
+git p4son sync-split-users add alice bob
+git p4son sync-split-users delete alice
+git p4son sync-split-users delete --me
 ```
 
-For example, with the last sync at CL 100 and your own changelists at 102 and 105, `sync-split` resolves
-to `git p4son sync 101 102 104 105 106`, producing five commits where CL 102 and CL 105 each hold only
-your change.
+- `list` prints one user per line. `$(user)` is shown with the name it stands for, e.g. `$(user) (alice)`.
+- `add` checks every name against the Perforce server first, since a misspelled name would never match a
+  changelist. If any name is not a Perforce user, nothing is added. Names are stored as the server spells them,
+  and a name that is already a split user is skipped.
+- `delete` removes names regardless of case. If any name is not a split user, nothing is removed.
 
-`sync-split` only moves forward: it requires a previous sync to start from, and refuses a target older
-than the last synced changelist (use `git p4son sync --force` for that).
+`--me` adds or removes the `$(user)` entry. A quoted `'$(user)'` does the same, but the quotes matter: unquoted,
+bash, zsh and PowerShell run `$(user)` as a command substitution.
 
 ### New Command
 
-Create a new Perforce changelist and add changed files to it. Description will contain an enumerated list of git commits since the base branch.
-Optionally creates a Swarm review.
+Create a new Perforce changelist and add changed files to it. Description will contain an enumerated list of git commits
+since the base branch. Optionally creates a Swarm review.
 
 Opening files requires a clean git workspace, untracked files included; `new` refuses to run otherwise. The check
 is skipped with `--no-edit`. After opening files, unchanged ones are reverted (see
 [Keeping the changelist in step with git](#keeping-the-changelist-in-step-with-git)).
 
 ```sh
-git p4son new -m <message> [alias] [--base-branch BASE_BRANCH] [--force] [--dry-run] [--no-edit] [--no-alias]
-                           [--shelve] [--review]
+git p4son new [-m <message> | -F <file>] [alias] [--base-branch BASE_BRANCH] [--force] [--dry-run] [--no-edit]
+              [--no-alias] [--no-commit-list] [--shelve] [--review]
 ```
 
 **Arguments:**
 - `alias` (optional): Alias name to save the new changelist number under. Defaults to the current branch name.
 
 **Options:**
-- `-m, --message MESSAGE`: Changelist description message (required)
+- `-m, --message MESSAGE`: Changelist description message. Defaults to the HEAD commit subject
+- `-F, --file FILE`: Read the changelist description message from a file instead of `-m`. The message may span
+  multiple lines
+- `--no-commit-list`: Leave the enumerated commit list out of the changelist description, so it holds only the
+  message
 - `-b, --base-branch BASE_BRANCH`: Base branch for enumerating commits and finding changed files. Default is
   `HEAD~1`
 - `-f, --force`: Overwrite an existing alias file
@@ -450,26 +468,44 @@ git p4son new -m "New feature" --review -b main
 Update an existing Perforce changelist description. Commits since the base branch replace their existing
 entries in the enumerated commit list (matched by subject) and new ones are appended; entries outside the
 range are kept and the list is renumbered. So `update -b main` rebuilds the whole list without duplicating
-it, while `update -b HEAD~3` only refreshes the last three entries. By default also opens changed files for
+it, while `update -b HEAD~3` only refreshes the last three entries. The message above the list is kept unless `-m`
+or `-F` replaces it. By default also opens changed files for
 edit, and reverts files that are no longer part of the git change (see
 [Keeping the changelist in step with git](#keeping-the-changelist-in-step-with-git)). Opening files requires a
 clean git workspace, untracked files included; `update` refuses to run otherwise. The check is skipped with
 `--no-edit`.
 
+With `--per-commit`, `update` runs once per commit since the base branch instead of once for the whole range, the
+way `review` does after creating the changelist. It replays the commits with an interactive rebase, without opening
+an editor, and runs `git p4son update` after each one. With `--shelve`, every commit gets a shelf of its own and so
+shows up as its own patch in the Swarm review. Use it after making several commits since the last update:
+`update -b HEAD~2 --per-commit --shelve` updates the changelist with the last two commits, one at a time. The
+changelist is resolved before the rebase starts, and `-m`/`-F` is applied on the first step only. The rebase needs a
+clean git workspace, also with `--no-edit`. If a step fails, the rebase stops; fix the problem and run
+`git rebase --continue`.
+
 ```sh
-git p4son update [changelist] [--base-branch BASE_BRANCH] [--dry-run] [--no-desc] [--no-edit] [--shelve]
+git p4son update [changelist] [-m <message> | -F <file>] [--base-branch BASE_BRANCH] [--dry-run]
+                 [--no-commit-list] [--no-edit] [--shelve] [--per-commit]
 ```
 
 **Arguments:**
 - `changelist` (optional): Changelist number or named alias to update. Defaults to the current branch name.
 
 **Options:**
+- `-m, --message MESSAGE`: Replace the changelist description message above the commit list. The commit list is
+  kept and updated as usual, and so is a Swarm `#review` keyword on a line of its own at the end of the description
+- `-F, --file FILE`: Like `-m`, but read the message from a file. The message may span multiple lines
 - `-b, --base-branch BASE_BRANCH`: Base branch for enumerating commits and finding changed files. Default is
   `HEAD~1`
 - `-n, --dry-run`: Pretend and print what would be done, but do not execute
-- `--no-desc`: Skip updating the changelist description
+- `--no-commit-list`: Leave the enumerated commit list as it is. Without `-m` or `-F` the description is not
+  touched at all
 - `--no-edit`: Skip opening changed files for edit in Perforce
 - `--shelve`: Re-shelve the changelist after updating
+- `--per-commit`: Update the changelist once per commit since the base branch, oldest first, through an
+  interactive rebase. Steps sleep 5 seconds between them to give Perforce/Swarm time to process each shelf.
+  `--dry-run` prints the generated rebase todo
 - `-s, --sleep SECONDS`: Sleep for the specified number of seconds after the command is done
 
 **Examples:**
@@ -478,6 +514,8 @@ git p4son update              # update changelist for current branch
 git p4son update --shelve     # update and re-shelve
 git p4son update 12345
 git p4son update myalias -b main
+git p4son update -F description.txt   # replace the message, e.g. after review feedback
+git p4son update -b HEAD~2 --per-commit --shelve   # one shelf for each of the last two commits
 ```
 
 ### Keeping the changelist in step with git
@@ -503,20 +541,30 @@ are left out of it.
 
 ### Review Command
 
-Automate the interactive rebase workflow for creating Swarm reviews. This command generates a rebase todo with `exec` lines that run `git p4son new --review` on the first commit and `git p4son update --shelve` on each subsequent commit, then opens it in your editor for review before executing.
+Automate the interactive rebase workflow for creating Swarm reviews. This command generates a rebase todo with `exec`
+lines that run `git p4son new --review` on the first commit and `git p4son update --shelve` on each subsequent commit,
+then opens it in your editor for review before executing.
 
 ```sh
-git p4son review [alias] -m <message> [--base-branch BASE_BRANCH] [--force] [--dry-run]
+git p4son review [alias] [-m <message> | -F <file>] [--base-branch BASE_BRANCH] [--force] [--dry-run]
+                 [--no-commit-list] [--no-edit-todo]
 ```
 
 **Arguments:**
 - `alias` (optional): Alias name for the new changelist. Defaults to the current branch name.
 
 **Options:**
-- `-m, --message MESSAGE`: Changelist description message (required)
+- `-m, --message MESSAGE`: Changelist description message. Defaults to the HEAD commit subject
+- `-F, --file FILE`: Read the changelist description message from a file instead of `-m`. The message may span
+  multiple lines. The generated `exec` line passes the file on to `git p4son new -F`, so keep it in place until the
+  rebase has finished
 - `-b, --base-branch BASE_BRANCH`: Base branch to rebase onto and find commits since. Default is `HEAD~1`
 - `-f, --force`: Overwrite an existing alias file
 - `-n, --dry-run`: Print the generated rebase todo without executing
+- `--no-commit-list`: Leave the enumerated commit list out of the changelist description. Passed on to `new` and
+  each `update` in the rebase todo
+- `--no-edit-todo`: Accept the generated rebase todo as is and start the rebase without opening an editor. No
+  editor needs to be configured. Useful for scripts and AI agents, which can check the todo with `--dry-run` first
 
 When run, the command generates a todo like this and opens it in your editor:
 
@@ -529,7 +577,8 @@ pick ghi9012 Third commit
 exec git p4son update my-feature --shelve
 ```
 
-You can edit the todo before saving (e.g. reorder commits, remove lines), or abort by clearing the file — just like a normal `git rebase -i`. Each `exec` line automatically sleeps after shelving to give Perforce/Swarm time to process.
+You can edit the todo before saving (e.g. reorder commits, remove lines), or abort by clearing the file - just like a
+normal `git rebase -i`. Each `exec` line automatically sleeps after shelving to give Perforce/Swarm time to process.
 
 If the rebase fails mid-way, you can fix the issue and run `git rebase --continue` as usual.
 
@@ -543,6 +592,12 @@ git p4son review -m "Fix bug"
 
 # Preview the generated todo without executing
 git p4son review -m "Add my feature" -b main --dry-run
+
+# Take a multi-line description from a file
+git p4son review -F description.txt -b main
+
+# Run the rebase without reviewing the todo in an editor
+git p4son review -m "Add my feature" -b main --no-edit-todo
 ```
 
 ### List-Changes Command
@@ -562,7 +617,8 @@ git p4son list-changes
 git p4son list-changes --base-branch main
 ```
 
-This command is useful for generating changelist descriptions by listing all commit messages since the base branch, numbered sequentially.
+This command is useful for generating changelist descriptions by listing all commit messages since the base branch,
+numbered sequentially.
 
 ### Alias Command
 
@@ -581,6 +637,27 @@ git p4son alias list
 git p4son alias list
 ```
 
+#### alias show
+
+Print the changelist number saved under an alias:
+
+```sh
+git p4son alias show [alias]
+```
+
+Only the number is printed to stdout, so scripts and AI agents can capture it, e.g. to find the changelist that
+`new` or `review` created. Exits with an error if the alias does not exist.
+
+**Arguments:**
+- `alias` (optional): Alias name to show. Defaults to the current branch name.
+
+**Examples:**
+```sh
+git p4son alias show              # changelist for current branch
+git p4son alias show myfeature
+p4 describe -s $(git p4son alias show)
+```
+
 #### alias new
 
 Save a changelist number under a named alias:
@@ -605,19 +682,24 @@ git p4son alias new 67890 myfeature -f
 
 #### alias delete
 
-Delete a changelist alias:
+Delete a changelist alias, or all of them:
 
 ```sh
-git p4son alias delete [alias]
+git p4son alias delete [alias | --all]
 ```
 
 **Arguments:**
 - `alias` (optional): Alias name to delete. Defaults to the current branch name.
 
+**Options:**
+- `--all`: Delete all aliases without prompting. Unlike `alias clean`, it does not ask first, which suits scripts
+  and AI agents
+
 **Examples:**
 ```sh
 git p4son alias delete              # delete alias for current branch
 git p4son alias delete myfeature
+git p4son alias delete --all
 ```
 
 #### alias clean
@@ -694,10 +776,19 @@ git-p4son completion <shell> [--dirname]
 
 See [Shell Completions](#shell-completions) below for installation instructions.
 
+### Skill Command
+
+Install or show the [Claude Code skill](#claude-code-skill):
+
+```sh
+git p4son skill install    # install the skill for your user
+git p4son skill show       # print the instructions the skill gives to AI agents
+```
+
 ### The `branch` keyword
 
 Most commands that accept an alias or changelist argument default to the current branch name. You can also pass the
-`branch` keyword explicitly — it resolves to an alias name derived from the current git branch.
+`branch` keyword explicitly - it resolves to an alias name derived from the current git branch.
 
 The keyword cannot be used in a detached HEAD state. Use `--no-alias` (on `new` and `review`) or supply an
 explicit alias name instead.
@@ -735,6 +826,30 @@ before the first sync.
 After a successful `git-p4son sync` that actually performs sync work, git-p4son runs executable hooks from
 `.git-p4son/hooks/post-sync/`.
 
+## Claude Code Skill
+
+git-p4son ships a skill for Claude Code that teaches it how git-p4son is meant to be used: keeping `main` in step
+with Perforce, never submitting on your behalf, creating reviews with full control of the changelist description,
+updating them after feedback, and cleaning up after a submit. With it installed, you can
+ask Claude to sync, put a branch up for review or address review feedback, and it will use git-p4son to do it.
+
+Install it once for your user:
+
+```sh
+git p4son skill install
+```
+
+This writes `~/.claude/skills/git-p4son/SKILL.md` (under `$CLAUDE_CONFIG_DIR` if set). `init` offers to do the same.
+The skill is installed for your user rather than in the workspace, where it would show up as an untracked file and
+block `sync`, `new` and `update`.
+
+The installed file is only a short stub: it tells Claude when the skill applies and to run `git p4son skill show`,
+which prints the full instructions from the installed git-p4son. So the instructions always match your version of
+git-p4son, and upgrading with pip needs no reinstall. Run `git p4son skill show` yourself to read what Claude is told.
+
+Claude picks the skill up on its own when you work in a git-p4son workspace. You can also invoke it directly with
+`/git-p4son`.
+
 ## Shell Completions
 
 Tab completion is available for bash, zsh, and PowerShell, including commands, flags, and dynamic alias names.