Skip to content

Commit 44a8b41

Browse files
tonytony
committed
docs(notes): add CLI flag → Python parameter mappings
why: Document how git CLI flags map to Python parameters what: - Add flag mapping tables for all Manager and Cmd classes - Include existing methods and planned methods - Add parsing patterns for stash and reflog entries
1 parent f05f2e3 commit 44a8b41

1 file changed

Lines changed: 240 additions & 1 deletion

File tree

‎notes/2025-11-26-command-support.md‎

Lines changed: 240 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,18 @@ Manager (collection-level) Cmd (per-entity)
3333
| `get(**kwargs)` | Implemented | Get single branch by filter |
3434
| `filter(**kwargs)` | Implemented | Filter branches |
3535

36+
#### CLI Flag → Python Parameter Mapping: `ls()` Enhancements
37+
38+
| Git CLI Flag | Python Parameter | Description |
39+
|--------------|------------------|-------------|
40+
| `-a, --all` | `_all: bool` | List all branches (local + remote) |
41+
| `-r, --remotes` | `remotes: bool` | List remote branches only |
42+
| `--merged <commit>` | `merged: str \| None` | Filter merged branches |
43+
| `--no-merged <commit>` | `no_merged: str \| None` | Filter unmerged branches |
44+
| `-v, --verbose` | `verbose: bool` | Show tracking info |
45+
| `--contains <commit>` | `contains: str \| None` | Branches containing commit |
46+
| `--sort=<key>` | `sort: str \| None` | Sort key |
47+
3648
### GitBranchCmd (Per-entity)
3749

3850
| Method | Status | Description |
@@ -49,6 +61,17 @@ Manager (collection-level) Cmd (per-entity)
4961
| `unset_upstream()` | **Missing** | `--unset-upstream` |
5062
| `track(remote_branch)` | **Missing** | `-t` / `--track` |
5163

64+
#### CLI Flag → Python Parameter Mapping: GitBranchCmd Methods
65+
66+
| Method | Git CLI | Parameters → Flags |
67+
|--------|---------|-------------------|
68+
| `delete()` | `git branch -d/-D` | `force=True` → `-D`, else `-d` |
69+
| `rename(new_name)` | `git branch -m/-M` | `force=True` → `-M`, else `-m` |
70+
| `copy(new_name)` | `git branch -c/-C` | `force=True` → `-C`, else `-c` |
71+
| `set_upstream(upstream)` | `git branch --set-upstream-to=` | `upstream` → `--set-upstream-to={upstream}` |
72+
| `unset_upstream()` | `git branch --unset-upstream` | None |
73+
| `track(remote_branch)` | `git branch -t` | `remote_branch` → `-t {remote_branch}` |
74+
5275
### GitBranchManager Enhancements Needed
5376

5477
| Feature | Status | Description |
@@ -98,6 +121,24 @@ Properties: `remote_name`, `fetch_url`, `push_url`
98121
| `set_head(branch, auto, delete)` | **Missing** | `set-head` |
99122
| `update(prune)` | **Missing** | `update` |
100123

124+
#### CLI Flag → Python Parameter Mapping: Existing Methods
125+
126+
| Method | Parameters → Flags |
127+
|--------|-------------------|
128+
| `rename()` | `progress=True` → `--progress`, `progress=False` → `--no-progress` |
129+
| `show()` | `verbose=True` → `--verbose`, `no_query_remotes=True` → `-n` |
130+
| `prune()` | `dry_run=True` → `--dry-run` |
131+
| `get_url()` | `push=True` → `--push`, `_all=True` → `--all` |
132+
| `set_url()` | `push=True` → `--push`, `add=True` → `--add`, `delete=True` → `--delete` |
133+
134+
#### CLI Flag → Python Parameter Mapping: Missing Methods
135+
136+
| Method | Git CLI | Parameters → Flags |
137+
|--------|---------|-------------------|
138+
| `set_branches(*branches)` | `git remote set-branches` | `add=True` → `--add`, `branches` → positional |
139+
| `set_head(branch)` | `git remote set-head` | `auto=True` → `-a`, `delete=True` → `-d`, `branch` → positional |
140+
| `update()` | `git remote update` | `prune=True` → `-p` |
141+
101142
---
102143

103144
## 3. GitStashCmd (Current) → GitStashManager / GitStashEntryCmd (Planned)
@@ -128,12 +169,30 @@ Properties: `remote_name`, `fetch_url`, `push_url`
128169
| `push(message, path, patch, staged, keep_index, include_untracked)` | **Planned** | Push to stash |
129170
| `clear()` | **Planned** | Clear all stashes |
130171

172+
#### CLI Flag → Python Parameter Mapping: `push()`
173+
174+
| Git CLI Flag | Python Parameter | Description |
175+
|--------------|------------------|-------------|
176+
| `-p, --patch` | `patch: bool` | Interactive patch selection |
177+
| `-S, --staged` | `staged: bool` | Stash only staged changes |
178+
| `-k, --keep-index` | `keep_index: bool` | Keep index intact |
179+
| `-u, --include-untracked` | `include_untracked: bool` | Include untracked files |
180+
| `-a, --all` | `_all: bool` | Include ignored files |
181+
| `-q, --quiet` | `quiet: bool` | Suppress output |
182+
| `-m, --message <msg>` | `message: str \| None` | Stash message |
183+
| `-- <pathspec>` | `path: list[str] \| None` | Limit to paths |
184+
131185
### Planned GitStashEntryCmd (Per-entity)
132186

133187
Properties: `index: int`, `branch: str`, `message: str`
134188

135189
Parse from: `stash@{0}: On master: my message`
136190

191+
**Parsing pattern**:
192+
```python
193+
stash_pattern = r"stash@\{(?P<index>\d+)\}: On (?P<branch>[^:]+): (?P<message>.+)"
194+
```
195+
137196
| Method | Status | Description |
138197
|--------|--------|-------------|
139198
| `__init__(path, index, branch, message, cmd)` | **Planned** | Constructor |
@@ -143,6 +202,16 @@ Parse from: `stash@{0}: On master: my message`
143202
| `drop()` | **Planned** | Delete this stash |
144203
| `branch(branch_name)` | **Planned** | Create branch from stash |
145204

205+
#### CLI Flag → Python Parameter Mapping: GitStashEntryCmd Methods
206+
207+
| Method | Git CLI | Parameters → Flags |
208+
|--------|---------|-------------------|
209+
| `show()` | `git stash show` | `stat=True` → `--stat`, `patch=True` → `-p`, `include_untracked=True` → `-u` |
210+
| `apply()` | `git stash apply` | `index=True` → `--index`, `quiet=True` → `-q` |
211+
| `pop()` | `git stash pop` | `index=True` → `--index`, `quiet=True` → `-q` |
212+
| `drop()` | `git stash drop` | `quiet=True` → `-q` |
213+
| `branch(name)` | `git stash branch` | `name` → positional |
214+
146215
---
147216

148217
## 4. GitSubmoduleCmd (Current) → GitSubmoduleManager / GitSubmoduleCmd (Planned)
@@ -173,9 +242,18 @@ Parse from: `stash@{0}: On master: my message`
173242
| `sync(recursive)` | **Planned** | Sync submodule URLs |
174243
| `summary(commit, files, cached)` | **Planned** | Summarize changes |
175244

245+
#### CLI Flag → Python Parameter Mapping: GitSubmoduleManager Methods
246+
247+
| Method | Git CLI | Parameters → Flags |
248+
|--------|---------|-------------------|
249+
| `add()` | `git submodule add` | `branch` → `-b`, `force=True` → `-f`, `name` → `--name`, `depth` → `--depth` |
250+
| `foreach()` | `git submodule foreach` | `recursive=True` → `--recursive` |
251+
| `sync()` | `git submodule sync` | `recursive=True` → `--recursive` |
252+
| `summary()` | `git submodule summary` | `cached=True` → `--cached`, `files=True` → `--files`, `summary_limit` → `-n` |
253+
176254
### Planned GitSubmoduleCmd (Per-entity)
177255

178-
Properties: `name`, `path`, `url`, `branch`
256+
Properties: `name`, `path`, `url`, `branch`, `sha`
179257

180258
| Method | Status | Description |
181259
|--------|--------|-------------|
@@ -188,6 +266,18 @@ Properties: `name`, `path`, `url`, `branch`
188266
| `status()` | **Planned** | Show status |
189267
| `absorbgitdirs()` | **Planned** | Absorb gitdir |
190268

269+
#### CLI Flag → Python Parameter Mapping: GitSubmoduleCmd Methods
270+
271+
| Method | Git CLI | Parameters → Flags |
272+
|--------|---------|-------------------|
273+
| `init()` | `git submodule init` | None |
274+
| `update()` | `git submodule update` | `init=True` → `--init`, `force=True` → `-f`, `recursive=True` → `--recursive`, `checkout/rebase/merge` → mode flags |
275+
| `deinit()` | `git submodule deinit` | `force=True` → `-f`, `_all=True` → `--all` |
276+
| `set_branch(branch)` | `git submodule set-branch` | `branch` → `-b`, `default=True` → `-d` |
277+
| `set_url(url)` | `git submodule set-url` | `url` → positional |
278+
| `status()` | `git submodule status` | `recursive=True` → `--recursive` |
279+
| `absorbgitdirs()` | `git submodule absorbgitdirs` | None |
280+
191281
---
192282

193283
## 5. GitTagManager / GitTagCmd (New)
@@ -205,6 +295,29 @@ Properties: `name`, `path`, `url`, `branch`
205295
| `filter(**kwargs)` | **Planned** | Filter tags |
206296
| `create(name, ref, message, annotate, sign, force)` | **Planned** | Create tag |
207297

298+
#### CLI Flag → Python Parameter Mapping: `create()`
299+
300+
| Git CLI Flag | Python Parameter | Description |
301+
|--------------|------------------|-------------|
302+
| `-a, --annotate` | `annotate: bool` | Create annotated tag |
303+
| `-s, --sign` | `sign: bool` | Create GPG-signed tag |
304+
| `-u <key-id>` | `local_user: str \| None` | Use specific GPG key |
305+
| `-f, --force` | `force: bool` | Replace existing tag |
306+
| `-m <msg>` | `message: str \| None` | Tag message |
307+
| `-F <file>` | `file: str \| None` | Read message from file |
308+
309+
#### CLI Flag → Python Parameter Mapping: `ls()`
310+
311+
| Git CLI Flag | Python Parameter | Description |
312+
|--------------|------------------|-------------|
313+
| `-l <pattern>` | `pattern: str \| None` | List tags matching pattern |
314+
| `--sort=<key>` | `sort: str \| None` | Sort by key |
315+
| `--contains <commit>` | `contains: str \| None` | Tags containing commit |
316+
| `--no-contains <commit>` | `no_contains: str \| None` | Tags not containing commit |
317+
| `--merged <commit>` | `merged: str \| None` | Tags merged into commit |
318+
| `--no-merged <commit>` | `no_merged: str \| None` | Tags not merged |
319+
| `-n<num>` | `lines: int \| None` | Print annotation lines |
320+
208321
### Planned GitTagCmd (Per-entity)
209322

210323
Properties: `tag_name`, `ref`, `message` (for annotated)
@@ -216,6 +329,14 @@ Properties: `tag_name`, `ref`, `message` (for annotated)
216329
| `delete()` | **Planned** | Delete tag (`-d`) |
217330
| `verify()` | **Planned** | Verify signed tag (`-v`) |
218331

332+
#### CLI Flag → Python Parameter Mapping: GitTagCmd Methods
333+
334+
| Method | Git CLI | Parameters → Flags |
335+
|--------|---------|-------------------|
336+
| `delete()` | `git tag -d` | None |
337+
| `verify()` | `git tag -v` | None |
338+
| `show()` | `git show` | (uses git show, not git tag) |
339+
219340
---
220341

221342
## 6. GitWorktreeManager / GitWorktreeCmd (New)
@@ -234,6 +355,35 @@ Properties: `tag_name`, `ref`, `message` (for annotated)
234355
| `add(path, branch, detach, checkout, lock, force)` | **Planned** | Add worktree |
235356
| `prune(dry_run, verbose, expire)` | **Planned** | Prune worktrees |
236357

358+
#### CLI Flag → Python Parameter Mapping: `add()`
359+
360+
| Git CLI Flag | Python Parameter | Description |
361+
|--------------|------------------|-------------|
362+
| `-f, --force` | `force: bool` | Force creation |
363+
| `--detach` | `detach: bool` | Detach HEAD |
364+
| `--checkout` | `checkout: bool` | Checkout after add |
365+
| `--lock` | `lock: bool` | Lock worktree |
366+
| `--reason <string>` | `reason: str \| None` | Lock reason |
367+
| `-b <branch>` | `new_branch: str \| None` | Create new branch |
368+
| `-B <branch>` | `new_branch_force: str \| None` | Force create branch |
369+
| `--orphan` | `orphan: bool` | Create orphan branch |
370+
| `--track` | `track: bool` | Track remote |
371+
372+
#### CLI Flag → Python Parameter Mapping: `prune()`
373+
374+
| Git CLI Flag | Python Parameter | Description |
375+
|--------------|------------------|-------------|
376+
| `-n, --dry-run` | `dry_run: bool` | Dry run |
377+
| `-v, --verbose` | `verbose: bool` | Verbose output |
378+
| `--expire <time>` | `expire: str \| None` | Expire time |
379+
380+
#### CLI Flag → Python Parameter Mapping: `ls()`
381+
382+
| Git CLI Flag | Python Parameter | Description |
383+
|--------------|------------------|-------------|
384+
| `-v` | `verbose: bool` | Verbose output |
385+
| `--porcelain` | `porcelain: bool` | Machine-readable |
386+
237387
### Planned GitWorktreeCmd (Per-entity)
238388

239389
Properties: `worktree_path`, `branch`, `head`, `locked`, `prunable`
@@ -247,6 +397,16 @@ Properties: `worktree_path`, `branch`, `head`, `locked`, `prunable`
247397
| `move(new_path)` | **Planned** | Move worktree |
248398
| `repair()` | **Planned** | Repair worktree |
249399

400+
#### CLI Flag → Python Parameter Mapping: GitWorktreeCmd Methods
401+
402+
| Method | Git CLI | Parameters → Flags |
403+
|--------|---------|-------------------|
404+
| `remove()` | `git worktree remove` | `force=True` → `-f` |
405+
| `lock()` | `git worktree lock` | `reason` → `--reason` |
406+
| `unlock()` | `git worktree unlock` | None |
407+
| `move(new_path)` | `git worktree move` | `force=True` → `-f` |
408+
| `repair()` | `git worktree repair` | None |
409+
250410
---
251411

252412
## 7. GitNotesManager / GitNoteCmd (New)
@@ -267,6 +427,34 @@ Properties: `worktree_path`, `branch`, `head`, `locked`, `prunable`
267427
| `merge(notes_ref, strategy, commit, abort, quiet)` | **Planned** | Merge notes |
268428
| `get_ref()` | **Planned** | Get notes ref |
269429

430+
#### CLI Flag → Python Parameter Mapping: `add()`
431+
432+
| Git CLI Flag | Python Parameter | Description |
433+
|--------------|------------------|-------------|
434+
| `-f, --force` | `force: bool` | Overwrite existing note |
435+
| `--allow-empty` | `allow_empty: bool` | Allow empty note |
436+
| `-m <msg>` | `message: str \| None` | Note message |
437+
| `-F <file>` | `file: str \| None` | Read message from file |
438+
| `-c <object>` | `reuse_message: str \| None` | Reuse message from note |
439+
| `-C <object>` | `reedit_message: str \| None` | Re-edit message |
440+
441+
#### CLI Flag → Python Parameter Mapping: `prune()`
442+
443+
| Git CLI Flag | Python Parameter | Description |
444+
|--------------|------------------|-------------|
445+
| `-n, --dry-run` | `dry_run: bool` | Dry run |
446+
| `-v, --verbose` | `verbose: bool` | Verbose output |
447+
448+
#### CLI Flag → Python Parameter Mapping: `merge()`
449+
450+
| Git CLI Flag | Python Parameter | Description |
451+
|--------------|------------------|-------------|
452+
| `-s <strategy>` | `strategy: str \| None` | Merge strategy |
453+
| `--commit` | `commit: bool` | Finalize merge |
454+
| `--abort` | `abort: bool` | Abort merge |
455+
| `-q, --quiet` | `quiet: bool` | Quiet mode |
456+
| `-v, --verbose` | `verbose: bool` | Verbose mode |
457+
270458
### Planned GitNoteCmd (Per-entity)
271459

272460
Properties: `object`, `note_ref`
@@ -280,6 +468,16 @@ Properties: `object`, `note_ref`
280468
| `copy(from_object)` | **Planned** | Copy note |
281469
| `remove()` | **Planned** | Remove note |
282470

471+
#### CLI Flag → Python Parameter Mapping: GitNoteCmd Methods
472+
473+
| Method | Git CLI | Parameters → Flags |
474+
|--------|---------|-------------------|
475+
| `show()` | `git notes show` | None |
476+
| `edit()` | `git notes edit` | `allow_empty=True` → `--allow-empty` |
477+
| `append(message)` | `git notes append` | `-m` → message, `-F` → file |
478+
| `copy(from_object)` | `git notes copy` | `force=True` → `-f` |
479+
| `remove()` | `git notes remove` | `ignore_missing=True` → `--ignore-missing` |
480+
283481
---
284482

285483
## 8. GitReflogManager / GitReflogCmd (New)
@@ -298,18 +496,59 @@ Properties: `object`, `note_ref`
298496
| `expire(ref, _all, dry_run, rewrite, updateref, stale_fix, verbose)` | **Planned** | Expire entries |
299497
| `exists(ref)` | **Planned** | Check if reflog exists |
300498

499+
#### CLI Flag → Python Parameter Mapping: `ls()` / `show()`
500+
501+
| Git CLI Flag | Python Parameter | Description |
502+
|--------------|------------------|-------------|
503+
| `<ref>` | `ref: str` | Reference (default: HEAD) |
504+
| `-n <number>` | `number: int \| None` | Limit entries |
505+
| `--date=<format>` | `date: str \| None` | Date format |
506+
507+
#### CLI Flag → Python Parameter Mapping: `expire()`
508+
509+
| Git CLI Flag | Python Parameter | Description |
510+
|--------------|------------------|-------------|
511+
| `--all` | `_all: bool` | Process all refs |
512+
| `-n, --dry-run` | `dry_run: bool` | Dry run |
513+
| `--rewrite` | `rewrite: bool` | Rewrite entries |
514+
| `--updateref` | `updateref: bool` | Update ref |
515+
| `--stale-fix` | `stale_fix: bool` | Fix stale entries |
516+
| `-v, --verbose` | `verbose: bool` | Verbose output |
517+
| `--expire=<time>` | `expire: str \| None` | Expire unreachable older than |
518+
| `--expire-unreachable=<time>` | `expire_unreachable: str \| None` | Expire unreachable |
519+
520+
#### CLI Flag → Python Parameter Mapping: `delete()`
521+
522+
| Git CLI Flag | Python Parameter | Description |
523+
|--------------|------------------|-------------|
524+
| `--rewrite` | `rewrite: bool` | Rewrite entries |
525+
| `--updateref` | `updateref: bool` | Update ref |
526+
| `-n, --dry-run` | `dry_run: bool` | Dry run |
527+
301528
### Planned GitReflogCmd (Per-entity)
302529

303530
Properties: `ref`, `index`, `action`, `message`, `sha`
304531

305532
Parse from: `abc1234 HEAD@{0}: commit: message`
306533

534+
**Parsing pattern**:
535+
```python
536+
reflog_pattern = r"(?P<sha>[a-f0-9]+) (?P<ref>[^@]+)@\{(?P<index>\d+)\}: (?P<action>[^:]+): (?P<message>.+)"
537+
```
538+
307539
| Method | Status | Description |
308540
|--------|--------|-------------|
309541
| `__init__(path, ref, index, action, message, sha, cmd)` | **Planned** | Constructor |
310542
| `show()` | **Planned** | Show entry details |
311543
| `delete()` | **Planned** | Delete entry |
312544

545+
#### CLI Flag → Python Parameter Mapping: GitReflogCmd Methods
546+
547+
| Method | Git CLI | Parameters → Flags |
548+
|--------|---------|-------------------|
549+
| `show()` | `git reflog show` | (show this entry) |
550+
| `delete()` | `git reflog delete` | `rewrite=True` → `--rewrite`, `updateref=True` → `--updateref` |
551+
313552
---
314553

315554
## Git Class Exposure

0 commit comments

Comments
 (0)