Module: Git::Repository::RemoteOperations Private

Included in:
Git::Repository
Defined in:
lib/git/repository/remote_operations.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.

Mixin that adds remote operation facade methods to Git::Repository

Included by Git::Repository.

Instance Method Summary collapse

Instance Method Details

#add_remote(name, url, opts = {}) ⇒ Git::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.

Deprecated.

Use #remote_add instead

Returns the newly added remote.

Parameters:

  • name (String) —

    the name for the new remote

  • url (String, Git::Repository) —

    the URL of the remote repository

    A Git::Repository instance is accepted for local references and converted to url.repo.to_s.

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

    options for adding the remote

Options Hash (opts):

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

    fetch from the remote immediately after adding it (-f)

    The deprecated alias :with_fetch is accepted and normalized automatically.

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

    track only the given branch during fetch (-t)

Returns:

Raises:

  • (ArgumentError) —

    when unsupported option keys are provided

  • (Git::FailedError) —

    when git exits with a non-zero status



374
375
376
377
378
379
380
 
# File 'lib/git/repository/remote_operations.rb', line 374

def add_remote(name, url, opts = {})
  Git::Deprecation.warn(
    'Git::Repository#add_remote is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#remote_add instead.'
  )
  remote_add(name, url, opts)
end

#config_remote(name) ⇒ Hash{String => 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.

Return the git configuration entries for a named remote

Reads git config --list and returns all entries whose keys begin with remote.<name>., with the remote.<name>. prefix stripped. This typically yields at least "url" and "fetch" for a configured remote.

Examples:

Retrieve the config for the 'origin' remote

repo.config_remote('origin')
#=> {
#     'url'   => 'https://github.com/user/repo.git',
#     'fetch' => '+refs/heads/*:refs/remotes/origin/*'
#   }

Parameters:

  • name (String) —

    the name of the remote (e.g. "origin")

Returns:

  • (Hash{String => String}) —

    configuration entries for the remote, keyed without the remote.<name>. prefix

    Returns an empty hash when no entries are found.

Raises:



525
526
527
528
529
530
 
# File 'lib/git/repository/remote_operations.rb', line 525

def config_remote(name)
  prefix = "remote.#{name}."
  Private.config_list(@execution_context).each_with_object({}) do |(key, value), hsh|
    hsh[key.delete_prefix(prefix)] = value if key.start_with?(prefix)
  end
end

#fetch(remote = 'origin', 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.

Download objects and refs from a remote repository

Fetches branches and/or tags from one or more other repositories, along with the objects necessary to complete their histories. The local tracking references are updated but the working directory is not modified.

Examples:

Fetch from the default remote

repo.fetch

Fetch from a named remote

repo.fetch('upstream')

Fetch all remotes at once

repo.fetch(all: true)

Fetch and prune deleted remote branches

repo.fetch('origin', prune: true)

Fetch a specific refspec

repo.fetch('origin', ref: 'refs/heads/main:refs/remotes/origin/main')

Fetch multiple refspecs

repo.fetch('origin', ref: ['refs/heads/main', 'refs/heads/develop'])

Fetch and include all tags

repo.fetch('origin', tags: true)

Parameters:

  • remote (String, Hash, nil) (defaults to: 'origin') —

    the remote name or URL to fetch from

    When a Hash is given it is treated as opts and remote defaults to nil (which omits the remote positional argument and lets git use the configured default).

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

    options for the fetch command

Options Hash (opts):

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

    fetch from all configured remotes (--all)

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

    fetch all tags from the remote (--tags)

    Alias: :t

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

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

    Alias: :p

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

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

    Alias: :P. The legacy dash-style key :'prune-tags' is also accepted and normalized automatically.

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

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

    Alias: :f

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

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

    Alias: :u. The legacy dash-style key :'update-head-ok' is also accepted and normalized automatically.

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

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

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

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

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

    one or more refspecs to fetch; forwarded as positional arguments after the remote name. An explicit remote is required when :ref is given.

Returns:

  • (String) —

    the merged stdout from the fetch command

Raises:

  • (ArgumentError) —

    when unsupported option keys are provided or :ref is supplied without an explicit remote

  • (Git::FailedError) —

    when git exits with a non-zero status



129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/git/repository/remote_operations.rb', line 129

def fetch(remote = 'origin', opts = {})
  remote, opts = Private.resolve_fetch_target(remote, opts)

  opts = Private.normalize_fetch_keys(opts)
  SharedPrivate.assert_valid_opts!(FETCH_ALLOWED_OPTS, **opts)

  opts = opts.dup
  refspecs = Array(opts.delete(:ref)).compact
  positionals = [*([remote] if remote), *refspecs]

  Git::Commands::Fetch.new(@execution_context).call(*positionals, **opts, merge: true).stdout
end

#ls_remote(location = nil, opts = {}) ⇒ Hash{String => Hash}

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:

The :ref value in each pair is only the first path segment of the full git ref (e.g. "refs" for refs/heads/main), not the complete ref path. This matches the behavior of 4.x. See issue 1416 for the planned fix.

List references available in a remote repository

Queries a remote for its available refs and returns a structured Hash mapping ref types to name/sha pairs. The remote is contacted but no local objects are created or updated.

Examples:

List all refs from the local repository

repo.ls_remote
# => {"head"=>{ref: "HEAD", sha: "abc123"},
#     "branches"=>{"main"=>{ref: "refs", sha: "abc123"}}}

List all refs from a named remote

repo.ls_remote('origin')
# => {"head"=>..., "branches"=>..., "tags"=>...}

List only tags from a named remote

repo.ls_remote('origin', tags: true)
# => {"tags"=>{"v1.0"=>{ref: "refs", sha: "def456"}}}

Parameters:

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

    the remote name or URL to query; defaults to '.' (the local repository) when nil

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

    options for the ls-remote command

Options Hash (opts):

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

    limit output to refs under refs/heads/; alias: :b

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

    limit output to refs under refs/heads/; kept for backward compatibility; alias: :h

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

    limit output to refs under refs/tags/; alias: :t

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

    exclude peeled tags and pseudorefs like HEAD from the output

  • :timeout (Numeric) — default: nil —

    execution timeout in seconds

Returns:

  • (Hash{String => Hash}) —

    a Hash keyed by ref type (e.g. "head", "branches", "tags"; other git namespace segments may appear for non-standard refs); for named refs the value is a Hash keyed by ref name mapping to { ref: String, sha: String }; for the "head" entry the value is { ref: String, sha: String } directly

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

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



631
632
633
634
635
636
 
# File 'lib/git/repository/remote_operations.rb', line 631

def ls_remote(location = nil, opts = {})
  SharedPrivate.assert_valid_opts!(LS_REMOTE_ALLOWED_OPTS, **opts)
  repository = location || '.'
  output_lines = Git::Commands::LsRemote.new(@execution_context).call(repository, **opts).stdout.split("\n")
  Git::Parsers::LsRemote.parse_output(output_lines)
end

#pull(remote = nil, 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.

Incorporate changes from a remote repository into the current branch

Fetches from the given remote and merges into the current branch. In its default mode, git pull is shorthand for git fetch followed by git merge FETCH_HEAD. The merge editor is suppressed (--no-edit) and progress output is silenced (--no-progress) by default.

Examples:

Pull from the default remote and branch

repo.pull

Pull from a named remote

repo.pull('upstream')

Pull a specific branch from a remote

repo.pull('origin', 'main')

Pull allowing unrelated histories

repo.pull('origin', 'main', allow_unrelated_histories: true)

Parameters:

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

    the remote name or URL to pull from

    When nil, git uses the tracking remote for the current branch.

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

    the remote branch name to pull

    When nil, git uses the tracking branch for the current branch. A branch may not be specified without also specifying a remote.

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

    options for the pull command

Options Hash (opts):

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

    allow merging histories that do not share a common ancestor (--allow-unrelated-histories)

Returns:

  • (String) —

    the stdout from the pull command

Raises:

  • (ArgumentError) —

    when a branch is given without a remote, or when unsupported option keys are provided

  • (Git::FailedError) —

    when git exits with a non-zero status



194
195
196
197
198
199
200
201
202
203
 
# File 'lib/git/repository/remote_operations.rb', line 194

def pull(remote = nil, branch = nil, opts = {})
  raise ArgumentError, 'You must specify a remote if a branch is specified' if remote.nil? && !branch.nil?

  SharedPrivate.assert_valid_opts!(PULL_ALLOWED_OPTS, **opts)
  positional_args = [remote, branch].compact
  Git::Commands::Pull
    .new(@execution_context)
    .call(*positional_args, no_edit: true, no_progress: true, **opts)
    .stdout
end

#push(remote = nil, branch = nil, opts = nil) ⇒ 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.

Push refs to a remote repository

Examples:

Push using the current branch's default remote and push configuration

repo.push

Push to a named remote

repo.push('origin')

Force-push the current branch to a named remote

repo.push('origin', force: true)

Push a specific branch to a named remote

repo.push('origin', 'main')

Push a branch and all tags to a named remote

repo.push('origin', 'main', tags: true)

Push all branches to a named remote

repo.push('origin', all: true)

Mirror all refs to a named remote

repo.push('origin', mirror: true)

Parameters:

  • remote (String, Hash, nil) (defaults to: nil) —

    the remote name or URL to push to

    When a Hash is given it is treated as opts and remote defaults to nil so git uses the configured default push target.

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

    the branch name or refspec to push

    When a Hash is given it is treated as opts and branch defaults to nil. A branch may not be specified without also specifying a remote.

  • opts (Hash, Boolean, nil) (defaults to: nil) —

    options for the push command

    For backward compatibility, a Boolean is interpreted as tags: <Boolean>.

Options Hash (opts):

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

    push all branches (--all)

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

    push all refs under refs/ to the remote (--mirror)

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

    push all refs under refs/tags/ in a second git push invocation (--tags)

    When :mirror is also given, the tags push is suppressed because --mirror already includes tags.

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

    force updates, overriding the fast-forward check (--force)

    Alias: :f

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

    delete the named refs from the remote (--delete)

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

    one or more server-side push option values (--push-option=<value>, repeatable)

Returns:

  • (String) —

    the stdout from the push command

Raises:

  • (ArgumentError) —

    when branch is given without remote

  • (ArgumentError) —

    when unsupported option keys are provided

  • (Git::FailedError) —

    when git exits with a non-zero exit status



284
285
286
287
288
289
290
291
292
293
 
# File 'lib/git/repository/remote_operations.rb', line 284

def push(remote = nil, branch = nil, opts = nil)
  remote, branch, opts = Private.normalize_push_args(remote, branch, opts)
  SharedPrivate.assert_valid_opts!(PUSH_ALLOWED_OPTS, **opts)
  raise ArgumentError, 'remote is required if branch is specified' if !remote && branch

  first_result = Private.push_refs(@execution_context, remote, branch, opts)
  return first_result.stdout unless Private.push_tags_separately?(opts)

  Private.push_tags(@execution_context, remote, opts).stdout
end

#remote(name = 'origin') ⇒ Git::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.

Returns a Git::Remote object for the named remote

Examples:

Get the default 'origin' remote

repo.remote  #=> #<Git::Remote 'origin'>

Get a named remote

repo.remote('upstream')  #=> #<Git::Remote 'upstream'>

Parameters:

  • name (String) (defaults to: 'origin') —

    the remote name (defaults to 'origin')

Returns:

Raises:



546
547
548
 
# File 'lib/git/repository/remote_operations.rb', line 546

def remote(name = 'origin')
  Git::Remote.new(self, name)
end

#remote_add(name, url, opts = {}) ⇒ Git::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.

Register a new remote in the local repository

Associates name with url and optionally fetches immediately or configures which branches are tracked.

Examples:

Add a remote

repo.remote_add('upstream', 'https://github.com/user/repo.git')

Add a remote and fetch immediately

repo.remote_add('upstream', 'https://github.com/user/repo.git', fetch: true)

Add a remote tracking a specific branch

repo.remote_add('upstream', 'https://github.com/user/repo.git', track: 'main')

Parameters:

  • name (String) —

    the name for the new remote

  • url (String, Git::Repository) —

    the URL of the remote repository

    A Git::Repository instance is accepted for local references and converted to url.repo.to_s.

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

    options for adding the remote

Options Hash (opts):

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

    fetch from the remote immediately after adding it (-f)

    The deprecated alias :with_fetch is accepted and normalized automatically.

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

    track only the given branch during fetch (-t)

Returns:

Raises:

  • (ArgumentError) —

    when unsupported option keys are provided

  • (Git::FailedError) —

    when git exits with a non-zero status



339
340
341
342
343
344
345
346
 
# File 'lib/git/repository/remote_operations.rb', line 339

def remote_add(name, url, opts = {})
  url = url.repo.to_s if url.is_a?(Git::Repository)
  opts = Private.normalize_add_remote_keys(opts)
  SharedPrivate.assert_valid_opts!(REMOTE_ADD_ALLOWED_OPTS, **opts)
  Git::Commands::Remote::Add.new(@execution_context).call(name, url, **opts)

  Git::Remote.new(self, name)
end

#remote_remove(name) ⇒ 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.

Removes a remote from this repository

Deletes the remote named name along with its associated configuration, tracking references, and remote-tracking branches.

Examples:

Remove a remote named 'upstream'

repo.remote_remove('upstream')

Parameters:

  • name (String) —

    the name of the remote to remove

Returns:

Raises:



396
397
398
 
# File 'lib/git/repository/remote_operations.rb', line 396

def remote_remove(name)
  Git::Commands::Remote::Remove.new(@execution_context).call(name)
end

#remote_set_branches(name, *branches, add: false)

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.

Configures which branches are fetched for a remote

Uses git remote set-branches to set or append fetch refspecs. When the add: option is false, the --add flag is not passed to the git command and the tracked branch list is replaced.

Examples:

Replace fetched branches with a single glob pattern

repo.remote_set_branches('origin', 'feature/*')

Append a glob pattern to existing fetched branches

repo.remote_set_branches('origin', 'release/*', add: true)

Configure multiple explicit branches

repo.remote_set_branches('origin', 'main', 'development', 'hotfix')

Parameters:

  • name (String) —

    the remote name (for example, "origin")

  • branches (Array<String>) —

    branch names or globs (for example, '*')

  • add (Boolean) (defaults to: false) —

    when true, append to existing refspecs instead of replacing them

Raises:

  • (ArgumentError) —

    when no branches are provided

  • (Git::FailedError) —

    when git exits with a non-zero status



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

def remote_set_branches(name, *branches, add: false)
  branch_list = branches.flatten
  raise ArgumentError, 'branches are required' if branch_list.empty?

  Git::Commands::Remote::SetBranches.new(@execution_context).call(name, *branch_list, add: add)

  nil
end

#remote_set_url(name, url) ⇒ Git::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.

Sets the URL for an existing remote

Replaces the fetch URL configured for the remote named name.

Examples:

Set the URL for a remote

repo.remote_set_url('origin', 'https://github.com/user/repo.git')

Set the URL from a local repository reference

source = Git.open('/path/to/source')
repo.remote_set_url('origin', source)

Parameters:

  • name (String) —

    the name of the remote to update

  • url (String, Git::Repository) —

    the new URL for the remote

    A Git::Repository instance is accepted for local references and converted to url.repo.to_s.

Returns:

Raises:



438
439
440
441
442
443
 
# File 'lib/git/repository/remote_operations.rb', line 438

def remote_set_url(name, url)
  url = url.repo.to_s if url.is_a?(Git::Repository)
  Git::Commands::Remote::SetUrl.new(@execution_context).call(name, url)

  Git::Remote.new(self, name)
end

#remotes ⇒ Array<Git::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.

Returns all configured remotes as Git::Remote objects

Examples:

List all remotes

repo.remotes  #=> [#<Git::Remote 'origin'>, #<Git::Remote 'upstream'>]

Returns:

  • (Array<Git::Remote>) —

    one Git::Remote for each configured remote

    Returns an empty array when no remotes are configured.

Raises:



561
562
563
564
 
# File 'lib/git/repository/remote_operations.rb', line 561

def remotes
  result = Git::Commands::Remote::List.new(@execution_context).call
  result.stdout.split("\n").map { |name| Git::Remote.new(self, name) }
end

#remove_remote(name) ⇒ 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.

Deprecated.

Use #remote_remove instead

Returns the result of calling git remote remove.

Parameters:

  • name (String) —

    the name of the remote to remove

Returns:

Raises:



408
409
410
411
412
413
414
 
# File 'lib/git/repository/remote_operations.rb', line 408

def remove_remote(name)
  Git::Deprecation.warn(
    'Git::Repository#remove_remote is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#remote_remove instead.'
  )
  remote_remove(name)
end

#set_remote_url(name, url) ⇒ Git::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.

Deprecated.

Use #remote_set_url instead

Returns the updated remote.

Parameters:

  • name (String) —

    the name of the remote to update

  • url (String, Git::Repository) —

    the new URL for the remote

    A Git::Repository instance is accepted for local references and converted to url.repo.to_s.

Returns:

Raises:



458
459
460
461
462
463
464
 
# File 'lib/git/repository/remote_operations.rb', line 458

def set_remote_url(name, url)
  Git::Deprecation.warn(
    'Git::Repository#set_remote_url is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#remote_set_url instead.'
  )
  remote_set_url(name, url)
end