git-p4son 0.2.11__tar.gz → 0.3.1__tar.gz

{git_p4son-0.2.11 → git_p4son-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-p4son
-Version: 0.2.11
+Version: 0.3.1
 Summary: Utility for keeping a Perforce workspace and local git repo in sync
 Author-email: Andreas Andersson <andreas@neoboid.com>
 License-Expression: MIT
@@ -156,41 +156,37 @@ cloning.
 
 These steps set up git-p4son in an existing Perforce workspace. You only need to do this once.
 
-1. **Enable clobber on your Perforce workspace.** Edit the workspace in
-   P4V to set the clobber flag, or run `p4 client` and change `noclobber` to `clobber` in the Options line.
-   See [Why clobber?](#why-clobber) for rationale.
-
-2. **Set a git editor** if you don't have one already. The `review` command opens an interactive rebase in your
+1. **Set a git editor** if you don't have one already. The `review` command opens an interactive rebase in your
    editor. If you haven't configured one, set it with:
    ```sh
    git config --global core.editor <editor>   # e.g. vim, nano, code --wait
    ```
 
-3. **Sync your workspace to a known changelist.** Pick a changelist to use as the starting point for your git
+2. **Sync your workspace to a known changelist.** Pick a changelist to use as the starting point for your git
    history:
    ```sh
    p4 sync //...@12345
    ```
 
-4. **Run `git p4son init`.** This can be anywhere inside your Perforce workspace — it doesn't have to be at the
+3. **Run `git p4son init`.** This can be anywhere inside your Perforce workspace - it doesn't have to be at the
    root:
    ```sh
    cd /path/to/your/workspace    # or a subdirectory of it
    git p4son init
    ```
-   The command verifies that you are inside a P4 workspace with clobber enabled, prompts you to select a depot
+   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.
 
-5. **Review `.gitignore`.** Edit the file to ensure build artifacts and other unwanted files are excluded.
+4. **Review `.gitignore`.** Edit the file to ensure build artifacts and other unwanted files are excluded.
 
-6. **Add and commit all files manually the first time**
+5. **Add and commit all files manually the first time**
    ```sh
    git add .
    git commit -m "Initial submit all files"
    ```
 
-7. **Run `git p4son sync`** to get your first official sync commit
+6. **Run `git p4son sync`** to get your first official sync commit
    ```sh
    git p4son sync
    ```
@@ -199,19 +195,41 @@ 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.
 
-### Why clobber?
+### 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:
+
+**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.
 
-When you switch branches with `git checkout`, git overwrites the files that differ between the source and target branch.
-In doing so, it always removes the read-only flag - this is just how git works.
+**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.
 
-Now imagine one of those files has also been modified in Perforce. The next time `p4 sync` runs, Perforce will complain
-that a file was changed outside its control. At that point you have two options: either force-sync the individual file
-with `p4 sync -f //path/to/file`, or enable the `clobber` flag on your workspace so that Perforce silently overwrites
-writable files.
+**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.
 
-This is not specific to git-p4son - any workflow that combines git and Perforce in the same workspace will run into it.
-And in practice it is harmless: your local changes live on feature branches in git, so when you rebase onto `main` after
-a sync, your changes are reapplied on top of the latest Perforce state.
+**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.
 
 ## Usage
 
@@ -241,13 +259,18 @@ Initialize a git repository inside a Perforce workspace:
 git p4son init
 ```
 
-This command checks preconditions (Perforce workspace, clobber flag), configures the depot root, runs `git init`,
+This command checks preconditions (Perforce workspace), configures the depot root, runs `git init`,
 sets up `.gitignore`, and creates an initial commit.
 
 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.
 
+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.
+
 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
@@ -258,24 +281,35 @@ The `.gitignore` is set up using this priority:
 Sync local git repository with a Perforce workspace:
 
 ```sh
-git p4son sync [changelist] [--force]
+git p4son sync [changelist ...] [--force]
 ```
 
 **Arguments:**
-- `changelist` (optional): Changelist number, or `last-synced` to re-sync the last synced changelist. Omit to
-  sync to the latest changelist affecting the workspace.
+- `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.
 
 **Options:**
-- `-f, --force`: Force sync encountered writable files and allow syncing to older changelists.
+- `-f, --force`: Allow syncing to changelists older than the current one.
 
 **Examples:**
 ```sh
 git p4son sync              # sync to latest
+git p4son sync head         # sync to latest (explicit)
 git p4son sync 12345
+git p4son sync 123 156 178  # sync each changelist in sequence, one commit each
+git p4son sync 123 156 head # sync 123, 156, then the latest changelist
 git p4son sync last-synced
 git p4son sync 12345 --force
 ```
 
+#### pre-sync hook
+
+Before `git-p4son sync` syncs any changelist, git-p4son runs [hooks](#hooks) from
+`.git-p4son/hooks/pre-sync/`. If any hook exits non-zero the sync is aborted. When a sequence of
+changelists is given, the pre-sync hooks run once, before the first sync.
+
 #### post-sync hook
 
 After a successful `git-p4son sync` that actually performs sync work, git-p4son runs [hooks](#hooks)
@@ -535,6 +569,13 @@ On Windows, `.ps1`, `.nu`, `.sh`, and `.py` files are run with `powershell.exe`,
 
 Non-executable or unrecognized hook files are skipped with a warning.
 
+### pre-sync hook
+
+Before `git-p4son sync` syncs any changelist, git-p4son runs executable hooks from
+`.git-p4son/hooks/pre-sync/`. If any hook exits with a non-zero code the sync is aborted before any
+changelist is synced. When a sequence of changelists is synced, the pre-sync hooks run only once,
+before the first sync.
+
 ### post-sync hook
 
 After a successful `git-p4son sync` that actually performs sync work, git-p4son runs executable hooks from

{git_p4son-0.2.11 → git_p4son-0.3.1}/README.md

@@ -133,41 +133,37 @@ cloning.
 
 These steps set up git-p4son in an existing Perforce workspace. You only need to do this once.
 
-1. **Enable clobber on your Perforce workspace.** Edit the workspace in
-   P4V to set the clobber flag, or run `p4 client` and change `noclobber` to `clobber` in the Options line.
-   See [Why clobber?](#why-clobber) for rationale.
-
-2. **Set a git editor** if you don't have one already. The `review` command opens an interactive rebase in your
+1. **Set a git editor** if you don't have one already. The `review` command opens an interactive rebase in your
    editor. If you haven't configured one, set it with:
    ```sh
    git config --global core.editor <editor>   # e.g. vim, nano, code --wait
    ```
 
-3. **Sync your workspace to a known changelist.** Pick a changelist to use as the starting point for your git
+2. **Sync your workspace to a known changelist.** Pick a changelist to use as the starting point for your git
    history:
    ```sh
    p4 sync //...@12345
    ```
 
-4. **Run `git p4son init`.** This can be anywhere inside your Perforce workspace — it doesn't have to be at the
+3. **Run `git p4son init`.** This can be anywhere inside your Perforce workspace - it doesn't have to be at the
    root:
    ```sh
    cd /path/to/your/workspace    # or a subdirectory of it
    git p4son init
    ```
-   The command verifies that you are inside a P4 workspace with clobber enabled, prompts you to select a depot
+   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.
 
-5. **Review `.gitignore`.** Edit the file to ensure build artifacts and other unwanted files are excluded.
+4. **Review `.gitignore`.** Edit the file to ensure build artifacts and other unwanted files are excluded.
 
-6. **Add and commit all files manually the first time**
+5. **Add and commit all files manually the first time**
    ```sh
    git add .
    git commit -m "Initial submit all files"
    ```
 
-7. **Run `git p4son sync`** to get your first official sync commit
+6. **Run `git p4son sync`** to get your first official sync commit
    ```sh
    git p4son sync
    ```
@@ -176,19 +172,41 @@ 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.
 
-### Why clobber?
+### 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:
+
+**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.
 
-When you switch branches with `git checkout`, git overwrites the files that differ between the source and target branch.
-In doing so, it always removes the read-only flag - this is just how git works.
+**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.
 
-Now imagine one of those files has also been modified in Perforce. The next time `p4 sync` runs, Perforce will complain
-that a file was changed outside its control. At that point you have two options: either force-sync the individual file
-with `p4 sync -f //path/to/file`, or enable the `clobber` flag on your workspace so that Perforce silently overwrites
-writable files.
+**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.
 
-This is not specific to git-p4son - any workflow that combines git and Perforce in the same workspace will run into it.
-And in practice it is harmless: your local changes live on feature branches in git, so when you rebase onto `main` after
-a sync, your changes are reapplied on top of the latest Perforce state.
+**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.
 
 ## Usage
 
@@ -218,13 +236,18 @@ Initialize a git repository inside a Perforce workspace:
 git p4son init
 ```
 
-This command checks preconditions (Perforce workspace, clobber flag), configures the depot root, runs `git init`,
+This command checks preconditions (Perforce workspace), configures the depot root, runs `git init`,
 sets up `.gitignore`, and creates an initial commit.
 
 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.
 
+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.
+
 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
@@ -235,24 +258,35 @@ The `.gitignore` is set up using this priority:
 Sync local git repository with a Perforce workspace:
 
 ```sh
-git p4son sync [changelist] [--force]
+git p4son sync [changelist ...] [--force]
 ```
 
 **Arguments:**
-- `changelist` (optional): Changelist number, or `last-synced` to re-sync the last synced changelist. Omit to
-  sync to the latest changelist affecting the workspace.
+- `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.
 
 **Options:**
-- `-f, --force`: Force sync encountered writable files and allow syncing to older changelists.
+- `-f, --force`: Allow syncing to changelists older than the current one.
 
 **Examples:**
 ```sh
 git p4son sync              # sync to latest
+git p4son sync head         # sync to latest (explicit)
 git p4son sync 12345
+git p4son sync 123 156 178  # sync each changelist in sequence, one commit each
+git p4son sync 123 156 head # sync 123, 156, then the latest changelist
 git p4son sync last-synced
 git p4son sync 12345 --force
 ```
 
+#### pre-sync hook
+
+Before `git-p4son sync` syncs any changelist, git-p4son runs [hooks](#hooks) from
+`.git-p4son/hooks/pre-sync/`. If any hook exits non-zero the sync is aborted. When a sequence of
+changelists is given, the pre-sync hooks run once, before the first sync.
+
 #### post-sync hook
 
 After a successful `git-p4son sync` that actually performs sync work, git-p4son runs [hooks](#hooks)
@@ -512,6 +546,13 @@ On Windows, `.ps1`, `.nu`, `.sh`, and `.py` files are run with `powershell.exe`,
 
 Non-executable or unrecognized hook files are skipped with a warning.
 
+### pre-sync hook
+
+Before `git-p4son sync` syncs any changelist, git-p4son runs executable hooks from
+`.git-p4son/hooks/pre-sync/`. If any hook exits with a non-zero code the sync is aborted before any
+changelist is synced. When a sequence of changelists is synced, the pre-sync hooks run only once,
+before the first sync.
+
 ### post-sync hook
 
 After a successful `git-p4son sync` that actually performs sync work, git-p4son runs executable hooks from

{git_p4son-0.2.11 → git_p4son-0.3.1}/git_p4son/__init__.py

@@ -7,6 +7,6 @@ creating and updating changelists, and managing Swarm reviews.
 
 CONFIG_DIR = '.git-p4son'
 
-__version__ = "0.2.11"
+__version__ = "0.3.1"
 __author__ = "Andreas Andersson"
 __email__ = "andreas@neoboid.com"

{git_p4son-0.2.11 → git_p4son-0.3.1}/git_p4son/alias.py

@@ -8,6 +8,7 @@ from .changelist_store import (
     list_changelist_aliases,
     delete_changelist_alias,
 )
+from .common import prompt_choice
 from .log import log
 
 
@@ -54,31 +55,6 @@ def alias_delete_command(args: argparse.Namespace) -> int:
     return 0
 
 
-def _prompt_choice(prefix: str, options: list[str]) -> str | None:
-    """Prompt until the response matches an option or its first letter.
-
-    The choices are rendered from the options, e.g. "[y]es / [n]o", so the
-    prompt and the accepted keys cannot drift apart. Options must have
-    unique first letters. Returns the chosen option, or None on EOF.
-    """
-    shorthands = {option[0]: option for option in options}
-    rendered = ' / '.join(f'[{option[0]}]{option[1:]}' for option in options)
-    keys = list(shorthands)
-    while True:
-        try:
-            response = input(f'{prefix} {rendered}: ').strip().lower()
-        except EOFError:
-            print()
-            return None
-
-        if response in shorthands:
-            return shorthands[response]
-        elif response in options:
-            return response
-        else:
-            print('Please enter ' + ', '.join(keys[:-1]) + f' or {keys[-1]}')
-
-
 def _clean_all(aliases: list[tuple[str, str]], workspace_dir: str) -> None:
     """Delete every alias without further prompting."""
     for name, _changelist in aliases:
@@ -98,7 +74,7 @@ def _clean_interactive(aliases: list[tuple[str, str]],
         log.heading(f'{name} -> CL {changelist}')
 
         if response != 'all':
-            response = _prompt_choice(
+            response = prompt_choice(
                 'Delete?', ['yes', 'no', 'all', 'quit'])
 
         if response is None or response == 'quit':
@@ -125,7 +101,7 @@ def alias_clean_command(args: argparse.Namespace) -> int:
     for name, changelist in aliases:
         log.info(f'{name} -> {changelist}')
 
-    mode = _prompt_choice('Delete?', ['all', 'interactive', 'quit'])
+    mode = prompt_choice('Delete?', ['all', 'interactive', 'quit'])
     if mode is None or mode == 'quit':
         log.info('Aborting')
         return 0

{git_p4son-0.2.11 → git_p4son-0.3.1}/git_p4son/changelist_store.py

@@ -11,7 +11,7 @@ from . import CONFIG_DIR
 from .log import log
 
 
-RESERVED_KEYWORDS = frozenset({'last-synced', 'branch'})
+RESERVED_KEYWORDS = frozenset({'last-synced', 'head', 'branch'})
 
 # Allowed characters: ASCII letters, digits, hyphen, underscore, dot.
 # Must not start or end with a dot, so "." and ".." are rejected and the

{git_p4son-0.2.11 → git_p4son-0.3.1}/git_p4son/cli.py

@@ -31,7 +31,10 @@ def create_parser() -> argparse.ArgumentParser:
         epilog="""
 Examples:
   git-p4son sync                # Sync to the latest changelist
+  git-p4son sync head           # Sync to the latest changelist (explicit)
   git-p4son sync 12345          # Sync to changelist 12345
+  git-p4son sync 123 156 178    # Sync each changelist in sequence, one commit each
+  git-p4son sync 123 156 head   # Sync 123, 156, then the latest changelist
   git-p4son sync last-synced    # Re-sync the last synced changelist
   git-p4son new -m "Fix bug"    # Create changelist, alias defaults to branch name
   git-p4son new -m "Fix bug" --review  # Create changelist, create Swarm review
@@ -66,7 +69,7 @@ Examples:
         'init',
         help='Initialize a git repository inside a Perforce workspace',
         description='Set up a new git repository inside a Perforce workspace. '
-        'Checks preconditions (P4 workspace, clobber flag), initializes git, '
+        'Checks preconditions (P4 workspace), initializes git, '
         'sets up .gitignore, and creates an initial commit.'
     )
 
@@ -78,18 +81,19 @@ Examples:
     )
     sync_parser.add_argument(
         'changelist',
-        nargs='?',
-        default=None,
-        help='Changelist number to sync, or "last-synced" to re-sync the last synced changelist. '
-             'Omit to sync to the latest changelist affecting the workspace'
+        nargs='*',
+        default=[],
+        metavar='CHANGELIST',
+        help='Changelist number(s) to sync, "last-synced" to re-sync the last synced changelist, '
+             'or "head" to sync to the latest changelist. Give several strictly increasing '
+             'changelist numbers to sync each in sequence, one commit per changelist; "head" may '
+             'close out such a sequence as a trailing target. Omit to sync to the latest '
+             'changelist affecting the workspace'
     )
     sync_parser.add_argument(
         '-f', '--force',
         action='store_true',
-        help='Force sync encountered writable files and allow syncing to older changelists. '
-             'When clobber is not enabled on your workspace, p4 will fail to sync files that '
-             'are read-only. git removes the readonly flag on touched files. Also allows '
-             'syncing to changelists older than the current one.'
+        help='Allow syncing to changelists older than the current one.'
     )
 
     # New subcommand

{git_p4son-0.2.11 → git_p4son-0.3.1}/git_p4son/common.py

@@ -36,6 +36,31 @@ def branch_to_alias(branch_name: str) -> str:
     return branch_name.replace('/', '-')
 
 
+def prompt_choice(prefix: str, options: list[str]) -> str | None:
+    """Prompt until the response matches an option or its first letter.
+
+    The choices are rendered from the options, e.g. "[y]es / [n]o", so the
+    prompt and the accepted keys cannot drift apart. Options must have
+    unique first letters. Returns the chosen option, or None on EOF.
+    """
+    shorthands = {option[0]: option for option in options}
+    rendered = ' / '.join(f'[{option[0]}]{option[1:]}' for option in options)
+    keys = list(shorthands)
+    while True:
+        try:
+            response = input(f'{prefix} {rendered}: ').strip().lower()
+        except EOFError:
+            print()
+            return None
+
+        if response in shorthands:
+            return shorthands[response]
+        elif response in options:
+            return response
+        else:
+            print('Please enter ' + ', '.join(keys[:-1]) + f' or {keys[-1]}')
+
+
 def _path_module_for(*paths: str):
     """Choose a path module that matches the given path strings."""
     if any('\\' in path or re.match(r'^[A-Za-z]:', path) for path in paths):

{git_p4son-0.2.11 → git_p4son-0.3.1}/git_p4son/complete.py

@@ -106,11 +106,16 @@ def _complete_positional(command, subcommand, positional_count,
     """Complete a positional argument."""
     aliases = _get_alias_names(workspace_dir)
 
-    if command == 'sync' and positional_count == 0:
-        candidates = [
-            ('last-synced', 'Re-sync last synced changelist'),
-        ]
-        return _filter(candidates, prefix)
+    if command == 'sync':
+        if positional_count == 0:
+            candidates = [
+                ('head', 'Sync to the latest changelist'),
+                ('last-synced', 'Re-sync last synced changelist'),
+            ]
+            return _filter(candidates, prefix)
+        # "head" may also close out a sequence of changelist numbers.
+        return _filter(
+            [('head', 'Sync to the latest changelist')], prefix)
 
     if command == 'update' and positional_count == 0:
         branch_candidates = _get_branch_candidates(prefix, workspace_dir)

{git_p4son-0.2.11 → git_p4son-0.3.1}/git_p4son/config.py

@@ -12,21 +12,40 @@ from . import CONFIG_DIR
 
 _BARE_KEY_RE = re.compile(r'^[A-Za-z0-9_-]+$')
 
+# Placeholder allowed in a stored depot root, substituted with the live
+# Perforce client (workspace) name each time the root is used. Storing e.g.
+# root = "//$(workspace)/Engine" keeps the config working after the workspace
+# is renamed, at the cost of one client-name lookup per command.
+WORKSPACE_PLACEHOLDER = '$(workspace)'
+
 
 def config_path(workspace_dir: str) -> str:
     """Return the path to the config file."""
     return os.path.join(workspace_dir, CONFIG_DIR, 'config.toml')
 
 
-def load_config(workspace_dir: str) -> dict:
-    """Read and parse the config file. Returns empty dict if missing."""
-    path = config_path(workspace_dir)
+def load_toml(path: str) -> dict:
+    """Read and parse a TOML file. Returns empty dict if missing."""
     if not os.path.exists(path):
         return {}
     with open(path, 'rb') as f:
         return tomllib.load(f)
 
 
+def write_toml(path: str, data: dict) -> None:
+    """Write data to a TOML file, creating parent directories as needed."""
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    # tomllib reads strict UTF-8, so write UTF-8 explicitly.
+    with open(path, 'w', encoding='utf-8') as f:
+        for section, values in data.items():
+            _write_table(f, _format_key(section), values)
+
+
+def load_config(workspace_dir: str) -> dict:
+    """Read and parse the config file. Returns empty dict if missing."""
+    return load_toml(config_path(workspace_dir))
+
+
 def save_config(workspace_dir: str, config: dict) -> None:
     """Merge config into the config file, section by section.
 
@@ -36,13 +55,7 @@ def save_config(workspace_dir: str, config: dict) -> None:
     merged = load_config(workspace_dir)
     for section, values in config.items():
         merged.setdefault(section, {}).update(values)
-
-    path = config_path(workspace_dir)
-    os.makedirs(os.path.dirname(path), exist_ok=True)
-    # tomllib reads strict UTF-8, so write UTF-8 explicitly.
-    with open(path, 'w', encoding='utf-8') as f:
-        for section, values in merged.items():
-            _write_table(f, _format_key(section), values)
+    write_toml(config_path(workspace_dir), merged)
 
 
 def _format_string(value: str) -> str:
@@ -87,3 +100,8 @@ def get_depot_root(workspace_dir: str) -> str | None:
     """Get the depot root from config, or None if not configured."""
     config = load_config(workspace_dir)
     return config.get('depot', {}).get('root')
+
+
+def expand_depot_root(depot_root: str, workspace_name: str) -> str:
+    """Substitute the live workspace name for the $(workspace) placeholder."""
+    return depot_root.replace(WORKSPACE_PLACEHOLDER, workspace_name)