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(*, path, cmd=None)

Bases: object

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

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

Parameters:

• path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

• cmd (Git | 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' 

branch_name: str

__init__(*, path, cmd=None)

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

Parameters:

• path (str | PathLike[str]) – 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

Directory to check out

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.

Return type:

str

Parameters:

• local_flags (list[str] | None)

• quiet (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Examples

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

checkout(*, branch)

Git branch checkout.

Return type:

str

Parameters:

branch (str)

Examples

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

create(*, branch, checkout=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).

Return type:

str

Examples

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

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

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)

Get branch via filter lookup.

Return type:

GitBranchCmd | None

Parameters:

• args (Any)

• kwargs (Any)

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 

filter(*args, **kwargs)

Get branches via filter lookup.

Return type:

list[GitBranchCmd]

Parameters:

• args (Any)

• kwargs (Any)

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') [] 

class libvcs.cmd.git.GitBranchCmd(*, path, branch_name, cmd=None)

Bases: object

Run git commands targeting a specific branch.

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

Parameters:

• path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

• branch_name (str) – Name of branch.

• cmd (Git | 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' 

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

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

Parameters:

• path (str | PathLike[str]) – 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

Directory to check out

branch_name: str

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.

Return type:

str

Parameters:

• local_flags (list[str] | None)

• quiet (bool | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Examples

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

checkout()

Git branch checkout.

Return type:

str

Examples

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

create(*, checkout=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).

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)

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)

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)

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)

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)

Remove the upstream (tracking) information.

Return type:

str

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Examples

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

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

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'."