Module: Git::Repository::Branching Private

Included in:
Git::Repository
Defined in:
lib/git/repository/branching.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Facade methods for branching operations: creating, checking out, querying, deleting, and updating branches

Included by Git::Repository.

API:

  • private

Defined Under Namespace

Classes: HeadState

Instance Method Summary collapse

Instance Method Details

#branch(branch_name = current_branch) ⇒ Git::Branch

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use branch_list(name).first and the name-based branch operations instead

#branch_list returns immutable BranchInfo value objects rather than Branch. It takes git branch --list patterns, so pass the short name of a local branch or "#{remote}/#{name}" for a remote-tracking branch; the remotes/ and refs/ prefixes this method accepts match nothing. A "#{remote}/#{name}" pattern also matches a local branch of that name, so take find(&:remote?) rather than first for a remote-tracking branch. With no argument this method wraps #current_branch, which is 'HEAD' when HEAD is detached; #branch_list has no entry for a detached or unborn HEAD, so use #current_branch_state in those states. Call the corresponding Git::Repository method (e.g. #checkout, #branch_new, #branch_delete) for operations on a branch.

Returns a Branch object for the given branch name

Examples:

Get a branch object for 'main'

repo.branch('main')  #=> #<Git::Branch 'main'>

Get a branch object for the current branch

repo.branch  #=> #<Git::Branch 'main'>

Parameters:

  • (defaults to: current_branch)

    the branch name (defaults to the current branch)

Returns:

  • the branch object

Raises:

  • if git exits with a non-zero exit status

See Also:

API:

  • private



718
719
720
721
722
723
724
725
726
 
# File 'lib/git/repository/branching.rb', line 718

def branch(branch_name = current_branch)
  Git::Deprecation.warn(
    'Git::Repository#branch is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#branch_list(name).first for a local branch, ' \
    'Git::Repository#branch_list("remote/name").find(&:remote?) for a remote-tracking branch, ' \
    'and the name-based branch operations instead.'
  )
  Git::Branch.new(self, branch_name)
end

#branch?(branch) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true if the named branch exists locally or as a remote-tracking branch

Examples:

Check whether main exists anywhere

repo.branch?('main')  # => true

Parameters:

  • the branch name to look up

Returns:

  • true if the branch exists locally or remotely, false otherwise

Raises:

  • if git exits with a non-zero exit status

API:

  • private



343
344
345
 
# File 'lib/git/repository/branching.rb', line 343

def branch?(branch)
  local_branch?(branch) || remote_branch?(branch)
end

#branch_contains(commit, branch_name = '') ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the git branch --list --contains stdout for a given commit

The output format is the human-readable git branch listing: each matching branch name appears on its own line, prefixed with two spaces, or * if it is the currently checked-out branch. This is the same format returned by Git::Lib#branch_contains in the 4.x gem series.

Examples:

List all branches that contain a commit

repo.branch_contains('abc1234')
# => "  main\n"

The current branch is marked with an asterisk

repo.branch_contains('abc1234')
# => "* main\n  feature\n"

Limit the search to branches matching a shell wildcard pattern

repo.branch_contains('abc1234', 'feature/*')

Typical usage: check whether any branch contains the commit

repo.branch_contains('abc1234').empty?  # => false

Parameters:

  • the commit SHA or ref to look up

  • (defaults to: '')

    a shell wildcard pattern to limit which branches are searched

    When empty or nil, all local branches are searched.

Returns:

  • the git branch --list --contains stdout

    Each matching branch appears on its own line, prefixed with two spaces, or * for the currently checked-out branch. Returns an empty string when no matching branch contains the commit.

Raises:

  • if git exits with a non-zero exit status

API:

  • private



573
574
575
576
577
578
579
 
# File 'lib/git/repository/branching.rb', line 573

def branch_contains(commit, branch_name = '')
  branch_name = branch_name.to_s
  pattern = branch_name.empty? ? nil : branch_name
  Git::Commands::Branch::List.new(@execution_context)
                             .call(*[pattern].compact, contains: commit, no_color: true)
                             .stdout
end

#branch_delete(*branches, **options) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Delete one or more local or remote-tracking branches

Examples:

Delete a single branch

repo.branch_delete('feature') # => "Deleted branch feature (was abc1234)."

Delete multiple branches at once

repo.branch_delete('feature-1', 'feature-2')

Force-delete an unmerged branch

repo.branch_delete('unmerged-branch', force: true)

Delete a remote-tracking branch

repo.branch_delete('origin/feature', remotes: true)

Parameters:

  • the name(s) of the branch(es) to delete

  • options for the delete command

Options Hash (**options):

  • :force (Boolean, nil) — default: true —

    allow deleting the branch irrespective of its merged status

    Defaults to true to match the 4.x behavior.

  • :remotes (Boolean, nil) — default: nil —

    delete remote-tracking branches

    Use together with a remote/branch name.

Returns:

  • the stdout output from the delete command, e.g. "Deleted branch feature (was abc1234)."

Raises:

  • if unsupported options are provided

  • if git exits outside the allowed range (exit code > 1)

  • if git reports a deletion failure

API:

  • private



493
494
495
496
497
498
499
500
501
502
 
# File 'lib/git/repository/branching.rb', line 493

def branch_delete(*branches, **options)
  options = { force: true }.merge(options)
  SharedPrivate.assert_valid_opts!(BRANCH_DELETE_ALLOWED_OPTS, **options)

  result = Git::Commands::Branch::Delete.new(@execution_context).call(*branches, **options)

  raise Git::Error, result.stderr.strip unless result.status.success?

  result.stdout.strip
end

#branch_list(*patterns, remote_names: nil) ⇒ Array<Git::BranchInfo>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns all local and remote-tracking branches as structured objects

Examples:

List all branches

repo.branch_list
# => [#<data Git::BranchInfo refname="refs/heads/main", current=true, ...>,
#     #<data Git::BranchInfo refname="refs/remotes/origin/main", current=false, ...>]

Find the currently checked-out branch

repo.branch_list.find(&:current)

List only local branches

repo.branch_list.reject(&:remote?)

Filter to an exact branch name

repo.branch_list('feature/auth')

Filter using glob patterns

repo.branch_list('feature/*', 'hotfix/*')

Parameters:

  • optional shell wildcard patterns passed directly to git branch --list; when empty (the default) all branches are returned. Pattern matching follows git's own rules; behavior may differ between local and remote-tracking branches.

  • (defaults to: nil)

    configured remote names used to resolve remote-tracking refs

    Especially useful for remotes whose remote names contain slashes. When omitted, the repository's configured remote names are fetched automatically.

Returns:

  • parsed branch information for every local and remote-tracking branch matching the pattern

    Returns an empty array when the repository has no branches or no branches match the given pattern.

Raises:

  • if git exits with a non-zero exit status

API:

  • private



619
620
621
622
623
624
625
 
# File 'lib/git/repository/branching.rb', line 619

def branch_list(*patterns, remote_names: nil)
  remote_names ||= self.remote_names
  result = Git::Commands::Branch::List.new(@execution_context).call(
    *patterns, all: true, format: Git::Parsers::Branch::FORMAT_STRING
  )
  Git::Parsers::Branch.parse_list(result.stdout, remote_names:)
end

#branch_new(branch, start_point = nil, branch_options = {})

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Create a new branch

Examples:

Create a new branch from the current HEAD

repo.branch_new('feature')

Create a new branch from a specific commit or branch

repo.branch_new('feature', 'main')

Parameters:

  • the name of the branch to create

  • (defaults to: nil)

    the commit, branch, or tag to start the new branch from; defaults to the current HEAD when nil

  • (defaults to: {})

    reserved; must be empty — no options are currently supported

Raises:

  • if unsupported options are provided

  • if git exits with a non-zero exit status

API:

  • private



439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/git/repository/branching.rb', line 439

def branch_new(branch, start_point = nil, branch_options = {})
  if start_point.is_a?(Hash) && branch_options.empty?
    branch_options = start_point
    start_point = nil
  end

  SharedPrivate.assert_valid_opts!(BRANCH_NEW_ALLOWED_OPTS, **branch_options)
  Git::Commands::Branch::Create.new(@execution_context).call(branch, start_point, **branch_options)

  nil
end

#branches ⇒ Git::Branches

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use #branch_list instead

#branch_list returns Array<Git::BranchInfo> (immutable value objects) rather than a Branches collection. Filter it with select(&:remote?) or reject(&:remote?) in place of branches.remote and branches.local, and look a branch up by name with branch_list(name).first in place of branches[name].

Returns a Branches collection of all branches in the repository

Examples:

List all branches

repo.branches
# => #<Git::Branches ...>

Iterate over all branches

repo.branches.each { |b| puts b.name }

Access local branches only

repo.branches.local

Access remote-tracking branches only

repo.branches.remote

Look up a branch by name

repo.branches['main']  # => #<Git::Branch 'main'>

Returns:

  • a collection wrapping all local and remote-tracking branches in the repository

Raises:

  • if git exits with a non-zero exit status

See Also:

API:

  • private



761
762
763
764
765
766
767
 
# File 'lib/git/repository/branching.rb', line 761

def branches
  Git::Deprecation.warn(
    'Git::Repository#branches is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#branch_list instead.'
  )
  Git::Branches.new(self)
end

#branches_all ⇒ Array<Array>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use #branch_list instead, which returns richer BranchInfo objects.

Returns all local and remote-tracking branches in the 4.x-compatible format

Each entry is a 4-element array: [refname, current, worktree, symref]. The refname uses the short form (main, remotes/origin/main) to match the output of the legacy Git::Lib#branches_all method.

Returns:

  • array of [refname, current, worktree, symref] tuples

Raises:

  • if git exits with a non-zero exit status

API:

  • private



640
641
642
643
644
645
646
647
648
649
 
# File 'lib/git/repository/branching.rb', line 640

def branches_all
  Git::Deprecation.warn(
    'Git::Repository#branches_all is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#branch_list instead.'
  )
  branch_list.map do |info|
    refname = info.remote? ? "remotes/#{info.remote_name}/#{info.short_name}" : info.short_name
    [refname, info.current, info.other_worktree?, info.symref]
  end
end

#change_head_branch(branch_name)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

Pointing HEAD at a branch that does not yet exist places the repository in unborn-branch state. This is intentional for repository initialization workflows — for example, setting a custom default branch name before any commits land — but is unexpected if done by mistake. The repository will appear to have no commits until the first commit is made on the new branch.

This method returns an undefined value.

Writes the HEAD symbolic ref to point at the given branch

Sets HEAD to refs/heads/<branch_name> via git symbolic-ref. This is equivalent to running git symbolic-ref HEAD refs/heads/<branch_name> on the command line and is the mechanism git uses internally for branch renaming and orphan-branch checkout.

Examples:

Change HEAD to point to an existing branch

repo.change_head_branch('main')

Initialize a repository with a custom default branch name (unborn-branch pattern)

repo = Git.init('/path/to/repo')
repo.change_head_branch('my-branch')
# HEAD now points at refs/heads/my-branch before any commits exist

Parameters:

  • the branch name to point HEAD at

Raises:

  • if git exits with a non-zero exit status

API:

  • private



532
533
534
535
 
# File 'lib/git/repository/branching.rb', line 532

def change_head_branch(branch_name)
  Git::Commands::SymbolicRef::Update.new(@execution_context).call('HEAD', "refs/heads/#{branch_name}")
  nil
end

#checkout(branch = nil, opts = {}) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Switch branches or restore working tree files

Examples:

Check out an existing branch

repo.checkout('main')

Create and check out a new branch from main

repo.checkout('new-feature', new_branch: true, start_point: 'main')

Create a new branch with a name different from the start point

repo.checkout('main', new_branch: 'new-feature')

Create and check out an unborn branch with no history

repo.checkout('gh-pages', orphan: true)

Force checkout discarding local changes

repo.checkout('main', force: true)

Parameters:

  • (defaults to: nil)

    the branch to check out; defaults to nil (i.e. restore HEAD state)

  • (defaults to: {})

    options for the checkout command

Options Hash (opts):

  • :force (Boolean, nil) — default: nil —

    discard local changes when switching branches

  • :new_branch (Boolean, String, nil) — default: nil —

    when true, creates a new branch named branch from :start_point

    When a String, creates a new branch with that name, using branch as the start point.

  • :b (Boolean, String, nil) — default: nil —

    alias for :new_branch

  • :f (Boolean, nil) — default: nil —

    alias for :force

  • :orphan (Boolean, String, nil) — default: nil —

    when true, creates a new unborn branch named branch whose first commit has no parents

    When a String, creates an unborn branch with that name, using branch as the start point for the working tree and index.

    false and nil are both treated as unset. A blank branch name is rejected rather than ignored.

  • :start_point (String, nil) — default: nil —

    the commit or branch to start the new branch from; used together with new_branch: true or orphan: true

Returns:

  • git's stdout from the checkout

Raises:

  • if unsupported options are provided

  • if :orphan is given a blank or missing branch name

  • if git exits with a non-zero exit status

API:

  • private



178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/git/repository/branching.rb', line 178

def checkout(branch = nil, opts = {})
  if branch.is_a?(Hash) && opts.empty?
    opts = branch
    branch = nil
  end

  SharedPrivate.assert_valid_opts!(CHECKOUT_ALLOWED_OPTS, **opts)

  target, translated_opts = Private.translate_checkout_opts(branch, opts)
  Git::Commands::Checkout::Branch.new(@execution_context).call(target, **translated_opts).stdout
end

#checkout_file(version, file) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Restore working tree files from a tree-ish

Examples:

Restore README.md to its HEAD state

repo.checkout_file('HEAD', 'README.md')

Parameters:

  • the tree-ish (branch, tag, commit SHA, etc.) to restore the file from

  • the path to the file to restore

Returns:

  • git's stdout from the checkout

Raises:

  • if git exits with a non-zero exit status

API:

  • private



118
119
120
 
# File 'lib/git/repository/branching.rb', line 118

def checkout_file(version, file)
  Git::Commands::Checkout::Files.new(@execution_context).call(version, pathspec: [file]).stdout
end

#checkout_index(options = {}) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Populate the working tree from the index

Examples:

Check out all files from the index

repo.checkout_index(all: true)

Force check out a specific file

repo.checkout_index(force: true, path_limiter: 'README.md')

Check out files to a staging prefix

repo.checkout_index(prefix: 'tmp/stage/', all: true)

Parameters:

  • (defaults to: {})

    options for the checkout-index command

Options Hash (options):

  • :all (Boolean, nil) — default: nil —

    check out all files in the index

  • :force (Boolean, nil) — default: nil —

    overwrite existing files

  • :prefix (String, nil) — default: nil —

    write files under this path prefix rather than the working directory root

  • :path_limiter (String, Pathname, Array<String, Pathname>, nil) — default: nil —

    limit the check out to the given path(s)

Returns:

  • git's stdout from the checkout-index command

Raises:

  • if unsupported options are provided

  • if git exits with a non-zero exit status

API:

  • private



286
287
288
289
290
291
292
 
# File 'lib/git/repository/branching.rb', line 286

def checkout_index(options = {})
  SharedPrivate.assert_valid_opts!(CHECKOUT_INDEX_ALLOWED_OPTS, **options)

  paths = Private.normalize_pathspecs(options[:path_limiter], 'path_limiter')
  keyword_opts = options.except(:path_limiter)
  Git::Commands::CheckoutIndex.new(@execution_context).call(*paths.to_a, **keyword_opts).stdout
end

#current_branch ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the name of the current branch

Examples:

Get the current branch name

repo.current_branch  # => "main"

In detached HEAD state

repo.current_branch  # => "HEAD"

Returns:

  • the current branch name, or 'HEAD' when in detached HEAD state

Raises:

  • if git exits with a non-zero exit status

API:

  • private



65
66
67
68
69
 
# File 'lib/git/repository/branching.rb', line 65

def current_branch
  result = Git::Commands::Branch::ShowCurrent.new(@execution_context).call
  name = result.stdout.strip
  name.empty? ? 'HEAD' : name
end

#current_branch_state ⇒ Git::Repository::Branching::HeadState

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the current HEAD state as a structured value object

HEAD can be in one of three states:

  • :active — HEAD points to a branch ref that has at least one commit.
  • :unborn — HEAD points to a branch ref that has been created but has no commits yet (e.g. immediately after git init before any commit).
  • :detached — HEAD points directly to a commit SHA rather than a branch.

Examples:

Active branch

repo.current_branch_state
# => #<data Git::Repository::Branching::HeadState state=:active, name="main">

Unborn branch (no commits yet)

repo.current_branch_state
# => #<data Git::Repository::Branching::HeadState state=:unborn, name="main">

Detached HEAD

repo.current_branch_state
# => #<data Git::Repository::Branching::HeadState state=:detached, name="HEAD">

Returns:

  • the current HEAD state

Raises:

  • if git exits with a non-zero exit status

API:

  • private



96
97
98
99
100
101
102
 
# File 'lib/git/repository/branching.rb', line 96

def current_branch_state
  branch_name = Git::Commands::Branch::ShowCurrent.new(@execution_context).call.stdout.strip
  return HeadState.new(state: :detached, name: 'HEAD') if branch_name.empty?

  state = Private.get_branch_state(@execution_context, branch_name)
  HeadState.new(state: state, name: branch_name)
end

#in_branch(branch, message = 'in branch work') { ... } ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Run a block with the given branch checked out, then restore the original branch

Records the current branch (or the current commit when HEAD is detached), checks out branch, and yields to the block. If the block returns a truthy value, all pending changes are committed with message (see Committing#commit_all); if it returns a falsy value, the index and working tree are hard-reset instead (see Staging#reset). The original branch or commit is then checked out again. The hard reset discards changes to tracked files only; untracked files created by the block are left in place.

Unlike Git::Branch#in_branch, this method does not create branch. The branch must be an existing local branch. Unlike #checkout, a commit SHA, tag, or remote-tracking branch is rejected before any checkout happens: those detach HEAD, and a commit made there would be left dangling once the original branch is restored. HEAD must be on a branch with at least one commit, or detached: an unborn branch (no commits yet) cannot be checked out again by name, so it is rejected before any checkout happens.

Note: the restore checkout is not wrapped in ensure. If the block, the commit, or the reset raises an exception, the repository is left checked out on branch rather than restored to the original branch.

Examples:

Commit a new file on a feature branch

repo.in_branch('feature', 'Add README') do
  File.write('README.md', '# Hello')
  repo.add('README.md')
  true  # commit and return to the original branch
end

Discard experimental changes to a tracked file

repo.in_branch('scratch') do
  File.write('README.md', '# Try something')
  false  # hard-reset and return to the original branch
end

Parameters:

  • the name of an existing local branch to check out

  • (defaults to: 'in branch work')

    the commit message used when the block returns a truthy value

Yields:

  • executes the block with branch checked out

Yield Returns:

  • (Object) —

    a truthy value to commit all changes, a falsy value to hard-reset

Returns:

  • git's stdout from the final checkout back to the original branch or commit

Raises:

  • if branch is not an existing local branch

  • if HEAD is on an unborn branch

  • if git exits with a non-zero exit status

API:

  • private



245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/git/repository/branching.rb', line 245

def in_branch(branch, message = 'in branch work')
  SharedPrivate.assert_local_branch!(self, branch)
  restore_point = SharedPrivate.head_restore_point(self)
  checkout(branch)
  if yield
    commit_all(message)
  else
    reset(nil, hard: true)
  end
  checkout(restore_point)
end

#is_branch?(branch) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

use #branch? instead

Checks whether the named branch exists locally or as a remote-tracking branch

Examples:

Check whether main exists anywhere

repo.is_branch?('main')  # => true

Parameters:

  • the branch name to look up

Returns:

  • true if the branch exists locally or remotely, false otherwise

Raises:

  • if git exits with a non-zero exit status

API:

  • private



404
405
406
407
408
409
410
 
# File 'lib/git/repository/branching.rb', line 404

def is_branch?(branch) # rubocop:disable Naming/PredicatePrefix
  Git::Deprecation.warn(
    'Git::Repository#is_branch? is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#branch? instead.'
  )
  branch?(branch)
end

#is_local_branch?(branch) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

use #local_branch? instead

Checks whether the named branch exists locally

Examples:

Check whether main exists locally

repo.is_local_branch?('main')  # => true

Parameters:

  • the local branch name to look up

Returns:

  • true if the branch exists locally, false otherwise

Raises:

  • if git exits with a non-zero exit status

API:

  • private



360
361
362
363
364
365
366
 
# File 'lib/git/repository/branching.rb', line 360

def is_local_branch?(branch) # rubocop:disable Naming/PredicatePrefix
  Git::Deprecation.warn(
    'Git::Repository#is_local_branch? is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#local_branch? instead.'
  )
  local_branch?(branch)
end

#is_remote_branch?(branch) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

use #remote_branch? instead

Checks whether the named branch exists as a remote-tracking branch

Examples:

Check whether master exists on any remote

repo.is_remote_branch?('master')  # => true

Parameters:

  • the short branch name to look up across all remotes

Returns:

  • true if a remote-tracking branch with that short name exists, false otherwise

Raises:

  • if git exits with a non-zero exit status

API:

  • private



382
383
384
385
386
387
388
 
# File 'lib/git/repository/branching.rb', line 382

def is_remote_branch?(branch) # rubocop:disable Naming/PredicatePrefix
  Git::Deprecation.warn(
    'Git::Repository#is_remote_branch? is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#remote_branch? instead.'
  )
  remote_branch?(branch)
end

#local_branch?(branch) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true if the named branch exists as a local branch

Examples:

Check whether main exists locally

repo.local_branch?('main')  # => true

Parameters:

  • the local branch name to look up

Returns:

  • true if the branch exists locally, false otherwise

Raises:

  • if git exits with a non-zero exit status

API:

  • private



305
306
307
308
 
# File 'lib/git/repository/branching.rb', line 305

def local_branch?(branch)
  result = Git::Commands::Branch::List.new(@execution_context).call(branch, format: '%(refname:short)')
  result.stdout.chomp == branch
end

#remote_branch?(branch) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true if the named branch exists as a remote-tracking branch

The branch argument must be the short branch name (e.g. 'master'), not the combined remote/branch form (e.g. 'origin/master').

Examples:

Check whether master exists on any remote

repo.remote_branch?('master')  # => true

Parameters:

  • the short branch name to look up across all remotes

Returns:

  • true if a remote-tracking branch with that short name exists, false otherwise

Raises:

  • if git exits with a non-zero exit status

API:

  • private



325
326
327
328
329
 
# File 'lib/git/repository/branching.rb', line 325

def remote_branch?(branch)
  result = Git::Commands::Branch::List.new(@execution_context)
                                      .call("*/#{branch}", remotes: true, format: '%(refname:lstrip=3)')
  result.stdout.each_line.any? { |line| line.chomp == branch }
end

#update_ref(branch, commit) ⇒ Git::CommandLine::Result

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Update a branch ref to point to a new commit

Derives the full ref from the branch argument:

  • remotes/<remote>/<name> or refs/remotes/<remote>/<name> → writes to refs/remotes/<remote>/<name> (remote-tracking branch)
  • Any other value → writes to refs/heads/<branch> (local branch)

Examples:

Advance a local branch to the current HEAD

repo.update_ref('feature', repo.rev_parse('HEAD'))

Reset a local branch to an older commit

repo.update_ref('main', 'abc1234def5678')

Update a remote-tracking branch ref

repo.update_ref('remotes/origin/main', 'abc1234def5678')

Parameters:

  • a local or remote-tracking branch name

    Short local names (e.g. 'main') resolve to refs/heads/<branch>. Remote-tracking names with a remotes/<remote>/ or refs/remotes/<remote>/ prefix (e.g. 'remotes/origin/main') resolve to refs/remotes/<remote>/<name>.

  • the commit SHA to point the branch at

Returns:

  • the result of calling git update-ref

Raises:

  • if git exits with a non-zero exit status

API:

  • private



681
682
683
684
 
# File 'lib/git/repository/branching.rb', line 681

def update_ref(branch, commit)
  ref = Private.build_update_ref(branch)
  Git::Commands::UpdateRef::Update.new(@execution_context).call(ref, commit)
end