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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-p4son
-Version: 0.2.9
+Version: 0.2.11
 Summary: Utility for keeping a Perforce workspace and local git repo in sync
 Author-email: Andreas Andersson <andreas@neoboid.com>
 License-Expression: MIT
@@ -276,6 +276,11 @@ git p4son sync last-synced
 git p4son sync 12345 --force
 ```
 
+#### post-sync hook
+
+After a successful `git-p4son sync` that actually performs sync work, git-p4son runs [hooks](#hooks)
+from `.git-p4son/hooks/post-sync/`.
+
 ### 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.
@@ -312,7 +317,11 @@ git p4son new -m "New feature" --review -b main
 
 ### Update Command
 
-Update an existing Perforce changelist description by replacing the enumerated commit list with the current commits since the base branch. By default also opens changed files for edit.
+Update an existing Perforce changelist description. Commits since the base branch replace their existing
+entries in the enumerated commit list (matched by subject) and new ones are appended; entries outside the
+range are kept and the list is renumbered. So `update -b main` rebuilds the whole list without duplicating
+it, while `update -b HEAD~3` only refreshes the last three entries. By default also opens changed files for
+edit.
 
 ```sh
 git p4son update [changelist] [--base-branch BASE_BRANCH] [--dry-run] [--no-desc] [--no-edit] [--shelve]
@@ -459,16 +468,21 @@ git p4son alias delete myfeature
 
 #### alias clean
 
-Interactively review and delete changelist aliases:
+Clean up changelist aliases:
 
 ```sh
 git p4son alias clean
 ```
 
-This command iterates through each alias, displays it, and prompts for action:
+The command 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
+
+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
+- `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
 
 **Examples:**
@@ -500,6 +514,32 @@ 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` and `review`) or supply an
 explicit alias name instead.
 
+## 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.
+
+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.
+
+On Windows, `.ps1`, `.nu`, `.sh`, and `.py` files are run with `powershell.exe`, `nushell.exe`, `bash.exe`, and
+`python.exe` respectively. Customize or add Windows script associations in `.git-p4son/config.toml`:
+
+```toml
+[hooks.extension-associations]
+".ps1" = ["pwsh.exe", "-NoProfile", "-File"]
+".py" = "python.exe"
+```
+
+Non-executable or unrecognized hook files are skipped with a warning.
+
+### post-sync hook
+
+After a successful `git-p4son sync` that actually performs sync work, git-p4son runs executable hooks from
+`.git-p4son/hooks/post-sync/`.
+
 ## Shell Completions
 
 Tab completion is available for bash, zsh, and PowerShell, including commands, flags, and dynamic alias names.
@@ -530,3 +570,4 @@ Add the following to your PowerShell profile (`$PROFILE`):
 ```
 
 All three enable completion for `git p4son <TAB>` and `git-p4son <TAB>`.
+

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

@@ -253,6 +253,11 @@ git p4son sync last-synced
 git p4son sync 12345 --force
 ```
 
+#### post-sync hook
+
+After a successful `git-p4son sync` that actually performs sync work, git-p4son runs [hooks](#hooks)
+from `.git-p4son/hooks/post-sync/`.
+
 ### 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.
@@ -289,7 +294,11 @@ git p4son new -m "New feature" --review -b main
 
 ### Update Command
 
-Update an existing Perforce changelist description by replacing the enumerated commit list with the current commits since the base branch. By default also opens changed files for edit.
+Update an existing Perforce changelist description. Commits since the base branch replace their existing
+entries in the enumerated commit list (matched by subject) and new ones are appended; entries outside the
+range are kept and the list is renumbered. So `update -b main` rebuilds the whole list without duplicating
+it, while `update -b HEAD~3` only refreshes the last three entries. By default also opens changed files for
+edit.
 
 ```sh
 git p4son update [changelist] [--base-branch BASE_BRANCH] [--dry-run] [--no-desc] [--no-edit] [--shelve]
@@ -436,16 +445,21 @@ git p4son alias delete myfeature
 
 #### alias clean
 
-Interactively review and delete changelist aliases:
+Clean up changelist aliases:
 
 ```sh
 git p4son alias clean
 ```
 
-This command iterates through each alias, displays it, and prompts for action:
+The command 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
+
+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
+- `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
 
 **Examples:**
@@ -477,6 +491,32 @@ 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` and `review`) or supply an
 explicit alias name instead.
 
+## 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.
+
+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.
+
+On Windows, `.ps1`, `.nu`, `.sh`, and `.py` files are run with `powershell.exe`, `nushell.exe`, `bash.exe`, and
+`python.exe` respectively. Customize or add Windows script associations in `.git-p4son/config.toml`:
+
+```toml
+[hooks.extension-associations]
+".ps1" = ["pwsh.exe", "-NoProfile", "-File"]
+".py" = "python.exe"
+```
+
+Non-executable or unrecognized hook files are skipped with a warning.
+
+### post-sync hook
+
+After a successful `git-p4son sync` that actually performs sync work, git-p4son runs executable hooks from
+`.git-p4son/hooks/post-sync/`.
+
 ## Shell Completions
 
 Tab completion is available for bash, zsh, and PowerShell, including commands, flags, and dynamic alias names.
@@ -507,3 +547,4 @@ Add the following to your PowerShell profile (`$PROFILE`):
 ```
 
 All three enable completion for `git p4son <TAB>` and `git-p4son <TAB>`.
+

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

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

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

@@ -54,43 +54,52 @@ def alias_delete_command(args: argparse.Namespace) -> int:
     return 0
 
 
-def _prompt_delete(prompt: str) -> str | None:
-    """Prompt until a valid y/n/a/q response is given. Returns None on EOF."""
+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(prompt).strip().lower()
+            response = input(f'{prefix} {rendered}: ').strip().lower()
         except EOFError:
             print()
             return None
 
-        if response in ('y', 'yes'):
-            return 'yes'
-        elif response in ('n', 'no'):
-            return 'no'
-        elif response in ('a', 'all'):
-            return 'all'
-        elif response in ('q', 'quit'):
-            return 'quit'
+        if response in shorthands:
+            return shorthands[response]
+        elif response in options:
+            return response
         else:
-            print('Please enter y, n, a, or q')
+            print('Please enter ' + ', '.join(keys[:-1]) + f' or {keys[-1]}')
 
 
-def alias_clean_command(args: argparse.Namespace) -> int:
-    """Execute the 'alias clean' command with interactive prompts."""
-    workspace_dir = args.workspace_dir
+def _clean_all(aliases: list[tuple[str, str]], workspace_dir: str) -> None:
+    """Delete every alias without further prompting."""
+    for name, _changelist in aliases:
+        if delete_changelist_alias(name, workspace_dir):
+            log.success(f'Deleted "{name}"')
 
-    aliases = list_changelist_aliases(workspace_dir)
-    if not aliases:
-        log.success('No changelist aliases to clean')
-        return 0
 
+def _clean_interactive(aliases: list[tuple[str, str]],
+                       workspace_dir: str) -> None:
+    """Review each alias in turn with yes/no/all/quit prompts.
+
+    The all option lets the user keep the first aliases and sweep the rest:
+    answer no until the last one worth keeping, then a deletes the
+    remainder without further prompts."""
     response = None
     for name, changelist in aliases:
         log.heading(f'{name} -> CL {changelist}')
 
         if response != 'all':
-            response = _prompt_delete(
-                'Delete? [y]es / [n]o / [a]ll / [q]uit: ')
+            response = _prompt_choice(
+                'Delete?', ['yes', 'no', 'all', 'quit'])
 
         if response is None or response == 'quit':
             log.info('Aborting')
@@ -102,6 +111,30 @@ def alias_clean_command(args: argparse.Namespace) -> int:
         if delete_changelist_alias(name, workspace_dir):
             log.success('Deleted')
 
+
+def alias_clean_command(args: argparse.Namespace) -> int:
+    """Execute the 'alias clean' command."""
+    workspace_dir = args.workspace_dir
+
+    aliases = list_changelist_aliases(workspace_dir)
+    if not aliases:
+        log.success('No changelist aliases to clean')
+        return 0
+
+    log.info(f'Found {len(aliases)}')
+    for name, changelist in aliases:
+        log.info(f'{name} -> {changelist}')
+
+    mode = _prompt_choice('Delete?', ['all', 'interactive', 'quit'])
+    if mode is None or mode == 'quit':
+        log.info('Aborting')
+        return 0
+
+    if mode == 'all':
+        _clean_all(aliases, workspace_dir)
+    else:
+        _clean_interactive(aliases, workspace_dir)
+
     return 0
 
 

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

@@ -19,6 +19,13 @@ RESERVED_KEYWORDS = frozenset({'last-synced', 'branch'})
 # (Windows disallows trailing dots).
 _ALIAS_NAME_RE = re.compile(r'^[A-Za-z0-9_-]([A-Za-z0-9._-]*[A-Za-z0-9_-])?$')
 
+# Windows device names; opening such a path hits the device namespace
+# instead of creating a file, on any drive and regardless of extension.
+_WINDOWS_RESERVED_NAMES = frozenset(
+    {'con', 'prn', 'aux', 'nul'}
+    | {f'com{i}' for i in range(1, 10)}
+    | {f'lpt{i}' for i in range(1, 10)})
+
 
 def validate_alias_name(name: str) -> str | None:
     """Return an error message if alias name is invalid, else None."""
@@ -30,6 +37,15 @@ def validate_alias_name(name: str) -> str | None:
         return (
             f'Invalid alias name "{name}": must contain only letters, digits, '
             'hyphens, underscores, and dots, and must not start or end with a dot')
+    if name.isdigit():
+        # Digit strings are always interpreted as changelist numbers, so
+        # such an alias could be created but never referenced.
+        return (
+            f'Invalid alias name "{name}": an all-digit name would be '
+            'indistinguishable from a changelist number')
+    if name.split('.', 1)[0].lower() in _WINDOWS_RESERVED_NAMES:
+        return (
+            f'Invalid alias name "{name}": reserved device name on Windows')
     return None
 
 
@@ -38,6 +54,18 @@ def _changelists_dir(workspace_dir: str) -> str:
     return os.path.join(workspace_dir, CONFIG_DIR, 'changelists')
 
 
+def _alias_path(name: str, workspace_dir: str) -> str | None:
+    """Validate name and return its store path, or None if invalid.
+
+    Validating on every lookup, not just on save, keeps raw user input
+    (e.g. "../../somefile") from escaping the store directory."""
+    error = validate_alias_name(name)
+    if error:
+        log.error(error)
+        return None
+    return os.path.join(_changelists_dir(workspace_dir), name)
+
+
 def alias_exists(name: str, workspace_dir: str) -> bool:
     """Check whether a changelist alias exists."""
     alias_path = os.path.join(_changelists_dir(workspace_dir), name)
@@ -46,13 +74,11 @@ def alias_exists(name: str, workspace_dir: str) -> bool:
 
 def save_changelist_alias(name: str, changelist: str, workspace_dir: str, force: bool = False) -> bool:
     """Save a changelist number under a named alias."""
-    error = validate_alias_name(name)
-    if error:
-        log.error(error)
+    alias_path = _alias_path(name, workspace_dir)
+    if alias_path is None:
         return False
 
     changelists_dir = _changelists_dir(workspace_dir)
-    alias_path = os.path.join(changelists_dir, name)
 
     if os.path.exists(alias_path) and not force:
         log.error(
@@ -71,7 +97,9 @@ def save_changelist_alias(name: str, changelist: str, workspace_dir: str, force:
 
 def load_changelist_alias(name: str, workspace_dir: str) -> str | None:
     """Load a changelist number from a named alias, or None if not found."""
-    alias_path = os.path.join(_changelists_dir(workspace_dir), name)
+    alias_path = _alias_path(name, workspace_dir)
+    if alias_path is None:
+        return None
 
     if not os.path.exists(alias_path):
         log.error(f'No changelist alias found: {name}')
@@ -108,7 +136,9 @@ def list_changelist_aliases(workspace_dir: str) -> list[tuple[str, str]]:
 
 def delete_changelist_alias(name: str, workspace_dir: str) -> bool:
     """Delete a changelist alias file."""
-    alias_path = os.path.join(_changelists_dir(workspace_dir), name)
+    alias_path = _alias_path(name, workspace_dir)
+    if alias_path is None:
+        return False
 
     if not os.path.exists(alias_path):
         log.error(f'No changelist alias found: {name}')

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

@@ -3,6 +3,7 @@ Main CLI entry point for git-p4son.
 """
 
 import argparse
+import os
 import sys
 import time
 from importlib.resources import files
@@ -148,6 +149,7 @@ Examples:
     )
     new_parser.add_argument(
         '-s', '--sleep',
+        type=int,
         help='Sleep for the specified number of seconds after the command is done'
     )
 
@@ -155,9 +157,11 @@ Examples:
     update_parser = subparsers.add_parser(
         'update',
         help='Update an existing changelist description and open files for edit',
-        description='Update an existing Perforce changelist description by '
-        'replacing the enumerated commit list with the current commits '
-        'since the base branch. By default also opens changed files for edit.'
+        description='Update an existing Perforce changelist description: '
+        'commits since the base branch replace their existing entries in '
+        'the enumerated commit list and new ones are appended; entries '
+        'outside the range are kept. By default also opens changed files '
+        'for edit.'
     )
     update_parser.add_argument(
         'changelist',
@@ -193,6 +197,7 @@ Examples:
     )
     update_parser.add_argument(
         '-s', '--sleep',
+        type=int,
         help='Sleep for the specified number of seconds after the command is done'
     )
 
@@ -267,9 +272,9 @@ Examples:
     # alias clean
     alias_subparsers.add_parser(
         'clean',
-        help='Interactive cleanup of changelist aliases',
-        description='Interactively review and delete changelist aliases with '
-        'yes/no/all/quit prompts'
+        help='Clean up changelist aliases',
+        description='List all changelist aliases, then delete all of them '
+        'or review each one interactively with yes/no/all/quit prompts'
     )
 
     # Review subcommand
@@ -378,6 +383,8 @@ def completion_command(args: argparse.Namespace) -> int:
 
 
 def run_command(args: argparse.Namespace) -> int:
+    args.invocation_dir = os.getcwd()
+
     log.heading('Finding workspace directory')
     args.workspace_dir = get_workspace_dir()
     if not args.workspace_dir:
@@ -465,7 +472,7 @@ def main() -> int:
         exit_code = run_command(args)
 
         if exit_code == 0 and getattr(args, 'sleep', None) is not None:
-            seconds = int(args.sleep)
+            seconds = args.sleep
             log.heading(f'Sleeping for {seconds} seconds')
             time.sleep(seconds)
             log.success('awake again')