Skip to content

Commit 5acef2b

Browse files
committed
docs(cmd/git): add Manager/Cmd pattern introduction
why: Help users understand the new architecture for git subcommands. what: - Add pattern overview with Manager vs Cmd explanation - Add tree diagram showing all available managers - Add quick example showing common operations
1 parent 7f6ea9b commit 5acef2b

1 file changed

Lines changed: 45 additions & 0 deletions

File tree

docs/cmd/git/index.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,51 @@ _Compare to: [`fabtools.git`](https://fabtools.readthedocs.io/en/0.19.0/api/git.
66
[`salt.modules.git`](https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.git.html),
77
[`ansible.builtin.git`](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/git_module.html)_
88

9+
## Manager/Cmd Pattern
10+
11+
libvcs provides a **Manager/Cmd pattern** for git subcommands:
12+
13+
- **Manager** classes (`git.branches`, `git.tags`, etc.) handle collection-level operations
14+
- **Cmd** classes represent individual entities with mutation methods
15+
16+
```
17+
Git instance
18+
├── branches: GitBranchManager
19+
│ ├── ls() -> QueryList[GitBranchCmd]
20+
│ ├── get() -> GitBranchCmd
21+
│ └── create()
22+
├── tags: GitTagManager
23+
├── remotes: GitRemoteManager
24+
├── stashes: GitStashManager
25+
├── worktrees: GitWorktreeManager
26+
├── notes: GitNotesManager
27+
├── submodules: GitSubmoduleManager
28+
└── reflog: GitReflogManager
29+
```
30+
31+
### Quick Example
32+
33+
```python
34+
from libvcs.cmd.git import Git
35+
36+
git = Git(path='/path/to/repo')
37+
38+
# List all branches
39+
branches = git.branches.ls()
40+
41+
# Filter to remote branches only
42+
remote_branches = git.branches.ls(remotes=True)
43+
44+
# Get a specific branch and rename it
45+
branch = git.branches.get(branch_name='old-name')
46+
branch.rename('new-name')
47+
48+
# Create and manage tags
49+
git.tags.create(name='v1.0.0', message='Release 1.0')
50+
tag = git.tags.get(tag_name='v1.0.0')
51+
tag.delete()
52+
```
53+
954
```{toctree}
1055
:caption: Subcommands
1156
:maxdepth: 1

0 commit comments

Comments
 (0)