'\" t
.\"     Title: git-remote
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2026-02-01
.\"    Manual: Git Manual
.\"    Source: Git 2.53.0
.\"  Language: English
.\"
.TH "GIT\-REMOTE" "1" "2026\-02\-01" "Git 2\&.53\&.0" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-remote \- Manage set of tracked repositories
.SH "SYNOPSIS"
.sp
.nf
\fBgit\fR \fBremote\fR [\fB\-v\fR | \fB\-\-verbose\fR]
\fBgit\fR \fBremote\fR \fBadd\fR [\fB\-t\fR \fI<branch>\fR] [\fB\-m\fR \fI<master>\fR] [\fB\-f\fR] [\fB\-\-\fR[\fBno\-\fR]\fBtags\fR] [\fB\-\-mirror=\fR(\fBfetch\fR|\fBpush\fR)] \fI<name>\fR \fI<URL>\fR
\fBgit\fR \fBremote\fR \fBrename\fR [\fB\-\-\fR[\fBno\-\fR]\fBprogress\fR] \fI<old>\fR \fI<new>\fR
\fBgit\fR \fBremote\fR \fBremove\fR \fI<name>\fR
\fBgit\fR \fBremote\fR \fBset\-head\fR \fI<name>\fR (\fB\-a\fR | \fB\-\-auto\fR | \fB\-d\fR | \fB\-\-delete\fR | \fI<branch>\fR)
\fBgit\fR \fBremote\fR \fBset\-branches\fR [\fB\-\-add\fR] \fI<name>\fR \fI<branch>\fR\&...
\fBgit\fR \fBremote\fR \fBget\-url\fR [\fB\-\-push\fR] [\fB\-\-all\fR] \fI<name>\fR
\fBgit\fR \fBremote\fR \fBset\-url\fR [\fB\-\-push\fR] \fI<name>\fR \fI<newurl>\fR [\fI<oldurl>\fR]
\fBgit\fR \fBremote\fR \fBset\-url\fR \fB\-\-add\fR [\fB\-\-push\fR] \fI<name>\fR \fI<newurl>\fR
\fBgit\fR \fBremote\fR \fBset\-url\fR \fB\-\-delete\fR [\fB\-\-push\fR] \fI<name>\fR \fI<URL>\fR
\fBgit\fR \fBremote\fR [\fB\-v\fR | \fB\-\-verbose\fR] \fBshow\fR [\fB\-n\fR] \fI<name>\fR\&...
\fBgit\fR \fBremote\fR \fBprune\fR [\fB\-n\fR | \fB\-\-dry\-run\fR] \fI<name>\fR\&...
\fBgit\fR \fBremote\fR [\fB\-v\fR | \fB\-\-verbose\fR] \fBupdate\fR [\fB\-p\fR | \fB\-\-prune\fR] [(\fI<group>\fR | \fI<remote>\fR)\&...]
.fi
.sp
.SH "DESCRIPTION"
.sp
Manage the set of repositories ("remotes") whose branches you track\&.
.SH "OPTIONS"
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Be a little more verbose and show remote url after name\&. For promisor remotes, also show which filters (\fBblob:none\fR
etc\&.) are configured\&. NOTE: This must be placed between
\fBremote\fR
and subcommand\&.
.RE
.SH "COMMANDS"
.sp
With no arguments, show a list of existing remotes\&. Several subcommands are available to perform operations on the remotes\&.
.PP
\fBadd\fR
.RS 4
Add a remote named
\fI<name>\fR
for the repository at
\fI<URL>\fR\&. The command
\fBgit\fR
\fBfetch\fR
\fI<name>\fR
can then be used to create and update remote\-tracking branches
\fI<name>\fR\fB/\fR\fI<branch>\fR\&.
.sp
With
\fB\-f\fR
option,
\fBgit\fR
\fBfetch\fR
\fI<name>\fR
is run immediately after the remote information is set up\&.
.sp
With
\fB\-\-tags\fR
option,
\fBgit\fR
\fBfetch\fR
\fI<name>\fR
imports every tag from the remote repository\&.
.sp
With
\fB\-\-no\-tags\fR
option,
\fBgit\fR
\fBfetch\fR
\fI<name>\fR
does not import tags from the remote repository\&.
.sp
By default, only tags on fetched branches are imported (see
\fBgit-fetch\fR(1))\&.
.sp
With
\fB\-t\fR
\fI<branch>\fR
option, instead of the default glob refspec for the remote to track all branches under the
\fBrefs/remotes/\fR\fI<name>\fR\fB/\fR
namespace, a refspec to track only
\fI<branch>\fR
is created\&. You can give more than one
\fB\-t\fR
\fI<branch>\fR
to track multiple branches without grabbing all branches\&.
.sp
With
\fB\-m\fR
\fI<master>\fR
option, a symbolic\-ref
\fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR
is set up to point at remote\(cqs
\fI<master>\fR
branch\&. See also the set\-head command\&.
.sp
When a fetch mirror is created with
\fB\-\-mirror=fetch\fR, the refs will not be stored in the
\fBrefs/remotes/\fR
namespace, but rather everything in
\fBrefs/\fR
on the remote will be directly mirrored into
\fBrefs/\fR
in the local repository\&. This option only makes sense in bare repositories, because a fetch would overwrite any local commits\&.
.sp
When a push mirror is created with
\fB\-\-mirror=push\fR, then
\fBgit\fR
\fBpush\fR
will always behave as if
\fB\-\-mirror\fR
was passed\&.
.RE
.PP
\fBrename\fR
.RS 4
Rename the remote named
\fI<old>\fR
to
\fI<new>\fR\&. All remote\-tracking branches and configuration settings for the remote are updated\&.
.sp
In case
\fI<old>\fR
and
\fI<new>\fR
are the same, and
\fI<old>\fR
is a file under
\fB$GIT_DIR/remotes\fR
or
\fB$GIT_DIR/branches\fR, the remote is converted to the configuration file format\&.
.RE
.PP
\fBremove\fR, \fBrm\fR
.RS 4
Remove the remote named
\fI<name>\fR\&. All remote\-tracking branches and configuration settings for the remote are removed\&.
.RE
.PP
\fBset\-head\fR
.RS 4
Set or delete the default branch (i\&.e\&. the target of the symbolic\-ref
\fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR) for the named remote\&. Having a default branch for a remote is not required, but allows the name of the remote to be specified in lieu of a specific branch\&. For example, if the default branch for
\fBorigin\fR
is set to
\fBmaster\fR, then
\fBorigin\fR
may be specified wherever you would normally specify
\fBorigin/master\fR\&.
.sp
With
\fB\-d\fR
or
\fB\-\-delete\fR, the symbolic ref
\fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR
is deleted\&.
.sp
With
\fB\-a\fR
or
\fB\-\-auto\fR, the remote is queried to determine its
\fBHEAD\fR, then the symbolic\-ref
\fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR
is set to the same branch\&. e\&.g\&., if the remote
\fBHEAD\fR
is pointed at
\fBnext\fR,
\fBgit\fR
\fBremote\fR
\fBset\-head\fR
\fBorigin\fR
\fB\-a\fR
will set the symbolic\-ref
\fBrefs/remotes/origin/HEAD\fR
to
\fBrefs/remotes/origin/next\fR\&. This will only work if
\fBrefs/remotes/origin/next\fR
already exists; if not it must be fetched first\&.
.sp
Use
\fI<branch>\fR
to set the symbolic\-ref
\fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR
explicitly\&. e\&.g\&.,
\fBgit\fR
\fBremote\fR
\fBset\-head\fR
\fBorigin\fR
\fBmaster\fR
will set the symbolic\-ref
\fBrefs/remotes/origin/HEAD\fR
to
\fBrefs/remotes/origin/master\fR\&. This will only work if
\fBrefs/remotes/origin/master\fR
already exists; if not it must be fetched first\&.
.RE
.PP
\fBset\-branches\fR
.RS 4
Change the list of branches tracked by the named remote\&. This can be used to track a subset of the available remote branches after the initial setup for a remote\&.
.sp
The named branches will be interpreted as if specified with the
\fB\-t\fR
option on the
\fBgit\fR
\fBremote\fR
\fBadd\fR
command line\&.
.sp
With
\fB\-\-add\fR, instead of replacing the list of currently tracked branches, adds to that list\&.
.RE
.PP
\fBget\-url\fR
.RS 4
Retrieves the URLs for a remote\&. Configurations for
\fBinsteadOf\fR
and
\fBpushInsteadOf\fR
are expanded here\&. By default, only the first URL is listed\&.
.sp
With
\fB\-\-push\fR, push URLs are queried rather than fetch URLs\&.
.sp
With
\fB\-\-all\fR, all URLs for the remote will be listed\&.
.RE
.PP
\fBset\-url\fR
.RS 4
Change URLs for the remote\&. Sets first URL for remote
\fI<name>\fR
that matches regex
\fI<oldurl>\fR
(first URL if no
\fI<oldurl>\fR
is given) to
\fI<newurl>\fR\&. If
\fI<oldurl>\fR
doesn\(cqt match any URL, an error occurs and nothing is changed\&.
.sp
With
\fB\-\-push\fR, push URLs are manipulated instead of fetch URLs\&.
.sp
With
\fB\-\-add\fR, instead of changing existing URLs, new URL is added\&.
.sp
With
\fB\-\-delete\fR, instead of changing existing URLs, all URLs matching regex
\fI<URL>\fR
are deleted for remote
\fI<name>\fR\&. Trying to delete all non\-push URLs is an error\&.
.sp
Note that the push URL and the fetch URL, even though they can be set differently, must still refer to the same place\&. What you pushed to the push URL should be what you would see if you immediately fetched from the fetch URL\&. If you are trying to fetch from one place (e\&.g\&. your upstream) and push to another (e\&.g\&. your publishing repository), use two separate remotes\&.
.RE
.PP
\fBshow\fR
.RS 4
Give some information about the remote
\fI<name>\fR\&.
.sp
With
\fB\-n\fR
option, the remote heads are not queried first with
\fBgit\fR
\fBls\-remote\fR
\fI<name>\fR; cached information is used instead\&.
.RE
.PP
\fBprune\fR
.RS 4
Delete stale references associated with
\fI<name>\fR\&. By default, stale remote\-tracking branches under
\fI<name>\fR
are deleted, but depending on global configuration and the configuration of the remote we might even prune local tags that haven\(cqt been pushed there\&. Equivalent to
\fBgit\fR
\fBfetch\fR
\fB\-\-prune\fR
\fI<name>\fR, except that no new references will be fetched\&.
.sp
See the PRUNING section of
\fBgit-fetch\fR(1)
for what it\(cqll prune depending on various configuration\&.
.sp
With
\fB\-\-dry\-run\fR
option, report what branches would be pruned, but do not actually prune them\&.
.RE
.PP
\fBupdate\fR
.RS 4
Fetch updates for remotes or remote groups in the repository as defined by
\fBremotes\&.\fR\fI<group>\fR\&. If neither group nor remote is specified on the command line, the configuration parameter
\fBremotes\&.default\fR
will be used; if
\fBremotes\&.default\fR
is not defined, all remotes which do not have the configuration parameter
\fBremote\&.\fR\fI<name>\fR\fB\&.skipDefaultUpdate\fR
set to
\fBtrue\fR
will be updated\&. (See
\fBgit-config\fR(1))\&.
.sp
With
\fB\-\-prune\fR
option, run pruning against all the remotes that are updated\&.
.RE
.SH "DISCUSSION"
.sp
The remote configuration is achieved using the \fBremote\&.origin\&.url\fR and \fBremote\&.origin\&.fetch\fR configuration variables\&. (See \fBgit-config\fR(1))\&.
.SH "EXIT STATUS"
.sp
On success, the exit status is \fB0\fR\&.
.sp
When subcommands such as \fBadd\fR, \fBrename\fR, and \fBremove\fR can\(cqt find the remote in question, the exit status is \fB2\fR\&. When the remote already exists, the exit status is \fB3\fR\&.
.sp
On any other error, the exit status may be any other non\-zero value\&.
.SH "EXAMPLES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Add a new remote, fetch, and check out a branch from it
.sp
.if n \{\
.RS 4
.\}
.nf
$ git remote
origin
$ git branch \-r
  origin/HEAD \-> origin/master
  origin/master
$ git remote add staging git://git\&.kernel\&.org/\&.\&.\&./gregkh/staging\&.git
$ git remote
origin
staging
$ git fetch staging
\&.\&.\&.
From git://git\&.kernel\&.org/pub/scm/linux/kernel/git/gregkh/staging
 * [new branch]      master     \-> staging/master
 * [new branch]      staging\-linus \-> staging/staging\-linus
 * [new branch]      staging\-next \-> staging/staging\-next
$ git branch \-r
  origin/HEAD \-> origin/master
  origin/master
  staging/master
  staging/staging\-linus
  staging/staging\-next
$ git switch \-c staging staging/master
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Imitate
\fBgit\fR
\fBclone\fR
but track only selected branches
.sp
.if n \{\
.RS 4
.\}
.nf
$ mkdir project\&.git
$ cd project\&.git
$ git init
$ git remote add \-f \-t master \-m master origin git://example\&.com/git\&.git/
$ git merge origin
.fi
.if n \{\
.RE
.\}
.sp
.RE
.SH "SEE ALSO"
.sp
\fBgit-fetch\fR(1) \fBgit-branch\fR(1) \fBgit-config\fR(1)
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite