Class: Git::Remote Deprecated

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

Overview

Deprecated.

Use Git::Repository::RemoteOperations#remote_list and the repository-level remote operations instead

Git::Repository::RemoteOperations#remote_list returns immutable RemoteInfo value objects. Operations that lived on this class are called on the repository with the remote name instead (for example Git::Repository::RemoteOperations#fetch and Git::Repository::RemoteOperations#remote_remove). Constructing a Git::Remote emits a deprecation warning.

A remote in a Git repository

Remote objects provide access to remote metadata and operations like fetch, merge, and remove. This class and Git::Repository#remote, which returns it, are both deprecated: read remote configuration through Git::Repository::RemoteOperations#remote_list and call the repository-level operations with the remote name instead.

Examples:

Reading a remote and fetching from it without Git::Remote

git = Git.open('.')
origin = git.remote_list.find { |r| r.name == 'origin' }  #=> Git::RemoteInfo
origin.url.first
git.fetch(origin.name)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base, name) ⇒ Remote

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:

Do not construct directly. Git::Repository#remote is deprecated as well; use Git::Repository::RemoteOperations#remote_list and the repository-level remote operations instead.

Initialize a new Remote object

Parameters:

  • base (Git::Repository) —

    the git repository

  • name (String) —

    the remote name (e.g. 'origin')



64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/git/remote.rb', line 64

def initialize(base, name)
  Git::Deprecation.warn(
    'Git::Remote is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#remote_list and the repository-level remote operations instead.'
  )
  @base = base
  # config_remote is deprecated too; silence it so one Git::Remote.new emits one warning
  config = Git::Deprecation.silence { remote_repository.config_remote(name) }
  @name = name
  @url = config['url']
  @fetch_opts = config['fetch']
end

Instance Attribute Details

#fetch_opts ⇒ String?

The fetch refspec for this remote

Returns:

  • (String, nil) —

    the fetch options string



50
51
52
 
# File 'lib/git/remote.rb', line 50

def fetch_opts
  @fetch_opts
end

#name ⇒ String

The name of this remote (e.g. 'origin')

Returns:

  • (String) —

    the remote name



38
39
40
 
# File 'lib/git/remote.rb', line 38

def name
  @name
end

#url ⇒ String?

The URL of this remote

Returns:

  • (String, nil) —

    the remote URL



44
45
46
 
# File 'lib/git/remote.rb', line 44

def url
  @url
end

Instance Method Details

#branch(branch = nil) ⇒ Git::Branch

Deprecated.

Use Git::Repository#branch_list("#{name}/#{branch || current_branch}").first instead

With no argument this method falls back to the current branch, so the replacement has to supply Git::Repository#current_branch itself. The replacement returns a BranchInfo value object rather than a Branch, and returns nil when the remote-tracking branch does not exist.

Returns a Branch object for the given branch on this remote

Examples:

Get the remote-tracking branch object

git.remote('origin').branch('main')  #=> #<Git::Branch 'origin/main'>

Parameters:

  • branch (String) (defaults to: nil) —

    the branch name on this remote (defaults to current branch)

Returns:

  • (Git::Branch) —

    a branch object representing <remote>/<branch>



152
153
154
155
 
# File 'lib/git/remote.rb', line 152

def branch(branch = nil)
  branch ||= remote_repository.current_branch
  Git::Branch.new(@base, "#{@name}/#{branch}")
end

#fetch(opts = {}) ⇒ String

Fetches from this remote

Examples:

Fetch from origin

git.remote('origin').fetch

Parameters:

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

    options for the fetch command

Options Hash (opts):

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

    fetch all tags from the remote (--tags)

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

    remove remote-tracking references that no longer exist on the remote (--prune)

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

    remove local tags that no longer exist on the remote (--prune-tags)

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

    override the fast-forward check when using explicit refspecs (--force)

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

    allow git fetch to update the branch pointed to by HEAD (--update-head-ok)

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

    convert a shallow clone into a full repository (--unshallow)

  • :depth (String, Integer, nil) — default: nil —

    limit history to N commits from each branch tip (--depth=N)

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

    one or more refspecs to fetch as positional arguments after the remote name

Returns:

  • (String) —

    git's stdout from the fetch

Raises:



112
113
114
 
# File 'lib/git/remote.rb', line 112

def fetch(opts = {})
  remote_repository.fetch(@name, opts)
end

#merge(branch = nil) ⇒ String

Merges this remote into the given (or current) local branch

Examples:

Merge origin/main into the current branch

git.remote('origin').merge('main')

Parameters:

  • branch (String) (defaults to: nil) —

    the local branch to merge into (defaults to current branch)

Returns:

  • (String) —

    git's stdout from the merge

Raises:



127
128
129
130
131
 
# File 'lib/git/remote.rb', line 127

def merge(branch = nil)
  branch ||= remote_repository.current_branch
  remote_tracking_branch = "#{@name}/#{branch}"
  remote_repository.merge(remote_tracking_branch)
end

#remove ⇒ Git::CommandLine::Result

Removes this remote from the repository

Examples:

Remove the upstream remote

git.remote('upstream').remove

Returns:

Raises:



166
167
168
 
# File 'lib/git/remote.rb', line 166

def remove
  remote_repository.remote_remove(@name)
end

#to_s ⇒ String

Returns the name of this remote as a string

Examples:

Get the remote name as a string

git.remote('origin').to_s  #=> 'origin'

Returns:

  • (String) —

    the remote name



177
178
179
 
# File 'lib/git/remote.rb', line 177

def to_s
  @name
end