Class: Git::Branch Deprecated

Inherits:
Object
  • Object
show all
Defined in:
lib/git/branch.rb

Overview

Deprecated.

Use Repository::Branching#branch_list and the name-based branch operations on Repository instead

Repository::Branching#branch_list returns immutable BranchInfo value objects. Operations that lived on this class are called on the repository with the branch name instead (for example Repository::Branching#checkout and Repository::Branching#branch_delete). Every operation on a Git::Branch emits a deprecation warning; the full, name, remote, to_s, and to_a readers do not.

Represents a Git branch

Branch objects provide access to branch metadata and operations like checkout, delete, and merge. They should be obtained via Repository#branch or Repository#branches, not constructed directly.

Examples:

Getting a branch

git = Git.open('.')
branch = git.branch('main')
branch.checkout

Listing branches

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

Constant Summary collapse

BRANCH_NAME_REGEXP =

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

Note:

This legacy string-constructor path does not resolve remote names containing /. Use Repository#branch_list to build branch objects from remote-aware Git::BranchInfo values.

Regular expression for parsing branch refnames

Matches full and short refnames, capturing an optional remote name and the branch name. Used internally to identify remote-tracking branches.

%r{
  ^
    # Optional 'remotes/' or 'refs/remotes/' at the beginning to specify a remote tracking branch
    # with a <remote_name>. <remote_name> is nil if not present.
    (?:
      (?:(?:refs/)?remotes/)(?<remote_name>[^/]+)/
    )?
    (?<branch_name>.*)
  $
}x

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base, branch_info_or_name) ⇒ 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.

Note:

Use Repository#branch or Repository#branches instead of constructing directly

Initialize a new Branch object

Parameters:

  • base (Git::Repository) —

    the git repository

  • branch_info_or_name (Git::BranchInfo, String) —

    branch info object or name string

    Passing a BranchInfo is preferred; String support is for backward compatibility.



91
92
93
94
95
96
97
 
# File 'lib/git/branch.rb', line 91

def initialize(base, branch_info_or_name)
  @base = base
  @gcommit = nil
  @stashes = nil

  initialize_from_argument(branch_info_or_name)
end

Instance Attribute Details

#full ⇒ String

The full refname of this branch

For local branches this is the short name (e.g. 'main'). For remote-tracking branches obtained via Repository#branches this includes the remotes/ prefix (e.g. 'remotes/origin/main'). Branches constructed by Remote#branch use the <remote>/<branch> form (e.g. 'origin/main') which does not populate #remote.

Examples:

Local and remote-tracking branch full refnames

git.branch('main').full                  #=> 'main'
git.branch('remotes/origin/main').full   #=> 'remotes/origin/main'

Returns:

  • (String) —

    the full refname



48
49
50
 
# File 'lib/git/branch.rb', line 48

def full
  @full
end

#name ⇒ String

The short branch name without the remote prefix

For both local and remote-tracking branches this is the bare branch name (e.g. 'main' rather than 'remotes/origin/main').

Examples:

Local and remote-tracking branch short names

git.branch('main').name                  #=> 'main'
git.branch('remotes/origin/main').name   #=> 'main'

Returns:

  • (String) —

    the short branch name



77
78
79
 
# File 'lib/git/branch.rb', line 77

def name
  @name
end

#remote ⇒ Git::Remote?

The remote for this branch, or nil for local or bare-name remote-tracking branches

Set to a Remote object only when this branch was initialized with a remotes/<remote>/ or refs/remotes/<remote>/ prefix. nil for local branches and for remote-tracking branches in <remote>/<branch> form (such as those returned by Remote#branch).

Examples:

Local and remote-tracking branches

git.branch('main').remote                  #=> nil
git.branch('remotes/origin/main').remote   #=> #<Git::Remote 'origin'>
git.remote('origin').branch('main').remote #=> nil  # uses 'origin/main' form

Returns:



64
65
66
 
# File 'lib/git/branch.rb', line 64

def remote
  @remote
end

Instance Method Details

#archive(file, opts = {}) ⇒ String

Deprecated.

Use Repository::ObjectOperations#archive with the branch name instead

Pass the branch name for a local branch, or "remotes/#{remote}/#{name}" (the value of #full) for a remote-tracking branch; the shorter "#{remote}/#{name}" can resolve a local branch of that name.

Archives this branch and writes the result to a file

Examples:

Archive to a tar file

git.branch('main').archive('/tmp/main.tar', format: 'tar')

Archive to a zip file

git.branch('main').archive('/tmp/main.zip', format: 'zip')

Archive a remote branch to a tgz file

git.remote('origin').branch('main').archive('/tmp/main.tgz', format: 'tgz')

Parameters:

  • file (String) —

    path to the destination archive file

  • opts (Hash) (defaults to: {}) —

    archive options (see Repository#archive)

Options Hash (opts):

  • :format (String) — default: 'zip' —

    archive format for this wrapper: 'tar', 'zip', or 'tgz'

  • :prefix (String) — default: nil —

    prefix prepended to every filename in the archive

  • :path (String) — default: nil —

    path within the tree to include in the archive

  • :remote (String) — default: nil —

    retrieve the archive from a remote repository

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

    apply gzip compression after writing the archive; set automatically when format: 'tgz' is given

Returns:

  • (String) —

    the path to the written archive file

Raises:

  • (ArgumentError) —

    when archive options or destination path are invalid

  • (Git::FailedError) —

    if git archive fails

See Also:



248
249
250
251
252
253
254
255
 
# File 'lib/git/branch.rb', line 248

def archive(file, opts = {})
  Git::Deprecation.warn(
    'Git::Branch#archive is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#archive(name, file, opts) or, for a remote-tracking branch, ' \
    'Git::Repository#archive("remotes/remote/name", file, opts) instead.'
  )
  branch_repository.archive(@full, file, opts)
end

#checkout ⇒ String

Deprecated.

Use Repository::Branching#checkout with the branch name instead

Repository::Branching#checkout does not create a missing local branch, apart from the guess git makes on its own: with no :no_guess option, git creates a tracking branch when exactly one remote has a branch of that name. To reproduce the create-or-checkout behavior of this method, call Repository::Branching#branch_new when Repository::Branching#local_branch? is false, then Repository::Branching#checkout. Pass "remotes/#{remote}/#{name}" (the value of #full) for a remote-tracking branch; the shorter "#{remote}/#{name}" can resolve a local branch of that name.

Checks out this branch, attempting to create it first if it does not already exist

Branch creation is attempted via #check_if_create; any error from that step is silently ignored and the checkout proceeds regardless.

Note: for remote-tracking branches (where #remote is not nil), check_if_create will attempt to create a local branch named #name as a side-effect before checking out #full (which typically results in a detached HEAD). This is a known limitation; see ruby-git#1280.

Examples:

Check out a branch

git = Git.open('.')
git.branch('main').checkout

Returns:

  • (String) —

    git's stdout from the checkout

Raises:

See Also:



192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/git/branch.rb', line 192

def checkout
  Git::Deprecation.warn(
    'Git::Branch#checkout is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#checkout(name) or, for a remote-tracking branch, ' \
    'Git::Repository#checkout("remotes/remote/name") instead. Git::Repository#checkout does not ' \
    'create a missing local branch (beyond the guess git makes from a unique remote-tracking ' \
    'branch); call Git::Repository#branch_new first unless Git::Repository#local_branch? is true.'
  )
  check_if_create
  branch_repository.checkout(@full)
end

#contains?(commit) ⇒ Boolean

Deprecated.

Use Repository::Branching#branch_contains with the commit and branch name instead

Repository::Branching#branch_contains returns the matching branch names as a String; test it with empty?.

Returns true if this branch contains the given commit

Note: this queries local branches by short name. For a remote-tracking branch (where #remote is not nil), it checks the local branch with the same #name rather than the remote-tracking ref, which may give an inaccurate result.

Examples:

Check if a commit is reachable from this branch

git.branch('main').contains?('abc1234') #=> true

Parameters:

  • commit (String) —

    the commit SHA or ref to check

Returns:

  • (Boolean) —

    whether this branch contains the given commit

Raises:

See Also:



417
418
419
420
421
422
423
 
# File 'lib/git/branch.rb', line 417

def contains?(commit)
  Git::Deprecation.warn(
    'Git::Branch#contains? is deprecated and will be removed in v6.0.0. ' \
    'Use !Git::Repository#branch_contains(commit, name).empty? instead.'
  )
  !branch_repository.branch_contains(commit, name).empty?
end

#create ⇒ nil

Deprecated.

Use Repository::Branching#branch_new instead

Repository::Branching#branch_new raises FailedError when the branch already exists rather than ignoring the error.

Creates this branch if it does not already exist

Silently ignores any error raised during branch creation (including the case where the branch already exists).

Examples:

Create a new branch

git.branch('feature').create

Returns:

  • (nil)

See Also:



325
326
327
328
329
330
331
 
# File 'lib/git/branch.rb', line 325

def create
  Git::Deprecation.warn(
    'Git::Branch#create is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#branch_new instead.'
  )
  check_if_create
end

#current ⇒ Boolean

Deprecated.

Compare Repository::Branching#current_branch with the branch name instead

Returns true if this is the currently checked-out branch

Note: this compares the current branch's short name against #name. For a remote-tracking branch (where #remote is not nil), #name is still the bare short name (e.g. 'main'), so this will return true whenever the local branch with that name is checked out — not the remote-tracking ref itself.

Examples:

Check whether currently on main

git.branch('main').current #=> true

Returns:

  • (Boolean) —

    whether this branch is currently checked out

Raises:

See Also:



385
386
387
388
389
390
391
 
# File 'lib/git/branch.rb', line 385

def current # rubocop:disable Naming/PredicateMethod
  Git::Deprecation.warn(
    'Git::Branch#current is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#current_branch == name instead.'
  )
  branch_repository.current_branch == @name
end

#delete ⇒ String

Deprecated.

Use Repository::Branching#branch_delete instead

Pass the branch name for a local branch, or "#{remote}/#{name}" with remotes: true for a remote-tracking branch.

Deletes this branch

Remote-tracking branches (one where #remote is not nil) delete the local remote-tracking ref; they do not push a deletion to the remote.

Examples:

Delete a local branch

git.branch('old-feature').delete

Returns:

  • (String) —

    git's deletion output

Raises:

  • (Git::Error) —

    if the branch cannot be deleted

See Also:



352
353
354
355
356
357
358
359
360
361
362
363
 
# File 'lib/git/branch.rb', line 352

def delete
  Git::Deprecation.warn(
    'Git::Branch#delete is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#branch_delete(name) or, for a remote-tracking branch, ' \
    'Git::Repository#branch_delete("remote/name", remotes: true) instead.'
  )
  if @remote
    branch_repository.branch_delete("#{@remote.name}/#{@name}", remotes: true)
  else
    branch_repository.branch_delete(@name)
  end
end

#gcommit ⇒ Git::Object

Deprecated.

Use Repository::ObjectOperations#gcommit with the branch name instead

Pass the branch name for a local branch, or "remotes/#{remote}/#{name}" (the value of #full) for a remote-tracking branch; the shorter "#{remote}/#{name}" can resolve a local branch of that name.

Returns the commit at the tip of this branch

The result is memoized after the first call.

Examples:

Get the tip commit

git.branch('main').gcommit #=> #<Git::Object ...>

Returns:

  • (Git::Object) —

    the commit at the tip of this branch

See Also:



116
117
118
119
120
121
122
123
124
 
# File 'lib/git/branch.rb', line 116

def gcommit
  Git::Deprecation.warn(
    'Git::Branch#gcommit is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#gcommit(name) or, for a remote-tracking branch, ' \
    'Git::Repository#gcommit("remotes/remote/name") instead.'
  )
  @gcommit ||= branch_repository.gcommit(@full)
  @gcommit
end

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

Deprecated.

Use Repository::Branching#in_branch with the branch name instead

Repository::Branching#in_branch does not create the branch and restores a detached HEAD to its original commit. It takes an existing local branch, so a remote-tracking Git::Branch has no direct replacement: this method checked out the remote-tracking ref, detaching HEAD. Create a local branch from that ref with Repository::Branching#branch_new first.

Checks out this branch for the duration of a block, then restores the original branch

If the block returns a truthy value, all pending changes are committed with the given message before switching back to the original branch. If the block returns a falsy value, a hard reset is performed before switching back.

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

Examples:

Commit a new file on a feature branch

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

Parameters:

  • message (String) (defaults to: 'in branch work') —

    commit message used when the block returns truthy

Yields:

  • Executes the block with this branch checked out

Yield Returns:

  • (Object) —

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

Returns:

  • (String) —

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

Raises:

  • (Git::FailedError) —

    if any of the underlying git operations (checkout, commit, reset) fail

See Also:



295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/git/branch.rb', line 295

def in_branch(message = 'in branch work')
  Git::Deprecation.warn(
    'Git::Branch#in_branch is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#in_branch(name, message) instead. It takes an existing local ' \
    'branch; for a remote-tracking branch, create a local branch from it first.'
  )
  old_current = branch_repository.current_branch
  # checkout is deprecated too; silence it so one in_branch call emits one warning
  Git::Deprecation.silence { checkout }
  yield ? branch_repository.commit_all(message) : branch_repository.reset(nil, hard: true)
  branch_repository.checkout(old_current)
end

#merge(branch, message = nil) ⇒ String #merge ⇒ String

Deprecated.

Use Repository::Merging#merge_into in place of merge(branch) and Repository::Merging#merge with the branch name in place of merge()

Repository::Merging#merge_into returns the merge's stdout, does not hard-reset after the merge, and restores a detached HEAD to its original commit. It takes an existing local branch, so a remote-tracking Git::Branch has no direct replacement: merge(branch) checked out the remote-tracking ref, detaching HEAD. Create a local branch from that ref with Repository::Branching#branch_new first.

Merges a branch into this branch, or merges this branch into the current branch

Overloads:

  • #merge(branch, message = nil) ⇒ String

    Temporarily checks out this branch, merges the given branch into it, then restores the original branch.

    Note: if self is a remote-tracking branch (where #remote is not nil), this delegates to #checkout which has the detached-HEAD side-effect described there. The remote-tracking ref will not be updated.

    Examples:

    Merge a feature branch into main

    git.branch('main').merge('feature')

    Parameters:

    • branch (String) —

      the name of the branch to merge into this one

    • message (String, nil) (defaults to: nil) —

      commit message for the merge commit

    Returns:

    • (String) —

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

  • #merge ⇒ String

    Merges this branch into the currently checked-out branch.

    Examples:

    Merge main into the current branch

    git.branch('main').merge

    Returns:

    • (String) —

      git's stdout from the merge command

Raises:

See Also:



472
473
474
475
476
477
478
 
# File 'lib/git/branch.rb', line 472

def merge(branch = nil, message = nil)
  if branch
    merge_into_this_branch(branch, message)
  else
    merge_into_current_branch
  end
end

#stashes ⇒ Git::Stashes

Deprecated.

Use Repository#stash_infos instead

Returns the stash list for this repository

This method ignores the branch receiver and returns every stash in the repository, so git.branch('feature').stashes and git.branch('main').stashes return the same entries. It is deprecated and will be removed in v6.0.0.

The result is memoized after the first call.

Examples:

Iterate over stash entries (deprecated)

git.branch('main').stashes.each { |s| puts s }

The replacement

repo.stash_infos.each { |info| puts info.message }

Returns:

See Also:

  • Repository#stash_infos


147
148
149
150
151
152
153
154
155
 
# File 'lib/git/branch.rb', line 147

def stashes
  Git::Deprecation.warn(
    'Git::Branch#stashes is deprecated and will be removed in v6.0.0. ' \
    'It ignores the branch and returns all repository stashes. ' \
    'Use Git::Repository#stash_infos instead.'
  )
  # Git::Stashes is deprecated too; silence it so one stashes call emits one warning
  @stashes ||= Git::Deprecation.silence { Git::Stashes.new(branch_repository) }
end

#to_a ⇒ Array<String>

Returns this branch as a single-element array containing its full refname

Examples:

Get branch as array

git.branch('main').to_a #=> ['main']

Returns:

  • (Array<String>) —

    a single-element array containing the full refname



527
528
529
 
# File 'lib/git/branch.rb', line 527

def to_a
  [@full]
end

#to_s ⇒ String

Returns the full refname of this branch as a string

Examples:

Get branch as string

git.branch('main').to_s #=> 'main'

Returns:

  • (String) —

    the full refname



538
539
540
 
# File 'lib/git/branch.rb', line 538

def to_s
  @full
end

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

Deprecated.

Use Repository::Branching#update_ref instead

Pass the branch name for a local branch, or "remotes/#{remote}/#{name}" for a remote-tracking branch.

Updates the git ref for this branch to point to the given commit

The target ref depends on whether #remote is set:

  • When #remote is not nil (i.e. the branch was initialized with a remotes/<remote>/ or refs/remotes/<remote>/ prefix), updates refs/remotes/<remote>/<name>.
  • Otherwise updates refs/heads/<name>. Note that branches in the <remote>/<branch> form (e.g. those returned by Remote#branch) have remote == nil and therefore update refs/heads/<remote>/<name>, not refs/remotes/....

Examples:

Advance a local branch to a new commit

git.branch('feature').update_ref('abc1234def5678')

Parameters:

  • commit (String) —

    the commit SHA to point this branch at

Returns:

Raises:

See Also:



507
508
509
510
511
512
513
514
515
516
517
518
 
# File 'lib/git/branch.rb', line 507

def update_ref(commit)
  Git::Deprecation.warn(
    'Git::Branch#update_ref is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#update_ref(name, commit) or, for a remote-tracking branch, ' \
    'Git::Repository#update_ref("remotes/remote/name", commit) instead.'
  )
  if @remote
    branch_repository.update_ref("remotes/#{@remote.name}/#{@name}", commit)
  else
    branch_repository.update_ref(@name, commit)
  end
end