Traversing Git Repos¶

libvcs provides Managers and Commands for intuitively traversing and navigating entities in a git repository—branches, tags, remotes, stashes, and more—with ORM-like convenience via QueryList.

Overview¶

The pattern consists of two types of classes:

Managers (git.branches, git.tags, etc.) let you traverse repository entities intuitively, listing, filtering, and retrieving them with ORM-like convenience
Commands are contextual ways to run git commands against a specific target entity (e.g., delete a branch, rename a tag, set a remote’s URL)

Git instance
├── branches: GitBranchManager
│   ├── ls() -> QueryList[GitBranchCmd]
│   ├── get() -> GitBranchCmd
│   └── create()
├── tags: GitTagManager
├── remotes: GitRemoteManager
├── stashes: GitStashManager
├── worktrees: GitWorktreeManager
├── notes: GitNotesManager
├── submodules: GitSubmoduleManager
└── reflog: GitReflogManager

Basic Usage¶

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)

Listing Items¶

All Manager classes have an ls() method that returns a QueryList:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> branches = git.branches.ls()
>>> isinstance(branches, list)
True
>>> tags = git.tags.ls()
>>> remotes = git.remotes.ls()

Getting a Single Item¶

Use get() with filter criteria to retrieve a single item:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.tags.create(name='v1.0.0', message='Release 1.0')
''
>>> tag = git.tags.get(tag_name='v1.0.0')
>>> tag.tag_name
'v1.0.0'

Creating Items¶

Manager classes provide create() or add() methods:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.tags.create(name='v2.0.0', message='Release 2.0')
''
>>> git.branches.create(branch='feature-branch')
''

Per-Entity Operations¶

Cmd objects have methods for mutating or inspecting that entity:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.tags.create(name='v3.0.0', message='Release 3.0')
''
>>> tag = git.tags.get(tag_name='v3.0.0')
>>> tag.delete()
"Deleted tag 'v3.0.0' ..."
>>> git.branches.create(branch='temp-branch')
''
>>> branch = git.branches.get(branch_name='temp-branch')
>>> branch.delete()
'Deleted branch temp-branch ...'

Comparison to Raw Commands¶

Before: Parsing Strings¶

Without Managers and Commands, you’d parse raw output:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> # Raw output requires parsing
>>> raw_output = git.run(['tag', '-l'])
>>> tag_names = [t for t in raw_output.strip().split('\\n') if t]

After: Typed Objects¶

With Managers and Commands, you get typed objects:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> tags = git.tags.ls()
>>> for tag in tags:
...     print(f"{tag.tag_name}")

Working with Remotes¶

Add and configure remote repositories:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.remotes.add(name='upstream', url='https://github.com/vcs-python/libvcs.git')
''
>>> remotes = git.remotes.ls()
>>> len(remotes) >= 1
True

Get a remote and update its URL:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.remotes.add(name='backup', url='https://example.com/old.git')
''
>>> remote = git.remotes.get(remote_name='backup')
>>> remote.remote_name
'backup'
>>> remote.set_url(url='https://example.com/new.git')
''

Branch Operations¶

Beyond creating and deleting, branches support rename and upstream tracking:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.branches.create(branch='old-name')
''
>>> branch = git.branches.get(branch_name='old-name')
>>> branch.rename('new-name')
''

Copy a branch:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.branches.create(branch='source-branch')
''
>>> branch = git.branches.get(branch_name='source-branch')
>>> branch.copy('copied-branch')
''

Stash Workflow¶

Save work in progress and restore it later:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> # Push returns message (or "No local changes to save")
>>> git.stashes.push(message='WIP: feature work')
'...'

List and inspect stashes:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> stashes = git.stashes.ls()
>>> isinstance(stashes, list)
True

Worktree Management¶

Create additional working directories for parallel development:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> worktrees = git.worktrees.ls()
>>> len(worktrees) >= 1  # Main worktree always exists
True

Notes¶

Attach metadata to commits:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.notes.add(message='Reviewed by Alice')
''

Filtering with ls() Parameters¶

Manager ls() methods accept parameters to narrow results:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> # All local branches
>>> local = git.branches.ls()
>>> isinstance(local, list)
True
>>> # Branches merged into HEAD
>>> merged = git.branches.ls(merged='HEAD')
>>> isinstance(merged, list)
True

Error Handling¶

When get() finds no match, it raises ObjectDoesNotExist:

>>> from libvcs.cmd.git import Git
>>> from libvcs._internal.query_list import ObjectDoesNotExist
>>> git = Git(path=example_git_repo.path)
>>> try:
...     git.branches.get(branch_name='nonexistent-branch-xyz')
... except ObjectDoesNotExist:
...     print('Branch not found')
Branch not found

When to Use¶

Use Case	Approach
List/filter/get entities	Manager class (`git.branches.ls()`)
Mutate a specific entity	Cmd class (`branch.delete()`)
Run arbitrary git commands	Direct methods (`git.run([...])`)
Complex pipelines	Mix of both

Available Managers¶

Manager	Access	Operations
`GitBranchManager`	`git.branches`	List, create, checkout branches
`GitTagManager`	`git.tags`	List, create tags
`GitRemoteManager`	`git.remotes`	List, add, configure remotes
`GitStashManager`	`git.stashes`	List, push, clear stashes
`GitWorktreeManager`	`git.worktrees`	List, add, prune worktrees
`GitNotesManager`	`git.notes`	List, add, prune notes
`GitSubmoduleManager`	`git.submodules`	List, add, sync submodules
`GitReflogManager`	`git.reflog`	List, expire reflog entries

See libvcs.cmd.git for the complete API reference.