git-p4son 0.7.0__tar.gz → 0.9.0__tar.gz

{git_p4son-0.7.0 → git_p4son-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-p4son
-Version: 0.7.0
+Version: 0.9.0
 Summary: Utility for keeping a Perforce workspace and local git or jj repo in sync
 Author-email: Andreas Andersson <andreas@neoboid.com>
 License-Expression: MIT
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/neoboid/git-p4son
 Project-URL: Repository, https://github.com/neoboid/git-p4son
 Project-URL: Issues, https://github.com/neoboid/git-p4son/issues
 Project-URL: Changelog, https://github.com/neoboid/git-p4son/blob/main/CHANGELOG.md
-Keywords: perforce,git,version-control,sync
+Keywords: perforce,git,jj,jujutsu,version-control,sync
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -25,31 +25,22 @@ Dynamic: license-file
 
 `git-p4son` lets you work in a Perforce workspace with a local git repository, or a colocated
 [Jujutsu (jj)](#jujutsu-jj) one, so you can use the familiar local development flow even though your project uses
-Perforce for source control.
+Perforce.
 
-A `main` branch (a bookmark in jj) is kept in sync with your Perforce workspace, one commit per changelist. You work
-on feature branches or jj changes and rebase them onto `main` after a sync; with jj, `sync` rebases the change you
-sync from for you.
+The core idea is a local `main` branch kept in sync with the Perforce workspace. Each sync commits the changes since
+the last one. You work on feature branches based on `main`, and rebase them onto it after a sync.
 
-When your changes are ready, `git-p4son` creates the changelist and shelves it for a Swarm review. It can post each
-commit as a patch of its own, so reviewers see the changes in the order you made them, much like a pull request.
-Updates fold in only the new commits.
-
-With jj, `git-p4son` works on the jj change: the changelist's alias follows the change through rewrites, the message
-comes from its description, and `jj p4son` runs every command.
-
-## On big workspaces
-Sometimes git struggles to keep entire perforce workspaces in the repo, like when working
-on a Unreal Engine game with all source code in the workspace. If so, it helps to edit
-`.gitignore` and include only the subdirectories in which you work, the rest of the files
-will still be managed by perforce of course.
+When your feature is ready, `git-p4son` creates a changelist from the commits on your branch. It can also create a
+review, in Swarm or another review tool, with each commit as its own patch, so reviewers see the changes in the order
+you made them, like the commits of a pull request on GitHub. To address feedback, commit more locally, and
+`git-p4son` adds the new commits to the changelist and the review.
 
 ## Usage Example
 
 Here's a typical workflow when developing a feature using `git-p4son`:
 
 ```sh
-# Sync main with latest changes from perforce
+# Sync main with the latest changes from Perforce
 git checkout main
 git p4son sync
 
@@ -60,11 +51,9 @@ git checkout -b my-fancy-feature
 git add .
 git commit -m "Feature part1"
 
-# Sync to the latest changelist affecting the workspace
+# Sync again, and rebase your branch onto main
 git checkout main
 git p4son sync
-
-# Rebase your changes on main
 git checkout my-fancy-feature
 git rebase main
 
@@ -72,32 +61,19 @@ git rebase main
 git add .
 git commit -m "Feature part2"
 
-# Create a Swarm review with all commits since main in one go.
-# Each commit is checked out in turn and gets a shelf of its own in the
-# review, then you are back on your branch.
-# An alias called "my-fancy-feature" (derived from the branch name) is
-# saved so you can refer to this CL by name in follow-up commands.
+# Create a review with a patch per commit, under an alias named after the branch
 git p4son review -m "My fancy feature" -b main
 
-# After review feedback, make more changes
+# Address review feedback, then add the new commit to the changelist and the review
 git add .
 git commit -m "Address review feedback"
-
-# Update the changelist with latest commit, re-open files, and re-shelve.
-# The changelist is looked up by branch name automatically.
 git p4son update --shelve
 
-# After approval, submit in p4v
-
-# Sync to the latest changelist from perforce
+# After approval, submit in P4V, then sync and clean up
 git checkout main
 git p4son sync
-
-# Force remove old branch as you don't need it anymore
-git branch -D my-fancy-feature
-
-# Remove changelist alias for the branch
-git p4son alias delete my-fancy-feature
+git branch -D my-fancy-feature    # -D, as the submitted change has other commit hashes
+git p4son alias clean             # deletes the aliases of submitted changelists
 
 # Start working on the next feature
 git checkout -b my-next-fancy-feature
@@ -119,8 +95,7 @@ jj p4son sync
 jj new -m "Feature part2"
 jj bookmark create my-fancy-feature
 
-# Create a Swarm review with every change since main, one shelf each.
-# The alias is named after the bookmark and records the jj change.
+# Create a review with a patch per change, under an alias named after the bookmark
 jj p4son review -m "My fancy feature" -b main
 
 # After review feedback, add a change and move the bookmark to it
@@ -128,11 +103,11 @@ jj new -m "Address review feedback"
 jj bookmark set my-fancy-feature -r @
 jj p4son update --shelve
 
-# After approval, submit in p4v, then abandon the submitted changes before
-# syncing, which deletes the bookmark too
+# After approval, submit in P4V, abandon the submitted changes, which deletes the
+# bookmark too, then sync and clean up
 jj abandon main..my-fancy-feature
-jj p4son alias delete my-fancy-feature
 jj p4son sync
+jj p4son alias clean
 
 # Start working on the next feature
 jj new main -m "Next fancy feature"
@@ -141,13 +116,30 @@ jj new main -m "Next fancy feature"
 `sync` only rebases the change you sync from, and the stack above it. Bring other bookmarks up to date with
 `jj rebase -b <bookmark> -d main`.
 
+## Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+- [Commands](#commands): [init](#init-command), [sync](#sync-command), [sync-split-users](#sync-split-users-command),
+  [new](#new-command), [update](#update-command), [review](#review-command), [list-changes](#list-changes-command),
+  [alias](#alias-command), [writable](#writable-command), [completion](#completion-command), [skill](#skill-command)
+- [Configuration](#configuration)
+- [Review Tools](#review-tools)
+- [Hooks](#hooks)
+- [Jujutsu (jj)](#jujutsu-jj)
+- [Claude Code Skill](#claude-code-skill)
+- [Shell Completions](#shell-completions)
+- [Development](#development)
+
 ## Installation
 
 ```sh
 pip install git-p4son
 ```
 
-Requires Python 3.11 or later.
+Requires Python 3.11 or later. For tab completion in bash, zsh and PowerShell, see
+[Shell Completions](#shell-completions). To let Claude Code drive git-p4son, see
+[Claude Code Skill](#claude-code-skill).
 
 ### Updating
 
@@ -155,45 +147,6 @@ Requires Python 3.11 or later.
 pip install --upgrade git-p4son
 ```
 
-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
-
-To install from source in editable mode:
-
-```sh
-git clone https://github.com/neoboid/git-p4son.git
-cd git-p4son
-pip install -e .
-```
-
-The `-e` flag installs the package in "editable" mode, meaning changes to the code are immediately available
-without reinstalling. This is also handy if you want to auto-update git-p4son whenever you pull from GitHub.
-
-git-p4son only uses Python standard library modules - no additional packages are required.
-
-Run the tests with `python -m pytest tests/` (`pip install pytest`). With `pytest-xdist` installed, add
-`-n auto --maxprocesses 8` to run them in parallel, which is about three times faster.
-
-### Git Hooks
-
-The repository includes git hooks in the `hooks/` directory:
-
-- **pre-commit** - verifies that staged Python files are formatted with `autopep8`. Install it with
-  `pip install autopep8`.
-- **pre-push** - runs the test suite and blocks the push if any test fails. It needs `pytest` installed, and runs
-  the tests in parallel when `pytest-xdist` is too.
-
-To activate the hooks, run:
-
-```sh
-scripts/setup-hooks.sh
-```
-
-This configures `core.hooksPath` so git uses the hooks from the repository. You only need to run this once after
-cloning.
-
 ## Setup
 
 These steps set up git-p4son in an existing Perforce workspace. You only need to do this once.
@@ -210,13 +163,13 @@ These steps set up git-p4son in an existing Perforce workspace. You only need to
    cd /path/to/your/workspace    # or a subdirectory of it
    git p4son init
    ```
-   The command verifies that you are inside a P4 workspace, prompts you to select a depot
-   root (entire workspace or current directory subtree), runs `git init`, sets up `.gitignore` (copying from
-   `.p4ignore` if available), and creates an initial commit.
-   With jj 0.41 or newer installed, it also offers to colocate jj and to add the `jj p4son` alias, see
-   [Jujutsu (jj)](#jujutsu-jj).
+   Answer its questions, starting with the depot root: the whole workspace or the subtree you're in. It then runs
+   `git init`, sets up `.gitignore` and makes a first commit holding only that. See [Init Command](#init-command) for
+   what it asks.
 
-3. **Review `.gitignore`.** Edit the file to ensure build artifacts and other unwanted files are excluded.
+3. **Review `.gitignore`.** Edit the file to ensure build artifacts and other unwanted files are excluded. In a big
+   workspace, such as an Unreal Engine game with all of the engine source in it, git can struggle to track
+   everything. Ignore all but the directories you work in; Perforce still manages the rest.
 
 4. **Add and commit all files manually the first time**
    ```sh
@@ -233,94 +186,23 @@ These steps set up git-p4son in an existing Perforce workspace. You only need to
 From here, branch off `main` for local development. See the [Usage Example](#usage-example) for a typical
 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 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
-the last sync commit that touched the file, restores the read-only flag, and lets the sync overwrite the file.
-
-**writable-changed** - The file on disk differs from the last sync. This happens when you manually edit a file
-on `main` and commit it to git without submitting to Perforce. git-p4son lets the sync overwrite the file and
-includes it in the sync commit (so the commit reflects pure Perforce state), then three-way merges your local
-changes on top of the new Perforce content - similar to a `git rebase`. If the merge is clean, the result appears
-as an unstaged change. If there are conflicts, standard conflict markers are inserted for you to resolve.
-
-**added both locally and in Perforce** - A file you committed to git is also being added by Perforce (p4 has never
-synced it to your workspace). There is no common baseline, so git-p4son merges the two versions against an empty
-base: identical content merges cleanly, otherwise the file gets a single conflict block containing both full
-versions for you to resolve.
-
-**binary files** - Binary files that have local changes cannot be three-way merged. git-p4son restores your local
-version to disk after the sync commit so it shows up in `git status` for you to handle manually.
-
-**added locally, deleted upstream** - A file with local changes in git was deleted in Perforce. git-p4son lets the
-delete stand and warns you - your version remains available in git history.
-
-**deleted locally, added upstream** - A file you deleted from git was modified in Perforce. The Perforce version is
-kept in the sync commit. You can delete it again if you want.
-
-**ignored** - Files ignored by `.gitignore` are skipped with a warning. These are outside git's domain and should
-be managed manually or via Perforce directly.
-
-After syncing, git-p4son prints a summary of how each writable file was handled, and instructs you to review and
-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: 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`.
-
-## Configuration
-
-git-p4son keeps its per-repository settings in `.git-p4son/config.toml`. `init`, `writable` and `sync-split-users`
-write most of them; the rest you edit by hand.
-
-- `[depot] root` (string, set by `init`): the depot path `sync` syncs, e.g. `//$(workspace)` or
-  `//$(workspace)/Engine`. See [Init Command](#init-command)
-- `[core] writable` (`true` or `false`, default `false`): [writable mode](#writable-command), which keeps
-  git-tracked files writable
-- `[core] backend` (`"auto"`, `"git"` or `"jj"`, default `"auto"`): the tool git-p4son follows for the change, the
-  base and the branch. `auto` means jj in a [jj workspace](#jujutsu-jj) and git otherwise
-- `[sync] branch` (string, set by `init`): the sync branch, which `sync` commits onto from whatever branch you are
-  on. Without it, `sync` uses `main`. See [Sync Command](#sync-command)
-- `[sync] split-users` (list of strings, default empty): the users whose changelists `sync` gives a commit each;
-  `$(user)` stands for you. See [Split users](#split-users)
-- `[sync] blocking-processes` (list of strings, default empty): processes that stop a sync while they run. See
-  [Blocking processes](#blocking-processes)
-- `[hooks.extension-associations]` (table, Windows only): the command that runs a hook script, by file extension.
-  See [Hooks](#hooks)
-
-For example:
-
-```toml
-[depot]
-root = "//$(workspace)"
-
-[core]
-writable = true
-
-[sync]
-split-users = ["$(user)", "alice"]
-blocking-processes = ["UnrealEditor"]
-```
-
-A value of the wrong type, such as `writable = "true"` or `split-users = "alice"`, or a file that is not valid TOML,
-stops the command with an error naming the setting, so a typo is never silently ignored.
+## Commands
 
-## Usage
+git-p4son provides eleven commands:
 
-git-p4son provides eleven commands: `init`, `sync`, `sync-split-users`, `new`, `update`, `review`,
-`list-changes`, `alias`, `writable`, `completion`, and `skill`.
+| Command | What it does |
+| --- | --- |
+| [`init`](#init-command) | Set up a git repository in a Perforce workspace |
+| [`sync`](#sync-command) | Sync the workspace from Perforce and commit the changes to `main` |
+| [`sync-split-users`](#sync-split-users-command) | Show or edit the users whose changelists `sync` commits one by one |
+| [`new`](#new-command) | Create a changelist from the commits on your branch, optionally with a review |
+| [`update`](#update-command) | Add the newer commits to an existing changelist |
+| [`review`](#review-command) | Create a review with one shelf per commit |
+| [`list-changes`](#list-changes-command) | List the commit subjects since a base branch |
+| [`alias`](#alias-command) | Manage the names that stand for changelist numbers |
+| [`writable`](#writable-command) | Keep git-tracked files writable, without `p4 edit` first |
+| [`completion`](#completion-command) | Print the path to a shell completion script |
+| [`skill`](#skill-command) | Install or show the Claude Code skill |
 
 To see help for any command, use `-h`:
 
@@ -339,48 +221,37 @@ Alternatively, call the executable directly: `git-p4son --help`.
 
 ### Init Command
 
-Initialize a git repository inside a Perforce workspace:
+Set up git-p4son in a Perforce workspace, from anywhere inside it:
 
 ```sh
 git p4son init
 ```
 
-This command checks that it runs in a Perforce workspace, then asks for the depot root, writable mode, split users,
-the Claude Code skill and jj. It then sets up `.gitignore`, runs `git init` and creates a first commit holding only
-`.gitignore`. It ends by listing the next steps.
-
-The depot root determines which part of the Perforce workspace git-p4son syncs. You can choose to sync the entire
-workspace or just the directory's subtree where the git root is placed. The selection is saved in
-`.git-p4son/config.toml` and used by all subsequent commands.
+`init` checks that it runs in a Perforce workspace, then asks:
 
-Nothing in `.git-p4son/` belongs in git. The folder has its own `.gitignore` that ignores everything in it, so there
-is no need to list it in the workspace `.gitignore`.
+- **Depot root:** which part of the workspace git-p4son syncs, the whole workspace or the subtree the git root is in.
+  It's saved as `[depot] root` in `.git-p4son/config.toml`, with a `$(workspace)` placeholder for the workspace name,
+  e.g. `//$(workspace)/Engine`, so renaming the workspace doesn't break it. A concrete name works too.
+- **Writable mode:** 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.
+- **Split users:** whether to sync your own changelists one by one, as a [split user](#split-users), defaulting to the
+  current setting. Yes adds a `$(user)` entry and no removes it; other split users are left alone.
+- **Claude Code skill:** if Claude Code is installed, whether to install the [skill](#claude-code-skill). An installed
+  skill is refreshed without asking.
+- **jj:** with jj 0.41 or newer, whether to colocate jj and add the `jj p4son` alias, as described below.
 
-The saved root uses a `$(workspace)` placeholder for the workspace (client) name, e.g.
-`root = "//$(workspace)/Engine"`. git-p4son substitutes the live workspace name each time it runs, so renaming
-the Perforce workspace does not break the config. You can still store a concrete name (e.g. `//my-workspace/Engine`)
-by hand-editing `config.toml`; both forms work.
+Then it sets up the repository:
 
-The `.gitignore` is set up using this priority:
-- If `.gitignore` already exists, it is left as is
-- If `.p4ignore` exists, it is copied to `.gitignore` as a starting point
-- Otherwise, an empty `.gitignore` is created
+- **`.gitignore`:** kept if it exists, else copied from `.p4ignore`, else created empty.
+- **git:** `git init`, and a first commit holding only `.gitignore`.
+- **Sync branch:** recorded as `[sync] branch`. In a repository it creates, that's the branch `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 the local branches.
+  A branch already set is kept.
 
-`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.
+It ends by listing the next steps. Nothing in `.git-p4son/` belongs in git: the folder has its own `.gitignore` that
+ignores everything in it.
 
-`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.
-
-`init` records the [sync branch](#sync-command) as `[sync] branch`. In a repository it creates, that's the branch
-`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
-the local branches. It keeps a branch already set.
-
-If Claude Code is installed, `init` offers to install the [Claude Code skill](#claude-code-skill). An
-already installed skill is refreshed without asking.
-
-With jj 0.41 or newer installed, `init` offers two things for [jj](#jujutsu-jj):
+For [jj](#jujutsu-jj), `init` offers:
 
 - **Colocating jj**, when the workspace has no `.jj` folder: "Use jj in this workspace too (colocated)?", default
   no. On yes, in an existing repository it runs `jj git init --colocate` as its last step, so jj imports the branch
@@ -394,34 +265,19 @@ Running `init` again asks neither once they are done.
 
 ### Sync Command
 
-Sync local git repository with a Perforce workspace:
+Sync the workspace from Perforce and commit what changed onto the sync branch, `main` by default:
 
 ```sh
-git p4son sync [changelist ...] [--branch BRANCH] [--force] [--dry-run] [--split-user NAME ...] [--no-split]
-               [--ignore-blocking-processes]
+git p4son sync [changelist ...] [--branch BRANCH] [--no-rebase] [--force] [--dry-run] [--split-user NAME ...]
+               [--no-split] [--ignore-blocking-processes]
 ```
 
-`sync` commits onto the sync branch, `[sync] branch` in `.git-p4son/config.toml`, which `init` sets and which
-defaults to `main`. From another branch, it checks the sync branch out, syncs and commits, then returns you to
-where you started, telling you to `git rebase` your branch onto the sync branch; it doesn't rebase for you. The
-pre-sync and post-sync hooks run on the sync branch. You stay on the sync branch when:
-
-- local changes were [merged back](#how-sync-handles-writable-files) into the work tree, for you to review and
-  commit there
-- a sync fails partway, with the files as Perforce left them and the commits so far kept
-
-A failing pre-sync hook, or anything else that stops `sync` before it syncs, returns you to where you started.
-
 **Arguments:**
 - `changelist` (optional): Changelist number, `last-synced` to re-sync the last synced changelist, or `head`
   to sync to the latest changelist. Omit to sync to the latest changelist affecting the workspace. Several
   strictly increasing changelist numbers may be given to sync each in sequence, producing one commit per
   changelist. A trailing `head` may close out such a sequence to finish at the latest changelist.
 
-`sync` requires clean git and Perforce workspaces: no uncommitted changes, untracked files included, and no
-git-tracked files opened in Perforce. It checks them after any [blocking processes](#blocking-processes) and before
-the [pre-sync hooks](#pre-sync-hook).
-
 **Options:**
 - `--branch BRANCH`: Commit onto this branch instead of `[sync] branch`. With the jj backend, the bookmark to move
   to each sync commit
@@ -452,6 +308,21 @@ git p4son sync --no-split   # sync without splitting out the configured split us
 git p4son sync --branch p4  # commit onto the p4 branch this time
 ```
 
+`sync` commits onto the sync branch, `[sync] branch` in `.git-p4son/config.toml`, which `init` sets and which
+defaults to `main`. From another branch, it checks the sync branch out, syncs and commits, then returns you to
+where you started, telling you to `git rebase` your branch onto the sync branch; it doesn't rebase for you. The
+pre-sync and post-sync hooks run on the sync branch. You stay on the sync branch when:
+
+- local changes were [merged back](#how-sync-handles-writable-files) into the work tree, for you to review and
+  commit there
+- a sync fails partway, with the files as Perforce left them and the commits so far kept
+
+A failing pre-sync hook, or anything else that stops `sync` before it syncs, returns you to where you started.
+
+`sync` requires clean git and Perforce workspaces: no uncommitted changes, untracked files included, and no
+git-tracked files opened in Perforce. It checks them after any [blocking processes](#blocking-processes) and before
+the [pre-sync hooks](#pre-sync-hook).
+
 #### Blocking processes
 
 Syncing while e.g. the Unreal editor is open lets p4 replace assets the editor still has loaded, so the editor
@@ -496,17 +367,61 @@ 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 Perforce query per split user, listing their changelists in the range
-being synced, then one batched query that checks each changelist found touched the workspace and finds the one before
-it. None of them scans the files of every changelist in the range, which on a large range can exceed the server's
-`maxscanrows`. They run 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.
+Finding the split users' changelists takes one Perforce query per split user and one more, none of which scans every
+file in the range, so a large range stays within the server's `maxscanrows`. They run after the checks and the
+pre-sync hooks, so those fail first. `--dry-run` skips the checks and hooks but still shows the resulting sequence.
 
-#### Hooks
+#### Sync hooks
 
 `sync` runs the [pre-sync](#pre-sync-hook) and [post-sync](#post-sync-hook) hooks.
 
+#### 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 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
+the last sync commit that touched the file, restores the read-only flag, and lets the sync overwrite the file.
+
+**writable-changed** - The file on disk differs from the last sync. This happens when you manually edit a file
+on `main` and commit it to git without submitting to Perforce. git-p4son lets the sync overwrite the file and
+includes it in the sync commit (so the commit reflects pure Perforce state), then three-way merges your local
+changes on top of the new Perforce content - similar to a `git rebase`. If the merge is clean, the result appears
+as an unstaged change. If there are conflicts, standard conflict markers are inserted for you to resolve.
+
+**added both locally and in Perforce** - A file you committed to git is also being added by Perforce (p4 has never
+synced it to your workspace). There is no common baseline, so git-p4son merges the two versions against an empty
+base: identical content merges cleanly, otherwise the file gets a single conflict block containing both full
+versions for you to resolve.
+
+**binary files** - Binary files that have local changes cannot be three-way merged. git-p4son restores your local
+version to disk after the sync commit so it shows up in `git status` for you to handle manually.
+
+**added locally, deleted upstream** - A file with local changes in git was deleted in Perforce. git-p4son lets the
+delete stand and warns you - your version remains available in git history.
+
+**deleted locally, added upstream** - A file you deleted from git was modified in Perforce. The Perforce version is
+kept in the sync commit. You can delete it again if you want.
+
+**ignored** - Files ignored by `.gitignore` are skipped with a warning. These are outside git's domain and should
+be managed manually or via Perforce directly.
+
+After syncing, git-p4son prints a summary of how each writable file was handled, and instructs you to review and
+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: 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`.
+
 ### Sync-Split-Users Command
 
 Show or edit the [split users](#split-users), the Perforce users whose changelists `sync` gives a commit each:
@@ -531,16 +446,13 @@ 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.
-
-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 sync with git](#keeping-the-changelist-in-sync-with-git)).
+Create a changelist from the commits since the base branch: their files are opened in it, and its description lists
+the commits. Optionally shelve it, or create a review in Swarm or another [review tool](#review-tools):
 
 ```sh
 git p4son new -b BASE_BRANCH [-m <message> | -F <file>] [alias] [--force] [--dry-run] [--no-edit]
-              [--no-alias] [--no-commit-list] [--shelve] [--review] [--per-commit]
+              [--no-alias] [--no-commit-list] [--shelve] [--review] [--review-tool NAME] [--per-commit]
+              [--ignore-out-of-date]
 ```
 
 **Arguments:**
@@ -553,24 +465,24 @@ git p4son new -b BASE_BRANCH [-m <message> | -F <file>] [alias] [--force] [--dry
 - `--no-commit-list`: Leave the enumerated commit list out of the changelist description, so it holds only the
   message
 - `-b, --base-branch BASE_BRANCH`: Required. The base the change starts from, for enumerating commits and finding
-  changed files: a branch or bookmark, or a commit exactly one points at. The alias records it by name, as a commit
-  would go stale after a sync and rebase, along with the commits since it the changelist includes, so `update`
-  knows where the next ones start. With `--no-alias` any commit will do
+  changed files: a branch or bookmark, or a commit exactly one points at, or with jj a change without a bookmark. The
+  alias records it by name, or a jj change by its change ID, as a commit would go stale after a sync and rebase, along
+  with the commits since it the changelist includes, so `update` knows where the next ones start. With `--no-alias`
+  any commit will do
 - `-f, --force`: Overwrite an existing alias file
 - `-n, --dry-run`: Pretend and print what would be done, but do not execute. Ends with `Dry run, nothing changed`
 - `--no-edit`: Skip opening changed files for edit in Perforce
 - `--no-alias`: Skip saving a changelist alias
 - `--shelve`: Shelve the changelist after creating it
-- `--review`: Add `#review` keyword and shelve to create a Swarm review
+- `--review`: Shelve and create a review with the default [review tool](#review-tools), Swarm unless
+  `[review-tool] default` names another. For Swarm, adds the `#review` keyword
+- `--review-tool NAME`: Push the review to this review tool instead of the default one: `swarm`, or a
+  `[review-tool.NAME]` in `.git-p4son/config.toml`. Implies `--review`. The alias records the tool, which
+  `update --shelve` then runs
 - `--per-commit`: Create the changelist on the first commit since the base branch, then update it once per later
   commit, as described below. Refuses `--no-edit` and `--no-alias`
-
-With `--per-commit`, `new` checks out the first commit since the base branch and runs `git p4son new` on it, then
-checks out each later commit and runs `git p4son update` on it, and finally returns to where you started. With
-`--shelve` or `--review`, every step shelves, so each commit shows up as its own patch in the Swarm review, and every
-step but the last sleeps 5 seconds to give Perforce/Swarm time to process the shelf. It needs a clean git
-workspace even with `--dry-run`. [`review`](#review-command) is `new --review --per-commit`, and describes the steps,
-the dry run and resuming after a failed step.
+- `--ignore-out-of-date`: Shelve even if files in the change are not at the latest revision (see
+  [Shelving only files at the latest revision](#shelving-only-files-at-the-latest-revision))
 
 **Examples:**
 ```sh
@@ -581,67 +493,28 @@ git p4son new -m "New feature" --review -b main
 git p4son new -m "New feature" --shelve --per-commit -b main   # a shelf per commit, without 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 sync with git](#keeping-the-changelist-in-sync-with-git)).
+
+With `--per-commit`, `new` checks out the first commit since the base branch and runs `git p4son new` on it, then
+checks out each later commit and runs `git p4son update` on it, and finally returns to where you started. With
+`--shelve` or `--review`, every step shelves, so each commit shows up as its own patch in the review. With Swarm,
+every step but the last sleeps 5 seconds to give Perforce/Swarm time to process the shelf; another review tool runs
+once per step instead. It needs a clean git workspace even with `--dry-run`. [`review`](#review-command) is
+`new --review --per-commit`, and describes the steps, the dry run and resuming after a failed step.
+
 ### Update Command
 
-Update an existing Perforce changelist with the commits it doesn't include yet. The message above the commit 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 sync with git](#keeping-the-changelist-in-sync-with-git)). Opening files requires a
-clean git workspace, untracked files included; `update` refuses to run otherwise. The check is skipped with
-`--no-edit`.
-
-**Changelists made by `new` or `review`.** Their alias records the base, by name, and the commits since it the
-changelist includes, by their jj change IDs or, with git, their author dates, which survive rebases and amends.
-`update` folds in the commits it doesn't know: it appends their subjects to the commit list, opens their files, and
-records them. The entries the list already has are left as they are, so an entry you reworded in the changelist
-stays as you wrote it. Every update counts, shelved or not.
-
-- `-b` only chooses which files to open, from that commit on, for example `-b main` to open them all again after a
-  manual `p4 revert`. The commit list is still only appended to. A `-b` above the last included commit is refused,
-  as the commits it skips would be counted without being opened.
-- An included commit that is gone from the branch, dropped or squashed into another, gets a warning, and the update
-  goes on with the new commits. Its patch stays in the review: to undo a shelved commit, revert it in a new commit.
-- A new commit below included ones is refused, as its own patch would undo the included commits above it. Move it
-  after them, then update again.
-- An amend, or a squash into an included commit, keeps the commit's identity, so `update` sees no new commit. With
-  nothing new, `update` opens every file since the base, which takes in what the amend added. With new commits as
-  well, run `update -b main` to open them.
-
-**After a sync.** A shelf holds whole files, so once a sync has changed files the changelist touches, its next shelf
-would mix those changes into the next commit's patch. So when `update --shelve` finds that the base moved since the
-last shelve, the branch was rebased onto it, and it changed such a file, it first inserts an empty commit, `Rebase
-onto CL <N>`, right after the last included commit, with the commits after it rebased onto it. Its shelf is a patch
-of its own, holding what the sync changed, and its entry keeps the commit list matching the patches.
-
-- With `--per-commit`, it's the first step. Without it, `update --shelve` shelves twice: at the rebase commit, then at
-  the tip.
-- An update without `--shelve` leaves the catch-up to the next one that shelves, and a changelist that was never
-  shelved has no patches to catch up. A dry run says what it would insert.
-
-**Other changelists**, whose alias records nothing (made by `alias new` or an older git-p4son), or named by a number
-no alias holds: the commits since the base branch, `HEAD~1` by default, replace their existing entries in the
-commit list (matched by subject) and new ones are appended; entries outside the range are kept and the list is
-renumbered.
-
-With `--per-commit`, `update` runs once per commit instead of once for the whole range, the way `new --per-commit`
-and `review` do after creating the changelist. It checks out each commit in turn, oldest first, runs the update on
-it, and returns to where you started. With `--shelve`, every commit gets a shelf of its own and so shows up as its
-own patch in the Swarm review.
-
-- **With a record,** plain `update --per-commit --shelve` runs on exactly the commits the changelist doesn't include
-  yet. `-b` is refused there, as it would shelve included commits again.
-- **Without one,** pass the range: `update -b HEAD~2 --per-commit --shelve` updates the changelist with the last two
-  commits, one at a time. The base is resolved once, before the first step, so a relative base like `HEAD~2` means
-  the same commit for every step.
-
-`-m`/`-F` is applied on the first step only. It needs a clean git workspace, also with `--no-edit`. If a step
-fails, `update` returns to where you started and names the step and commit that failed. The error ends with the
-command that resumes after the last commit that worked, so earlier commits get no second shelf; with a record,
-running the same command again does the same.
+Add the commits a changelist doesn't include yet: `update` opens their files for edit and appends their subjects to
+the commit list in the description, keeping the message above it unless `-m` or `-F` replaces it. It also reverts
+files that are no longer part of the change (see
+[Keeping the changelist in sync with git](#keeping-the-changelist-in-sync-with-git)). Opening files needs a clean git
+workspace, untracked files included, unless `--no-edit` skips it.
 
 ```sh
 git p4son update [changelist] [-m <message> | -F <file>] [--base-branch BASE_BRANCH] [--dry-run]
-                 [--no-commit-list] [--no-edit] [--shelve] [--per-commit]
+                 [--no-commit-list] [--no-edit] [--shelve] [--per-commit] [--ignore-out-of-date]
 ```
 
 **Arguments:**
@@ -652,16 +525,23 @@ git p4son update [changelist] [-m <message> | -F <file>] [--base-branch BASE_BRA
   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`: Where the commits to fold in start, for the commit list and the files to open.
-  Defaults to after the last commit the changelist includes, when its alias records that, else to `HEAD~1`
+  Defaults to after the last commit the changelist includes, when its alias records that, else to `HEAD~1`. When the
+  base the alias records no longer resolves, as a deleted branch or an abandoned or divergent jj change, `update`
+  refuses without `-b`, and with it records the new base, as `new` does. That base has to sit below the changelist's
+  first commit
 - `-n, --dry-run`: Pretend and print what would be done, but do not execute. Ends with `Dry run, nothing changed`
 - `--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. With a record, the new commits are then neither
   appended nor counted, so the next update that opens files includes them
-- `--shelve`: Re-shelve the changelist after updating
+- `--shelve`: Re-shelve the changelist after updating. For a review in a [review tool](#review-tools) other than
+  Swarm, as the alias records it, the tool then runs for the new shelf
 - `--per-commit`: Update the changelist once per commit it doesn't include yet, or since the base branch without
   a record, oldest first, with each commit checked out in turn. With `--shelve`, steps sleep 5 seconds between them
-  to give Perforce/Swarm time to process each shelf. `--dry-run` prints the steps, one per commit
+  to give Perforce/Swarm time to process each shelf, unless another review tool has the changelist. `--dry-run`
+  prints the steps, one per commit
+- `--ignore-out-of-date`: Shelve even if files in the change or the changelist are not at the latest revision (see
+  [Shelving only files at the latest revision](#shelving-only-files-at-the-latest-revision))
 
 **Examples:**
 ```sh
@@ -674,39 +554,95 @@ git p4son update --per-commit --shelve   # one shelf for each commit the changel
 git p4son update 12345 -b HEAD~2 --per-commit --shelve   # no record: the last two commits
 ```
 
+#### Which commits are new
+
+A changelist made by `new` or `review` has an alias that records its base and the commits it includes, by jj change
+ID or, with git, by author date, which survive rebases and amends. `update` adds only the commits it doesn't know,
+whether it shelves or not, and leaves the entries already in the commit list as they are, so an entry you reworded
+stays as you wrote it.
+
+- `-b` only chooses which files to open, for example `-b main` to open them all again after a manual `p4 revert`. A
+  `-b` above the last included commit is refused.
+- An included commit that is gone from the branch, dropped or squashed, gets a warning. Its patch stays in the
+  review: to undo a shelved commit, revert it in a new commit.
+- A new commit below included ones is refused, as its patch would undo the ones above it. Move it after them.
+- An amend keeps the commit's identity, so `update` sees nothing new and opens every file since the base, which
+  takes in the amend. With new commits as well, run `update -b main`.
+
+#### After a sync
+
+A shelf holds whole files, so after a sync that changed files the changelist touches, the next shelf would mix the
+sync's changes into your next patch. So when `update --shelve` finds you synced and rebased, it first inserts an
+empty commit, `Rebase onto CL <N>`, after the last included commit, and shelves it on its own: its patch holds what
+the sync changed. An update without `--shelve` leaves this to the next one that shelves, and a dry run says what it
+would insert.
+
+#### Changelists without a record
+
+For a changelist whose alias records no commits, made by `alias new` or an older git-p4son, or one named by a number
+no alias holds, `update` takes the commits since `-b`, `HEAD~1` by default. Their entries replace the ones in the
+commit list with the same subject, the others are appended, and the list is renumbered.
+
+#### One update per commit
+
+With `--per-commit`, `update` checks out each new commit in turn, oldest first, updates the changelist on it, and
+returns to where you started. With `--shelve`, each commit gets a shelf of its own, so it shows up as its own patch in
+the review. Without a record, give the range with `-b`, such as `-b HEAD~2` for the last two commits; with one, `-b`
+is refused, as it would shelve included commits again. `-m`/`-F` applies to the first step only, and the run needs a
+clean git workspace even with `--no-edit`.
+
+If a step fails, `update` returns to where you started and names the commit that failed, with the command that
+resumes after the last commit that worked. With a record, running the same command again does the same.
+
 ### Keeping the changelist in sync with git
 
-`new` and `update` open every file changed since the base branch in the changelist. A file can later stop being
+`new` and `update` open every file changed since the base branch in the changelist. A file git sees as renamed is
+opened as a `p4 move` from its old path to its new one, carrying any edit along, so Perforce keeps its history and the
+review shows the move with only the lines that changed. git finds a rename as `git diff -M` does, by at least half
+the content matching, whatever `diff.renames` says. A file renamed again later moves on from where it started, and an
+existing move stays opened through later edits. A file added earlier in the same change is renamed as an add, as it
+isn't in the depot yet, and a rename that only changes the case of the name is an edit, as a case-insensitive server
+sees one file.
+
+A file can later stop being
 part of the change, for example when a later commit undoes an edit, or a file is added in one commit and deleted
 in the next. Such files would otherwise stay opened as no-ops, so after opening files both commands revert them:
 
 - Files opened for edit that are unchanged compared to the depot are reverted with `p4 revert -a`. Changed files
   stay opened.
 - Files opened for add that are missing from disk are reverted.
-- Files opened for delete that git still has (deleted in one commit, restored in a later one) are reverted and
-  restored from git.
+- Files opened for delete that git still has (deleted in one commit, restored in a later one) are reverted, keeping
+  git's file.
+- Moves whose new path git no longer has, as the rename was undone, are reverted, which reverts both ends.
 
 Only files git-p4son has authority over are touched: files tracked by git, and files opened for add that are
 missing from disk. Anything else in the changelist, such as binaries that only exist in Perforce and were opened
-by hand, is left alone even when unchanged. Files opened with other actions (`move/add`, `integrate`, ...) are
-also left alone. This step is skipped with `--no-edit`.
+by hand, is left alone even when unchanged. Files opened with other actions (`integrate`, `branch`, ...) are also
+left alone. This step is skipped with `--no-edit`.
 
 Shelving (`--shelve`, `--review`) replaces the whole shelf with the changelist's opened files using
 `p4 shelve -r -a leaveunchanged`, so the shelf never holds stale files, and unchanged files that are still opened
 are left out of it.
 
+#### Shelving only files at the latest revision
+
+Before shelving, `new`, `update` and `review` check that the files are synced to the latest revision in the depot:
+the change's files, and for `update` also the files already opened in the changelist, or with `--no-edit` only
+those. A file is out of date when someone has submitted a newer revision, deleted it, or added a file of that name
+since your last sync. Shelved, it would show in the review against an older revision, and the changelist would need a
+resolve before it is submitted, so the command lists the files and refuses, before it changes anything. Run
+`git p4son sync`, rebase the change onto it and run the command again, or pass `--ignore-out-of-date` to shelve
+anyway; the command it gives to resume or rerun after a failure keeps the option. With `--per-commit`, the check
+covers every commit once, before the first step. Without shelving there is no check.
+
 ### Review Command
 
-Create a Swarm review with one shelf per commit. `review` is short for `git p4son new --review --per-commit`, taking the
-same arguments apart from `--review`, `--per-commit`, `--shelve`, `--no-edit` and `--no-alias`. It checks out the first
-commit since the base branch and runs `git p4son new --review` on it, then checks out each later commit and runs
-`git p4son update --shelve`, and finally returns to where you started. Every step but the last sleeps 5 seconds to give
-Perforce/Swarm time to process the shelf. The commits are reviewed where they are: to review them on top of the latest
-`main`, rebase first. Like `new`, it needs a clean git workspace, untracked files included, and checks it even with
-`--dry-run`.
+Create a review with one shelf per commit, so each commit is a patch of its own. `review` is short for
+`git p4son new --review --per-commit`:
 
 ```sh
 git p4son review -b BASE_BRANCH [alias] [-m <message> | -F <file>] [--force] [--dry-run] [--no-commit-list]
+                 [--review-tool NAME] [--ignore-out-of-date]
 ```
 
 **Arguments:**
@@ -722,20 +658,8 @@ git p4son review -b BASE_BRANCH [alias] [-m <message> | -F <file>] [--force] [--
 - `-n, --dry-run`: Print the steps, one per commit, without running them. Ends with `Dry run, nothing changed`
 - `--no-commit-list`: Leave the enumerated commit list out of the changelist description. Passed on to `new` and
   each `update` step
-
-A dry run prints the plan like this, with the base resolved to the commit every step uses; the message, which only
-the first step gets, is printed below it:
-
-```
-abc1234 First commit: git p4son new my-feature --review -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
-def5678 Second commit: git p4son update my-feature --shelve -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
-ghi9012 Third commit: git p4son update my-feature --shelve -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
-```
-
-If a step fails, `review` returns to where you started and names the step and commit that failed. Once the first
-step has created the changelist, the error also says how to finish: after fixing the problem, run the
-`git p4son update my-feature --shelve --per-commit -b <commit>` it prints, which resumes after the last commit that
-worked.
+- `--ignore-out-of-date`: Shelve even if files in the change are not at the latest revision (see
+  [Shelving only files at the latest revision](#shelving-only-files-at-the-latest-revision))
 
 **Examples:**
 ```sh
@@ -752,9 +676,30 @@ git p4son review -m "Add my feature" -b main --dry-run
 git p4son review -F description.txt -b main
 ```
 
+`review` checks out the first commit since the base branch and runs `git p4son new --review` on it, then checks out
+each later commit and runs `git p4son update --shelve`, and finally returns to where you started. With Swarm, every
+step but the last sleeps 5 seconds to give Perforce/Swarm time to process the shelf; another
+[review tool](#review-tools) runs once per step instead. The commits are reviewed where they are: to review them on top
+of the latest `main`, rebase first. Like `new`, it needs a clean git workspace, untracked files included, and checks
+it even with `--dry-run`.
+
+A dry run prints the plan like this, with the base resolved to the commit every step uses; the message, which only
+the first step gets, is printed below it:
+
+```
+abc1234 First commit: git p4son new my-feature --review -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
+def5678 Second commit: git p4son update my-feature --shelve -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
+ghi9012 Third commit: git p4son update my-feature --shelve -b 5f1d0e9c2a7b4e8d9c0b1a2f3e4d5c6b7a8f9e0d
+```
+
+If a step fails, `review` returns to where you started and names the step and commit that failed. Once the first
+step has created the changelist, the error also says how to finish: after fixing the problem, run the
+`git p4son update my-feature --shelve --per-commit -b <commit>` it prints, which resumes after the last commit that
+worked.
+
 ### List-Changes Command
 
-List commit subjects since a base branch in chronological order (oldest first):
+List the commit subjects since a base branch, oldest first and numbered, as a changelist description lists them:
 
 ```sh
 git p4son list-changes [--base-branch BASE_BRANCH] [--porcelain]
@@ -772,17 +717,12 @@ git p4son list-changes --base-branch main
 git p4son list-changes --base-branch main --porcelain
 ```
 
-This command is useful for generating changelist descriptions by listing all commit messages since the base branch,
-numbered sequentially.
-
 ### Alias Command
 
-Manage changelist aliases, stored one per file as `.git-p4son/aliases/<alias>.toml` (`changelist = 12345`, and
-with the jj backend `change = "<change ID>"`, the [jj change](#jujutsu-jj) it was made for). An alias that `new` or
-`review` saved also records the changelist's base and the commits since it it includes, which
-[`update`](#update-command) goes on from: `base`, `base_commit` and `included`, a list of the commits' identities.
-Aliases saved by older versions in `.git-p4son/changelists/` keep working, and move to `.git-p4son/aliases/` when
-written, or all at once with `alias clean`.
+Manage changelist aliases: names that stand for changelist numbers, so you can say `my-feature` instead of `12345`.
+`new` and `review` save one named after the branch, which also records what [`update`](#update-command) needs to go
+on from. Aliases are stored in `.git-p4son/aliases/`; ones saved by older versions in `.git-p4son/changelists/` keep
+working, and move when written, or all at once with `alias clean`.
 
 #### alias list
 
@@ -792,11 +732,6 @@ List all aliases and their changelist numbers:
 git p4son alias list
 ```
 
-**Examples:**
-```sh
-git p4son alias list
-```
-
 #### alias show
 
 Print the changelist number saved under an alias:
@@ -840,6 +775,36 @@ git p4son alias new 12345 myfeature
 git p4son alias new 67890 myfeature -f
 ```
 
+#### alias rename
+
+Rename an alias, keeping its changelist and everything it records for `update`:
+
+```sh
+git p4son alias rename [OLD] NEW [--force]
+```
+
+As with `git branch -m`, a single name is the new name for the current alias, the one the current branch names, or
+with jj the one that records the jj change. The `branch` keyword works for either name; as `NEW` it is the current
+branch or bookmark name, so the alias can follow a renamed branch.
+
+**Arguments:**
+- `OLD` (optional): The alias to rename. Defaults to the current alias
+- `NEW`: The new alias name
+
+**Options:**
+- `-f, --force`: Overwrite an existing alias of the new name
+
+**Examples:**
+```sh
+git p4son alias rename my-feature-v2              # the current alias, then: git branch -m my-feature-v2
+git p4son alias rename my-feature branch          # after git branch -m: follow the branch's new name
+git p4son alias rename my-feature my-feature-v2
+```
+
+With git, renaming the branch first means the branch no longer names the alias, so name both:
+`alias rename OLD branch`. With jj, `alias rename NEW` works before or after `jj bookmark rename`, as the alias
+records the jj change.
+
 #### alias delete
 
 Delete a changelist alias, or all of them:
@@ -852,8 +817,9 @@ git p4son alias delete [alias | --all]
 - `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
+- `--all`: Delete all aliases without prompting, whether their changelists are pending or not. To delete only those
+  that are not, use `alias clean`. An alias that can't be deleted is reported and skipped, and the command then exits
+  with 1
 
 **Examples:**
 ```sh
@@ -864,27 +830,37 @@ git p4son alias delete --all
 
 #### alias clean
 
-Clean up changelist aliases:
+Delete the aliases whose changelist is no longer pending, as it was submitted or deleted:
 
 ```sh
-git p4son alias clean
+git p4son alias clean [-n] [--porcelain]
 ```
 
-It first moves any aliases still in `.git-p4son/changelists/` to `.git-p4son/aliases/`, then lists all aliases and
-asks how to proceed:
-- `a` (all): Delete all aliases
-- `i` (interactive): Review each alias one by one
-- `q` (quit): Exit without deleting anything
+It first moves any aliases still in `.git-p4son/changelists/` to `.git-p4son/aliases/`, then goes through the aliases
+in name order: it looks up the alias's changelist in Perforce and deletes the alias if the changelist was submitted or
+doesn't exist. If p4 answers neither that nor pending for a changelist, it stops
+there, leaving that alias and the ones after it. A submit that renumbers the changelist leaves its old number behind,
+which counts as gone too. With the jj backend, an alias whose [jj change](#jujutsu-jj) is gone but whose changelist
+is still pending is kept; `alias list` marks it `(gone)`, and `alias delete` removes it.
+
+It ends under an `Alias clean done` heading with how many aliases it deleted and kept. If any couldn't be deleted,
+that line is a warning with how many failed, followed by an error, and the command exits with 1.
 
-In interactive mode, each alias is displayed in turn with a prompt:
-- `y` (yes): Delete this alias
-- `n` (no): Keep this alias
-- `a` (all): Delete this and all remaining aliases (handy for keeping the first few and sweeping the rest)
-- `q` (quit): Stop and keep remaining aliases
+To delete specific aliases, use `alias list` and `alias delete`.
+
+**Options:**
+- `-n, --dry-run`: List the aliases that would be deleted, without deleting or moving any. Ends with
+  `Dry run, nothing changed`
+- `--porcelain`: Print only one `<action> <alias> <CL>` line per alias, for scripts and agents. The action is `kept`,
+  `deleted`, or `failed` when the alias couldn't be deleted; with `-n` it is `would-keep` or `would-delete`. Errors
+  still go to stderr. A `failed` alias makes the exit code 1, after the lines for all aliases; a stop exits with 1,
+  with no line for the alias it stopped at or those after it.
 
 **Examples:**
 ```sh
+git p4son alias clean -n            # see which aliases would go
 git p4son alias clean
+git p4son alias clean --porcelain   # e.g. "deleted feature-login 12345"
 ```
 
 ### Writable Command
@@ -957,28 +933,116 @@ Most commands that accept an alias or changelist argument default to the current
 The keyword cannot be used in a detached HEAD state. Use `--no-alias` (on `new`) or supply an explicit
 alias name instead.
 
+## Configuration
+
+git-p4son keeps its per-repository settings in `.git-p4son/config.toml`. `init`, `writable` and `sync-split-users`
+write most of them; the rest you edit by hand.
+
+- `[depot] root` (string, set by `init`): the depot path `sync` syncs, e.g. `//$(workspace)` or
+  `//$(workspace)/Engine`. See [Init Command](#init-command)
+- `[core] writable` (`true` or `false`, default `false`): [writable mode](#writable-command), which keeps
+  git-tracked files writable
+- `[core] backend` (`"auto"`, `"git"` or `"jj"`, default `"auto"`): the tool git-p4son follows for the change, the
+  base and the branch. `auto` means jj in a [jj workspace](#jujutsu-jj) and git otherwise
+- `[sync] branch` (string, set by `init`): the sync branch, which `sync` commits onto from whatever branch you are
+  on. Without it, `sync` uses `main`. See [Sync Command](#sync-command)
+- `[sync] split-users` (list of strings, default empty): the users whose changelists `sync` gives a commit each;
+  `$(user)` stands for you. See [Split users](#split-users)
+- `[sync] blocking-processes` (list of strings, default empty): processes that stop a sync while they run. See
+  [Blocking processes](#blocking-processes)
+- `[review-tool] default` (string, default `"swarm"`): the [review tool](#review-tools) `new --review` and `review`
+  push to without `--review-tool`
+- `[review-tool.<name>]` (table): a [review tool](#review-tools)'s `command`, and its `new` and `update` arguments
+- `[core.script-runners]` (table, Windows only): the command that runs a hook script, by file extension.
+  See [Hooks](#hooks). The old `[hooks.extension-associations]` is still read, and `core.script-runners` wins where
+  both name an extension
+
+For example:
+
+```toml
+[depot]
+root = "//$(workspace)"
+
+[core]
+writable = true
+
+[sync]
+split-users = ["$(user)", "alice"]
+blocking-processes = ["UnrealEditor"]
+```
+
+A value of the wrong type, such as `writable = "true"` or `split-users = "alice"`, or a file that is not valid TOML,
+stops the command with an error naming the setting, so a typo is never silently ignored.
+
+## Review Tools
+
+`new --review` and `review` create a review in Swarm by default: the description gets a `#review` keyword, and Swarm
+picks up each shelf. A team that reviews with another tool, one that has to be run to post each shelf, configures the
+tool's command line under a name of its choosing in `.git-p4son/config.toml`:
+
+```toml
+[review-tool]
+default = "my-tool"
+
+[review-tool.my-tool]
+command = ["python", "tools/my-review.py", "--p4port", "$(p4port)", "--changelist", "$(changelist)"]
+new = ["create"]
+update = ["update"]
+```
+
+`--review-tool my-tool` pushes a review to it, and `default` makes it the default, so `--review-tool swarm` picks
+Swarm again. The alias records the changelist's tool, so `update --shelve` runs it again without naming it; to move a
+change to another tool, delete the changelist and its alias and create the review again. `--no-alias` is refused with
+any tool but Swarm.
+
+With a review tool other than Swarm, there is no `#review` keyword, and after each shelve of the review git-p4son runs
+`command` from the workspace root, once per commit with `review`. On the shelve of `new`, the `new` arguments are
+added to it, to create the review, and on the shelves of `update` the `update` ones, to add the new shelf as a
+revision of it. If the first run fails, the `update --shelve` that reruns it still gets the `new` arguments, as the
+review doesn't exist yet. Both are optional; without one, `command` runs as it is.
+
+`command`, `new` and `update` are lists, one string per argument; a single string is refused. No shell runs them,
+so they work the same on every platform and never need quoting. A program named by a relative path, such as
+`tools/review.exe`, is found from the workspace root, and a bare name, such as `python`, on `PATH`. A `.cmd` or `.ps1`
+script on Windows needs its interpreter named, such as `["pwsh", "-File", "tools/my-review.ps1"]`. `$(name)` in an
+argument is replaced:
+
+- `$(changelist)`: the pending changelist number
+- `$(workspace)`: the Perforce client workspace name
+- `$(user)`: the Perforce user
+- `$(p4port)`: the server address, as `p4 set P4PORT` gives it
+- any other name: the environment variable of that name, which on Windows ignores case. A name that is neither fails
+  the command before anything runs
+
+A replaced value stays within its argument, spaces and all. The command is echoed with the values in, so it can be
+rerun by hand; that also shows any token passed through an environment variable. Anything more, such as settings
+files or a sign-in, goes in a wrapper script of your own that the command runs.
+
+The first run can sign in or open a browser; later ones run once per shelve, often as the steps of a per-commit run,
+so keep them non-interactive. A tool that exits with a non-zero code fails the command. `review` then stops at that
+commit with the command that resumes it, which shelves the commit again and reruns the tool, and `new` names the
+`update <alias> --shelve` that reruns it once the tool works. `--dry-run` says which tool would run. The tool runs on
+the terminal, so its output shows as it is written and it can prompt. Like a hook, it runs under git-p4son's
+[jj lock](#locking-and-the-git-workflow), so it must not run jj commands that snapshot.
+
 ## Hooks
 
-Hooks work similarly to git hooks. They are executables (unix)/scripts (windows) that you place in
-the `.git-p4son/hooks/[hook-name]/` directory. These scripts will be called to add or modify behavior
-at defined times during git-p4son operations. Scripts get run in filename (lexicographically) sorted
-order.
+Like git hooks, hooks are programs git-p4son runs at set points of a command: executables, or on Windows scripts, in
+`.git-p4son/hooks/<hook-name>/`, run in filename order.
 
-The hook process CWD is the directory where git-p4son was invoked, and `GIT_P4SON_REPO_ROOT_DIR` is
-set to the git-p4son repository root. `GIT_P4SON_BACKEND` is `git` or `jj`, the [backend](#choosing-the-backend)
-the command runs with.
+A hook runs in the directory git-p4son was run from, with `GIT_P4SON_REPO_ROOT_DIR` set to the repository root and
+`GIT_P4SON_BACKEND` to `git` or `jj`, the [backend](#choosing-the-backend) the command runs with.
 
-On Windows, `.ps1`, `.nu`, `.sh`, and `.py` files are run with
-`powershell.exe -NoProfile -ExecutionPolicy Bypass -File`, `nu.exe`, `bash.exe`, and `python.exe` respectively.
-Customize or add Windows script associations in `.git-p4son/config.toml`:
+On Windows, `.ps1`, `.sh` and `.py` files run with `powershell.exe -NoProfile -ExecutionPolicy Bypass -File`,
+`bash.exe` and `python.exe`. Change or add script runners in `.git-p4son/config.toml`:
 
 ```toml
-[hooks.extension-associations]
+[core.script-runners]
 ".ps1" = ["pwsh.exe", "-NoProfile", "-File"]
-".py" = "python.exe"
+".nu" = "nu.exe"
 ```
 
-Non-executable or unrecognized hook files, and invalid association entries, are skipped with a warning.
+Non-executable or unrecognized hook files, and invalid runner entries, are skipped with a warning.
 
 ### pre-sync hook
 
@@ -1044,13 +1108,20 @@ With the jj backend in a jj workspace:
 - `new` records the change's ID in the alias it saves, so later commands find the alias by change, whatever the
   change's bookmarks or description have become since. A new alias is named after the one local bookmark at the
   change, with `/` replaced by `-`, or, with no bookmark or several, after the first 8 letters of its change ID.
+- When no alias records the change itself, as after adding changes on top of the one `new` recorded, the current
+  alias is the one recording the nearest change below it. The search stops at the first bookmark below the change,
+  so a bookmarked change stacked on another's CL doesn't take that CL's alias, and skips empty changes, which a sync
+  leaves behind for submitted CLs. In a stack without bookmarks, every change above `main` counts. jj doesn't move
+  a bookmark on `jj new`, so a bookmark left on the change `new` recorded stops the search from the changes above
+  it: move it to the tip with `jj bookmark move <name> --to @-`, or `--to @` when the working change has content.
 - An alias records one change, and a change one alias: `new` refuses a change another alias records, naming it, and
   `--force` moves the record to the new alias. `alias new` records no change. `alias list` shows each recorded change,
   marked `(gone)` once jj no longer has it.
 - The default message is the first line of the change's description. Use `jj describe`, `-m` or `-F`.
 - `-b/--base-branch` takes a jj revision that resolves to one change, such as a bookmark, change ID or commit ID.
   Where it has a default, it's the change's parent rather than git's `HEAD~1`. `new` and `review` record it as a
-  bookmark, so it has to name one, or resolve to a commit exactly one points at.
+  bookmark when it names one or resolves to a commit exactly one points at, and as its change ID when it has none, so
+  a local change kept under a stack, never submitted, can be the base. Several bookmarks at it is an error.
 - `new` and `update` use jj's snapshot of the working copy, check that it did not change while git-p4son took the
   lock, and refuse files jj left untracked. You do not need a separate committed change before opening files in
   Perforce. Before a Perforce revert overwrites a file, git-p4son saves the working file and puts it back
@@ -1147,44 +1218,35 @@ colocates with both settings.
 git matches `.gitignore` patterns without case when `core.ignorecase` is true, the default on Windows and macOS. jj
 always matches them with case, so it would track a `Thirdparty/` folder that git ignores through `ThirdParty/`.
 
-To keep jj from tracking them, git-p4son leaves each such folder, or file, out of jj's `snapshot.auto-track` for the
-repository, building on any value you have, for example `(all()) ~ root:Some/Plugin/Source/Thirdparty`. That's
-jj's own setting, so it works whatever `.gitignore` re-includes with `!`, which would outrank `.git/info/exclude`,
-and it leaves git alone. `jj status` then lists the folders under "Untracked paths". As the repository's value holds
-yours, a later change to your user-level `snapshot.auto-track` doesn't reach the repository.
-
-git-p4son does so when `init` colocates, passing the setting to `jj git init`, as jj snapshots straight away, and in
-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
-backend, as a sync can bring in new folders. To let jj track such a folder again, remove its `root:"..."` from
-`snapshot.auto-track`, with `jj config edit --repo`.
+git-p4son keeps jj from tracking them by leaving each such folder, or file, out of jj's `snapshot.auto-track` for the
+repository, building on any value you have, for example `(all()) ~ root:Some/Plugin/Source/Thirdparty`. `jj status`
+then lists them under "Untracked paths". It does so when `init` colocates, and at the end of each sync on the jj
+backend, as a sync can bring in new folders. To let jj track such a folder again, remove its `root:"..."` with
+`jj config edit --repo`. As the repository's value holds yours, a later change to your user-level
+`snapshot.auto-track` doesn't reach the repository.
 
 If jj tracks such files anyway, for example in a workspace colocated before git-p4son did this, git-p4son warns about
-the ones the change you're working on adds, unless it's a commit in the sync branch's history, which git made. The
-warning lists the `jj config set` that leaves them out and the `jj file untrack` command that stops tracking them,
-which leaves the files on disk. Both are quoted to paste into cmd, PowerShell or a POSIX shell alike. They name a
-folder only when git tracks nothing else in it, so files git tracks stay tracked. Files you track on purpose, with
-`jj file track --include-ignored`, are left alone.
+the ones your change adds. The warning lists the `jj config set` that leaves them out and the `jj file untrack` that
+stops tracking them, which leaves the files on disk. Both are quoted to paste into cmd, PowerShell or a POSIX shell.
+They name a folder only when git tracks nothing else in it, so files git tracks stay tracked. Files you track on
+purpose, with `jj file track --include-ignored`, are left alone.
 
 ### Locking, and the git workflow
 
 git-p4son holds jj's working-copy lock while commands run, including sync hooks and temporary Perforce reverts,
-so other jj processes cannot snapshot files halfway through. A busy lock stops the command. Queries during the
-command use a pinned jj operation without snapshotting.
-
-jj's first snapshot and final reconciliation happen outside the lock, and so do sync's rebase and return, so
-another jj command can import the finished git changes before git-p4son does: this is not one atomic jj
-transaction. `--verbose` logs the jj operation git-p4son pinned at the start. The lock does not keep out
-editors, git commands or other jj workspaces. If a command fails, look at the workspace before continuing: the
-lock is released, but Perforce operations that completed are not undone.
+so other jj processes cannot snapshot files halfway through. A busy lock stops the command. The lock does not keep
+out editors, git commands or other jj workspaces, and a command is not one atomic jj transaction: jj's first
+snapshot, the final import, and sync's rebase and return happen outside it. If a command fails, look at the workspace
+before continuing: Perforce operations that completed are not undone.
 
 Hooks must not run ordinary jj commands, which would wait for the lock their caller holds. Read-only queries such
-as `jj --at-op=@ log` avoid snapshotting and the git import. A hook that runs git-p4son itself needs
-`--backend git`, which reuses the caller's lock.
+as `jj --at-op=@ log` are fine, and a hook that runs git-p4son itself needs `--backend git`, which reuses the
+caller's lock.
 
-`review`, `new --per-commit` and `update --per-commit` run once per commit since the base, up to the jj change, as they
-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
-at the end, also when a step fails, so jj sees no change. No jj command runs, and untracked and ignored files are left
-alone. They refuse to start if files changed after jj's snapshot, as the checkouts would overwrite them:
+`review`, `new --per-commit` and `update --per-commit` run once per commit since the base, as they 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 at the end,
+also when a step fails, so jj sees no change. Untracked and ignored files are left alone. They refuse to start if
+files changed after jj's snapshot, as the checkouts would overwrite them:
 
 ```sh
 git p4son review -b main
@@ -1277,3 +1339,39 @@ source $(git-p4son completion zsh --jj)         # ~/.zshrc, after compinit
 Each loads the `git p4son` completion for its shell too. If you named the alias something other than `p4son`, set
 `GIT_P4SON_JJ_ALIAS` to its name.
 
+## Development
+
+To install from source in editable mode:
+
+```sh
+git clone https://github.com/neoboid/git-p4son.git
+cd git-p4son
+pip install -e .
+```
+
+The `-e` flag installs the package in "editable" mode, meaning changes to the code are immediately available
+without reinstalling. This is also handy if you want to auto-update git-p4son whenever you pull from GitHub.
+
+git-p4son only uses Python standard library modules - no additional packages are required.
+
+Run the tests with `python -m pytest tests/` (`pip install pytest`). With `pytest-xdist` installed, add
+`-n auto --maxprocesses 8` to run them in parallel, which is about three times faster.
+
+### Git Hooks
+
+The repository includes git hooks in the `hooks/` directory:
+
+- **pre-commit** - verifies that staged Python files are formatted with `autopep8`. Install it with
+  `pip install autopep8`.
+- **pre-push** - runs the test suite and blocks the push if any test fails. It needs `pytest` installed, and runs
+  the tests in parallel when `pytest-xdist` is too.
+
+To activate the hooks, run:
+
+```sh
+scripts/setup-hooks.sh
+```
+
+This configures `core.hooksPath` so git uses the hooks from the repository. You only need to run this once after
+cloning.
+