branch

For git-branch(1).

Overview

Manage git branches using GitBranchManager (collection-level) and GitBranchCmd (per-branch operations).

Example

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

class libvcs.cmd.git.GitBranchManager

class

Bases: object

Traverse and manage git branches with ORM-like filtering via QueryList.

branch_name: str

attribute

__init__(*, path, cmd=None)

method

Wrap some of git-branch(1), git-checkout(1), manager.

Parameters:

• path (StrPath) – Operates as PATH in the corresponding git subcommand.

• cmd (Git | None)

Return type:

None

Examples

>>> GitBranchManager(path=tmp_path)
<GitBranchManager path=...>

>>> GitBranchManager(path=tmp_path).run(quiet=True)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitBranchManager(
...     path=example_git_repo.path).run(quiet=True)
'* master'

path: Path

attribute

Directory to check out

run(local_flags=None, *, quiet=None, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run a command against a git repository’s branches.

Wraps git branch.

Examples

>>> GitBranchManager(path=example_git_repo.path).run()
'* master'

Parameters:

• local_flags (list[str] | None)

• quiet (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str

checkout(*, branch)

method

Git branch checkout.

Examples

>>> GitBranchManager(path=example_git_repo.path).checkout(branch='master')
"Your branch is up to date with 'origin/master'."

Parameters:

branch (str)

Return type:

str

create(*, branch, checkout=False)

method

Create a git branch.

Parameters:

• branch (str) – Name of the branch to create.

• checkout (bool) – If True, also checkout the newly created branch. Defaults to False (create only, don’t switch HEAD).

Return type:

str

Examples

>>> GitBranchManager(path=example_git_repo.path).create(branch='master')
"fatal: a branch named 'master' already exists"

_ls(*, local_flags=None)

method

List branches (raw output).

Parameters:

local_flags (list[str] | None) – Additional flags to pass to git branch.

Return type:

list[str]

Examples

>>> branches = GitBranchManager(path=example_git_repo.path)._ls()
>>> '* master' in branches or 'master' in str(branches)
True

ls(*, _all=False, remotes=False, merged=None, no_merged=None, contains=None, sort=None, verbose=False)

method

List branches.

Parameters:

• _all (bool) – List all branches (local + remote). Maps to –all.

• remotes (bool) – List remote branches only. Maps to –remotes.

• merged (str | None) – Only list branches merged into specified commit.

• no_merged (str | None) – Only list branches NOT merged into specified commit.

• contains (str | None) – Only list branches containing specified commit.

• sort (str | None) – Sort key (e.g., ‘-committerdate’, ‘refname’).

• verbose (bool) – Show sha1 and commit subject line for each head. Maps to –verbose.

Return type:

QueryList[GitBranchCmd]

Examples

>>> branches = GitBranchManager(path=example_git_repo.path).ls()
>>> any(b.branch_name == 'master' for b in branches)
True

get(*args, **kwargs)

method

Get branch via filter lookup.

Examples

>>> GitBranchManager(
...     path=example_git_repo.path
... ).get(branch_name='master')
<GitBranchCmd path=... branch_name=master>

>>> GitBranchManager(
...     path=example_git_repo.path
... ).get(branch_name='unknown')
Traceback (most recent call last):
    exec(compile(example.source, filename, "single",
    ...
    return self.ls().get(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "..._internal/query_list.py", line ..., in get
    raise ObjectDoesNotExist
libvcs._internal.query_list.ObjectDoesNotExist

Parameters:

• args (Any)

• kwargs (Any)

Return type:

GitBranchCmd | None

filter(*args, **kwargs)

method

Get branches via filter lookup.

Examples

>>> GitBranchManager(
...     path=example_git_repo.path
... ).filter(branch_name__contains='master')
[<GitBranchCmd path=... branch_name=master>]

>>> GitBranchManager(
...     path=example_git_repo.path
... ).filter(branch_name__contains='unknown')
[]

Parameters:

• args (Any)

• kwargs (Any)

Return type:

list[GitBranchCmd]

class libvcs.cmd.git.GitBranchCmd

class

Bases: object

Run git commands targeting a specific branch.

__init__(*, path, branch_name, cmd=None)

method

Lite, typed, pythonic wrapper for git-branch(1).

Parameters:

• path (StrPath) – Operates as PATH in the corresponding git subcommand.

• branch_name (str) – Name of branch.

• cmd (Git | None)

Return type:

None

Examples

>>> GitBranchCmd(
...     path=tmp_path,
...     branch_name='master'
... )
<GitBranchCmd path=... branch_name=master>

>>> GitBranchCmd(
...     path=tmp_path,
...     branch_name='master'
... ).run(quiet=True)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).run(quiet=True)
'* master'

path: Path

attribute

Directory to check out

branch_name: str

attribute

run(local_flags=None, *, quiet=None, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run a command against a git repository’s branch.

Wraps git branch.

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).run()
'* master'

Parameters:

• local_flags (list[str] | None)

• quiet (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str

checkout()

method

Git branch checkout.

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).checkout()
"Your branch is up to date with 'origin/master'."

Return type:

str

create(*, checkout=False)

method

Create a git branch.

Parameters:

checkout (bool) – If True, also checkout the newly created branch. Defaults to False (create only, don’t switch HEAD).

Return type:

str

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).create()
"fatal: a branch named 'master' already exists"

delete(*, force=False, log_in_real_time=False, check_returncode=None)

method

Delete this git branch.

Parameters:

• force (bool) – Use -D instead of -d to force deletion.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='nonexistent'
... ).delete()
"error: branch 'nonexistent' not found"

rename(new_name, *, force=False, log_in_real_time=False, check_returncode=None)

method

Rename this git branch.

Parameters:

• new_name (str) – New name for the branch.

• force (bool) – Use -M instead of -m to force rename.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).rename('main')
''

copy(new_name, *, force=False, log_in_real_time=False, check_returncode=None)

method

Copy this git branch.

Parameters:

• new_name (str) – Name for the copied branch.

• force (bool) – Use -C instead of -c to force copy.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).copy('master-copy')
''

set_upstream(upstream, *, log_in_real_time=False, check_returncode=None)

method

Set the upstream (tracking) branch.

Parameters:

• upstream (str) – The upstream branch in format remote/branch (e.g., origin/main).

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).set_upstream('origin/master')
"branch 'master' set up to track 'origin/master'."

unset_upstream(*, log_in_real_time=False, check_returncode=None)

method

Remove the upstream (tracking) information.

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).unset_upstream()
''

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

track(remote_branch, *, log_in_real_time=False, check_returncode=None)

method

Create branch tracking a remote branch.

Wraps git branch -t.

Parameters:

• remote_branch (str) – Remote branch to track (e.g., ‘origin/main’).

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

For existing branches, use set_upstream() instead. track() is for creating new branches that track a remote:

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='tracking-branch'
... ).track('origin/master')
"branch 'tracking-branch' set up to track 'origin/master'."