Class: Git::Remote

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

Overview

A remote in a Git repository

Remote objects provide access to remote metadata and operations like fetch, merge, and remove. They should be obtained via Base#remote or the remote factory method on a Git::Repository instance, not constructed directly.

Examples:

Getting a remote

git = Git.open('.')
remote = git.remote('origin')
remote.fetch

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:

Use Base#remote or the remote factory method on a Git::Repository instance instead of constructing directly

Initialize a new Remote object

Parameters:

  • base (Git::Base, Git::Repository) —

    the git repository

    Accepts either a Base (legacy) or a Git::Repository (new form). The is_a?(Git::Base) guard will be removed when Base is deleted in Phase 4.

  • name (String) —

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



56
57
58
59
60
61
62
 
# File 'lib/git/remote.rb', line 56

def initialize(base, name)
  @base = base
  config = 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



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

def fetch_opts
  @fetch_opts
end

#name ⇒ String

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

Returns:

  • (String) —

    the remote name



27
28
29
 
# File 'lib/git/remote.rb', line 27

def name
  @name
end

#url ⇒ String?

The URL of this remote

Returns:

  • (String, nil) —

    the remote URL



33
34
35
 
# File 'lib/git/remote.rb', line 33

def url
  @url
end

Instance Method Details

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

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>



105
106
107
108
109
110
 
# File 'lib/git/remote.rb', line 105

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

#fetch(opts = {}) ⇒ String

Fetches from this remote

Examples:

Fetch from origin

git.remote('origin').fetch

Parameters:

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

    fetch options (see Base#fetch)

Returns:

  • (String) —

    git's stdout from the fetch

Raises:



75
76
77
 
# File 'lib/git/remote.rb', line 75

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:



90
91
92
93
94
 
# File 'lib/git/remote.rb', line 90

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

#remove ⇒ Git::CommandLineResult

Removes this remote from the repository

Examples:

Remove the upstream remote

git.remote('upstream').remove

Returns:

Raises:



121
122
123
 
# File 'lib/git/remote.rb', line 121

def remove
  remote_repository.remove_remote(@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



132
133
134
 
# File 'lib/git/remote.rb', line 132

def to_s
  @name
end