cmd(git): Add Manager/Cmd pattern for git subcommands (#465)

Introduces typed Python objects for git subcommands instead of raw strings.

New features:
- Manager classes: GitBranchManager, GitRemoteManager, GitStashManager,
  GitTagManager, GitWorktreeManager, GitNotesManager, GitSubmoduleManager,
  GitReflogManager
- Cmd classes for per-entity operations on branches, remotes, stashes, tags,
  worktrees, notes, submodules, and reflog entries
- All ls() methods return QueryList for chainable filtering
- Enhanced Git.init() with ref_format, make_parents, octal shared permissions

Bug fixes:
- Git.run(): Fix boolean config serialization, -C path iteration, add
  config_env
- Git.clone(): Fix reference_if_able flag, separate_git_dir quoting
- Git.fetch()/pull(): Remove clone-only params, add recurse_submodules,
  fix --signoff spelling
- Git.rebase(): Fix --no-rerere-autoupdate typo, whitespace options
- Git.init(): Remove invalid --default, fix shared=False behavior
- Forward **kwargs in all Manager/Cmd run() methods
- GitRemoteManager.ls(): Handle URLs with spaces
- GitNoteCmd: Propagate custom ref to commands
- GitNotesManager.merge(): Handle commit/abort forms
- GitStashCmd.push(): Handle str paths
- stash.pop(): Use stash@{N} format
- branch.create(): Use git branch instead of checkout -b
- remote.add(): Wire fetch, track, master params
- remote.show(): Only add --verbose when explicitly True

Documentation:
- API docs for all new Manager/Cmd classes
- Split git subcommand docs into separate pages
- Usage examples in README and quickstart

Tests:
- Comprehensive coverage for all new Manager/Cmd classes

Author: tony

CHANGES

@@ -20,6 +20,59 @@ $ uv add libvcs --prerelease allow
 
 _Upcoming changes will be written here._
 
+### New features
+
+#### cmd: Manager/Cmd pattern for git subcommands (#465)
+
+New architecture for git subcommands that returns typed objects instead of raw strings:
+
+- **Manager classes** handle collection-level operations (`ls()`, `get()`, `filter()`, `add()`/`create()`)
+- **Cmd classes** handle per-entity operations (`show()`, `remove()`, `rename()`)
+- All `ls()` methods return `QueryList` for chainable filtering
+
+New subcommand managers accessible via `Git` instance:
+
+- {attr}`Git.branches <libvcs.cmd.git.Git.branches>` -> {class}`~libvcs.cmd.git.GitBranchManager`
+- {attr}`Git.remotes <libvcs.cmd.git.Git.remotes>` -> {class}`~libvcs.cmd.git.GitRemoteManager`
+- {attr}`Git.stashes <libvcs.cmd.git.Git.stashes>` -> {class}`~libvcs.cmd.git.GitStashManager`
+- {attr}`Git.tags <libvcs.cmd.git.Git.tags>` -> {class}`~libvcs.cmd.git.GitTagManager`
+- {attr}`Git.worktrees <libvcs.cmd.git.Git.worktrees>` -> {class}`~libvcs.cmd.git.GitWorktreeManager`
+- {attr}`Git.notes <libvcs.cmd.git.Git.notes>` -> {class}`~libvcs.cmd.git.GitNotesManager`
+- {attr}`Git.submodules <libvcs.cmd.git.Git.submodules>` -> {class}`~libvcs.cmd.git.GitSubmoduleManager`
+- {attr}`Git.reflog <libvcs.cmd.git.Git.reflog>` -> {class}`~libvcs.cmd.git.GitReflogManager`
+
+Example usage:
+
+```python
+git = Git(path="/path/to/repo")
+
+# List all branches, filter remote ones
+remote_branches = git.branches.ls(remotes=True)
+
+# Get a specific tag
+tag = git.tags.get(tag_name="v1.0.0")
+tag.delete()
+
+# Create a new branch and switch to it
+git.branches.create("feature-branch")
+```
+
+#### cmd: Enhanced Git.init() (#465)
+
+- Added `ref_format` parameter for `--ref-format` (files/reftable)
+- Added `make_parents` parameter to auto-create parent directories
+- Improved parameter validation with clear error messages
+- Extended `shared` parameter to support octal permissions (e.g., "0660")
+
+### Documentation
+
+- Add API documentation for all new Manager/Cmd classes (#465)
+- Split git subcommand documentation into separate pages: branch, tag, worktree, notes, reflog
+
+### Tests
+
+- Comprehensive test coverage for all new Manager/Cmd classes (#465)
+
 ## libvcs 0.37.0 (2025-11-01)
 
 ### Breaking changes

README.md

@@ -91,6 +91,31 @@ git.clone(url='https://github.com/vcs-python/libvcs.git')
 Above: [`libvcs.cmd.git.Git`](https://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git) using
 [`Git.clone()`](http://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git.clone).
 
+### Manage Branches, Tags, and More
+
+Work with git subcommands using typed Python objects:
+
+```python
+from libvcs.cmd.git import Git
+
+git = Git(path='/path/to/repo')
+
+# Branches
+branches = git.branches.ls()              # List all branches
+git.branches.create('feature-branch')     # Create a branch
+
+# Tags
+git.tags.create(name='v1.0.0', message='Release')
+tags = git.tags.ls()
+
+# Remotes
+remotes = git.remotes.ls()
+remote = git.remotes.get(remote_name='origin')
+remote.prune()
+```
+
+See the [Manager/Cmd pattern documentation](https://libvcs.git-pull.com/cmd/git/index.html) for more.
+
 ## Repository Synchronization
 
 Synchronize your repositories using the

docs/cmd/git/branch.md

@@ -0,0 +1,44 @@
+# `branch`
+
+For `git-branch(1)`.
+
+## Overview
+
+Manage git branches using {class}`~libvcs.cmd.git.GitBranchManager` (collection-level)
+and {class}`~libvcs.cmd.git.GitBranchCmd` (per-branch operations).
+
+### Example
+
+```python
+from libvcs.cmd.git import Git
+
+git = Git(path='/path/to/repo')
+
+# List all branches
+branches = git.branches.ls()
+
+# List remote branches only
+remote_branches = git.branches.ls(remotes=True)
+
+# Create a new branch
+git.branches.create('feature-branch')
+
+# Get a specific branch and operate on it
+branch = git.branches.get(branch_name='feature-branch')
+branch.rename('new-feature')
+branch.delete()
+```
+
+## API Reference
+
+```{eval-rst}
+.. autoclass:: libvcs.cmd.git.GitBranchManager
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+.. autoclass:: libvcs.cmd.git.GitBranchCmd
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/cmd/git/index.md

@@ -6,13 +6,63 @@ _Compare to: [`fabtools.git`](https://fabtools.readthedocs.io/en/0.19.0/api/git.
 [`salt.modules.git`](https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.git.html),
 [`ansible.builtin.git`](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/git_module.html)_
 
+## Manager/Cmd Pattern
+
+libvcs provides a **Manager/Cmd pattern** for git subcommands:
+
+- **Manager** classes (`git.branches`, `git.tags`, etc.) handle collection-level operations
+- **Cmd** classes represent individual entities with mutation methods
+
+```
+Git instance
+├── branches: GitBranchManager
+│   ├── ls() -> QueryList[GitBranchCmd]
+│   ├── get() -> GitBranchCmd
+│   └── create()
+├── tags: GitTagManager
+├── remotes: GitRemoteManager
+├── stashes: GitStashManager
+├── worktrees: GitWorktreeManager
+├── notes: GitNotesManager
+├── submodules: GitSubmoduleManager
+└── reflog: GitReflogManager
+```
+
+### Quick Example
+
+```python
+from libvcs.cmd.git import Git
+
+git = Git(path='/path/to/repo')
+
+# List all branches
+branches = git.branches.ls()
+
+# Filter to remote branches only
+remote_branches = git.branches.ls(remotes=True)
+
+# Get a specific branch and rename it
+branch = git.branches.get(branch_name='old-name')
+branch.rename('new-name')
+
+# Create and manage tags
+git.tags.create(name='v1.0.0', message='Release 1.0')
+tag = git.tags.get(tag_name='v1.0.0')
+tag.delete()
+```
+
 ```{toctree}
 :caption: Subcommands
 :maxdepth: 1
 
 submodule
 remote
 stash
+branch
+tag
+worktree
+notes
+reflog
 ```
 
 ```{eval-rst}
@@ -21,6 +71,23 @@ stash
    :show-inheritance:
    :undoc-members:
    :exclude-members: GitSubmoduleCmd,
+     GitSubmoduleManager,
+     GitSubmodule,
+     GitSubmoduleEntryCmd,
      GitRemoteCmd,
-     GitStashCmd
+     GitRemoteManager,
+     GitStashCmd,
+     GitStashManager,
+     GitStashEntryCmd,
+     GitBranchCmd,
+     GitBranchManager,
+     GitTagCmd,
+     GitTagManager,
+     GitWorktreeCmd,
+     GitWorktreeManager,
+     GitNoteCmd,
+     GitNotesManager,
+     GitReflogEntry,
+     GitReflogEntryCmd,
+     GitReflogManager
 ```

docs/cmd/git/notes.md

@@ -0,0 +1,45 @@
+# `notes`
+
+For `git-notes(1)`.
+
+## Overview
+
+Manage git notes using {class}`~libvcs.cmd.git.GitNotesManager` (collection-level)
+and {class}`~libvcs.cmd.git.GitNoteCmd` (per-note operations).
+
+### Example
+
+```python
+from libvcs.cmd.git import Git
+
+git = Git(path='/path/to/repo')
+
+# Add a note to a commit
+git.notes.add(object='HEAD', message='This is a note')
+
+# List all notes
+notes = git.notes.ls()
+
+# Get a specific note and operate on it
+note = git.notes.get(object='HEAD')
+note.show()
+note.append(message='Additional info')
+note.remove()
+
+# Prune notes for non-existent objects
+git.notes.prune()
+```
+
+## API Reference
+
+```{eval-rst}
+.. autoclass:: libvcs.cmd.git.GitNotesManager
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+.. autoclass:: libvcs.cmd.git.GitNoteCmd
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/cmd/git/reflog.md

@@ -0,0 +1,47 @@
+# `reflog`
+
+For `git-reflog(1)`.
+
+## Overview
+
+Manage git reflog using {class}`~libvcs.cmd.git.GitReflogManager` (collection-level)
+and {class}`~libvcs.cmd.git.GitReflogEntryCmd` (per-entry operations).
+
+### Example
+
+```python
+from libvcs.cmd.git import Git
+
+git = Git(path='/path/to/repo')
+
+# List reflog entries
+entries = git.reflog.ls()
+
+# List entries for a specific ref
+head_entries = git.reflog.ls(ref='HEAD')
+
+# Check if reflog exists for a ref
+git.reflog.exists(ref='main')
+
+# Expire old reflog entries
+git.reflog.expire(ref='HEAD', expire='90.days.ago')
+```
+
+## API Reference
+
+```{eval-rst}
+.. autoclass:: libvcs.cmd.git.GitReflogManager
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+.. autoclass:: libvcs.cmd.git.GitReflogEntryCmd
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+.. autoclass:: libvcs.cmd.git.GitReflogEntry
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

docs/cmd/git/remote.md

@@ -2,7 +2,39 @@
 
 For `git-remote(1)`.
 
+## Overview
+
+Manage git remotes using {class}`~libvcs.cmd.git.GitRemoteManager` (collection-level)
+and {class}`~libvcs.cmd.git.GitRemoteCmd` (per-remote operations).
+
+### Example
+
+```python
+from libvcs.cmd.git import Git
+
+git = Git(path='/path/to/repo')
+
+# List all remotes
+remotes = git.remotes.ls()
+
+# Add a new remote
+git.remotes.add(name='upstream', url='https://github.com/org/repo.git')
+
+# Get a specific remote and operate on it
+origin = git.remotes.get(remote_name='origin')
+origin.show()
+origin.prune()
+origin.set_url('https://new-url.git')
+```
+
+## API Reference
+
 ```{eval-rst}
+.. autoclass:: libvcs.cmd.git.GitRemoteManager
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 .. autoclass:: libvcs.cmd.git.GitRemoteCmd
    :members:
    :show-inheritance: