branch

For git-branch(1).

Overview

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

Examples

List branches — local by default, remote with remotes=True:

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

Create a branch, then look it up:

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

Rename or delete a branch through its Cmd object:

>>> 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-feature')
''
>>> renamed = git.branches.get(branch_name='new-feature')
>>> renamed.delete()
'Deleted branch new-feature ...'

API Reference

class libvcs.cmd.git.GitBranchManager

class

class

class libvcs.cmd.git.GitBranchManager

Bases: object

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

branch_name: str

attribute

attribute

branch_name: str

__init__(*, path, cmd=None)

method

method

__init__(*, path, cmd=None)

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, trim=True)
'fatal: not a git repository (or any of the parent directories): .git'

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

path: Path

attribute

attribute

path: Path

Directory to check out

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

method

method

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

Run a command against a git repository’s branches.

Wraps git branch.

Examples

>>> GitBranchManager(path=example_git_repo.path).run(trim=True)
'* 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, trim=False)

method

method

checkout(*, branch, trim=False)

Git branch checkout.

Examples

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

Parameters:

• branch (str)

• trim (bool)

Return type:

str

create(*, branch, checkout=False, trim=False)

method

method

create(*, branch, checkout=False, trim=False)

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).

• trim (bool, default: False) – Strip trailing whitespace/newline from command output.

Return type:

str

Examples

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

_ls(*, local_flags=None)

method

method

_ls(*, local_flags=None)

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

method

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

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

method

get(*args, **kwargs)

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

method

filter(*args, **kwargs)

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

class

class libvcs.cmd.git.GitBranchCmd

Bases: object

Run git commands targeting a specific branch.

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

method

method

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

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, trim=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, trim=True)
'* master'

path: Path

attribute

attribute

path: Path

Directory to check out

branch_name: str

attribute

attribute

branch_name: str

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

method

method

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

Run a command against a git repository’s branch.

Wraps git branch.

Examples

>>> GitBranchCmd(
...     path=example_git_repo.path,
...     branch_name='master'
... ).run(trim=True)
'* 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(trim=False)

method

method

checkout(trim=False)

Git branch checkout.

Examples

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

Parameters:

trim (bool)

Return type:

str

create(*, checkout=False, trim=False)

method

method

create(*, checkout=False, trim=False)

Create a git branch.

Parameters:

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

• trim (bool, default: False) – Strip trailing whitespace/newline from command output.

Return type:

str

Examples

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

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

method

method

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

Delete this git branch.

Parameters:

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

• trim (bool, default: False) – Strip trailing whitespace/newline from command output.

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

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

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

method

method

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

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

method

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

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, trim=False)

method

method

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

Set the upstream (tracking) branch.

Parameters:

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

• trim (bool, default: False) – Strip trailing whitespace/newline from command output.

• 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', trim=True)
"branch 'master' set up to track 'origin/master'."

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

method

method

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

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, trim=False)

method

method

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

Create branch tracking a remote branch.

Wraps git branch -t.

Parameters:

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

• trim (bool, default: False) – Strip trailing whitespace/newline from command output.

• 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', trim=True)
"branch 'tracking-branch' set up to track 'origin/master'."