man1/git-remote.1

   1 '\" t
   2 .\"     Title: git-remote
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-08-21
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.46.0.288.g3a7362eb9f
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-REMOTE" "1" "2024-08-21" "Git 2\&.46\&.0\&.288\&.g3a7362" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-remote \- Manage set of tracked repositories
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit remote\fR [\-v | \-\-verbose]
  36 \fIgit remote add\fR [\-t <branch>] [\-m <master>] [\-f] [\-\-[no\-]tags] [\-\-mirror=(fetch|push)] <name> <URL>
  37 \fIgit remote rename\fR [\-\-[no\-]progress] <old> <new>
  38 \fIgit remote remove\fR <name>
  39 \fIgit remote set\-head\fR <name> (\-a | \-\-auto | \-d | \-\-delete | <branch>)
  40 \fIgit remote set\-branches\fR [\-\-add] <name> <branch>\&...\:
  41 \fIgit remote get\-url\fR [\-\-push] [\-\-all] <name>
  42 \fIgit remote set\-url\fR [\-\-push] <name> <newurl> [<oldurl>]
  43 \fIgit remote set\-url \-\-add\fR [\-\-push] <name> <newurl>
  44 \fIgit remote set\-url \-\-delete\fR [\-\-push] <name> <URL>
  45 \fIgit remote\fR [\-v | \-\-verbose] \fIshow\fR [\-n] <name>\&...\:
  46 \fIgit remote prune\fR [\-n | \-\-dry\-run] <name>\&...\:
  47 \fIgit remote\fR [\-v | \-\-verbose] \fIupdate\fR [\-p | \-\-prune] [(<group> | <remote>)\&...\:]
  48 .fi
  49 .SH "DESCRIPTION"
  50 .sp
  51 Manage the set of repositories ("remotes") whose branches you track\&.
  52 .SH "OPTIONS"
  53 .PP
  54 \-v, \-\-verbose
  55 .RS 4
  56 Be a little more verbose and show remote url after name\&. For promisor remotes, also show which filters (\fBblob:none\fR
  57 etc\&.) are configured\&. NOTE: This must be placed between
  58 \fBremote\fR
  59 and subcommand\&.
  60 .RE
  61 .SH "COMMANDS"
  62 .sp
  63 With no arguments, shows a list of existing remotes\&. Several subcommands are available to perform operations on the remotes\&.
  64 .PP
  65 \fIadd\fR
  66 .RS 4
  67 Add a remote named <name> for the repository at <URL>\&. The command
  68 \fBgit fetch <name>\fR
  69 can then be used to create and update remote\-tracking branches <name>/<branch>\&.
  70 .sp
  71 With
  72 \fB\-f\fR
  73 option,
  74 \fBgit fetch <name>\fR
  75 is run immediately after the remote information is set up\&.
  76 .sp
  77 With
  78 \fB\-\-tags\fR
  79 option,
  80 \fBgit fetch <name>\fR
  81 imports every tag from the remote repository\&.
  82 .sp
  83 With
  84 \fB\-\-no\-tags\fR
  85 option,
  86 \fBgit fetch <name>\fR
  87 does not import tags from the remote repository\&.
  88 .sp
  89 By default, only tags on fetched branches are imported (see
  90 \fBgit-fetch\fR(1))\&.
  91 .sp
  92 With
  93 \fB\-t <branch>\fR
  94 option, instead of the default glob refspec for the remote to track all branches under the
  95 \fBrefs/remotes/<name>/\fR
  96 namespace, a refspec to track only
  97 \fB<branch>\fR
  98 is created\&. You can give more than one
  99 \fB\-t <branch>\fR
 100 to track multiple branches without grabbing all branches\&.
 101 .sp
 102 With
 103 \fB\-m <master>\fR
 104 option, a symbolic\-ref
 105 \fBrefs/remotes/<name>/HEAD\fR
 106 is set up to point at remote\(cqs
 107 \fB<master>\fR
 108 branch\&. See also the set\-head command\&.
 109 .sp
 110 When a fetch mirror is created with
 111 \fB\-\-mirror=fetch\fR, the refs will not be stored in the
 112 \fIrefs/remotes/\fR
 113 namespace, but rather everything in
 114 \fIrefs/\fR
 115 on the remote will be directly mirrored into
 116 \fIrefs/\fR
 117 in the local repository\&. This option only makes sense in bare repositories, because a fetch would overwrite any local commits\&.
 118 .sp
 119 When a push mirror is created with
 120 \fB\-\-mirror=push\fR, then
 121 \fBgit push\fR
 122 will always behave as if
 123 \fB\-\-mirror\fR
 124 was passed\&.
 125 .RE
 126 .PP
 127 \fIrename\fR
 128 .RS 4
 129 Rename the remote named <old> to <new>\&. All remote\-tracking branches and configuration settings for the remote are updated\&.
 130 .sp
 131 In case <old> and <new> are the same, and <old> is a file under
 132 \fB$GIT_DIR/remotes\fR
 133 or
 134 \fB$GIT_DIR/branches\fR, the remote is converted to the configuration file format\&.
 135 .RE
 136 .PP
 137 \fIremove\fR, \fIrm\fR
 138 .RS 4
 139 Remove the remote named <name>\&. All remote\-tracking branches and configuration settings for the remote are removed\&.
 140 .RE
 141 .PP
 142 \fIset\-head\fR
 143 .RS 4
 144 Sets or deletes the default branch (i\&.e\&. the target of the symbolic\-ref
 145 \fBrefs/remotes/<name>/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
 146 \fBorigin\fR
 147 is set to
 148 \fBmaster\fR, then
 149 \fBorigin\fR
 150 may be specified wherever you would normally specify
 151 \fBorigin/master\fR\&.
 152 .sp
 153 With
 154 \fB\-d\fR
 155 or
 156 \fB\-\-delete\fR, the symbolic ref
 157 \fBrefs/remotes/<name>/HEAD\fR
 158 is deleted\&.
 159 .sp
 160 With
 161 \fB\-a\fR
 162 or
 163 \fB\-\-auto\fR, the remote is queried to determine its
 164 \fBHEAD\fR, then the symbolic\-ref
 165 \fBrefs/remotes/<name>/HEAD\fR
 166 is set to the same branch\&. e\&.g\&., if the remote
 167 \fBHEAD\fR
 168 is pointed at
 169 \fBnext\fR,
 170 \fBgit remote set\-head origin \-a\fR
 171 will set the symbolic\-ref
 172 \fBrefs/remotes/origin/HEAD\fR
 173 to
 174 \fBrefs/remotes/origin/next\fR\&. This will only work if
 175 \fBrefs/remotes/origin/next\fR
 176 already exists; if not it must be fetched first\&.
 177 .sp
 178 Use
 179 \fB<branch>\fR
 180 to set the symbolic\-ref
 181 \fBrefs/remotes/<name>/HEAD\fR
 182 explicitly\&. e\&.g\&.,
 183 \fBgit remote set\-head origin master\fR
 184 will set the symbolic\-ref
 185 \fBrefs/remotes/origin/HEAD\fR
 186 to
 187 \fBrefs/remotes/origin/master\fR\&. This will only work if
 188 \fBrefs/remotes/origin/master\fR
 189 already exists; if not it must be fetched first\&.
 190 .RE
 191 .PP
 192 \fIset\-branches\fR
 193 .RS 4
 194 Changes 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\&.
 195 .sp
 196 The named branches will be interpreted as if specified with the
 197 \fB\-t\fR
 198 option on the
 199 \fBgit remote add\fR
 200 command line\&.
 201 .sp
 202 With
 203 \fB\-\-add\fR, instead of replacing the list of currently tracked branches, adds to that list\&.
 204 .RE
 205 .PP
 206 \fIget\-url\fR
 207 .RS 4
 208 Retrieves the URLs for a remote\&. Configurations for
 209 \fBinsteadOf\fR
 210 and
 211 \fBpushInsteadOf\fR
 212 are expanded here\&. By default, only the first URL is listed\&.
 213 .sp
 214 With
 215 \fB\-\-push\fR, push URLs are queried rather than fetch URLs\&.
 216 .sp
 217 With
 218 \fB\-\-all\fR, all URLs for the remote will be listed\&.
 219 .RE
 220 .PP
 221 \fIset\-url\fR
 222 .RS 4
 223 Changes URLs for the remote\&. Sets first URL for remote <name> that matches regex <oldurl> (first URL if no <oldurl> is given) to <newurl>\&. If <oldurl> doesn\(cqt match any URL, an error occurs and nothing is changed\&.
 224 .sp
 225 With
 226 \fB\-\-push\fR, push URLs are manipulated instead of fetch URLs\&.
 227 .sp
 228 With
 229 \fB\-\-add\fR, instead of changing existing URLs, new URL is added\&.
 230 .sp
 231 With
 232 \fB\-\-delete\fR, instead of changing existing URLs, all URLs matching regex <URL> are deleted for remote <name>\&. Trying to delete all non\-push URLs is an error\&.
 233 .sp
 234 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\&.
 235 .RE
 236 .PP
 237 \fIshow\fR
 238 .RS 4
 239 Gives some information about the remote <name>\&.
 240 .sp
 241 With
 242 \fB\-n\fR
 243 option, the remote heads are not queried first with
 244 \fBgit ls\-remote <name>\fR; cached information is used instead\&.
 245 .RE
 246 .PP
 247 \fIprune\fR
 248 .RS 4
 249 Deletes stale references associated with <name>\&. By default, stale remote\-tracking branches under <name> 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
 250 \fBgit fetch \-\-prune <name>\fR, except that no new references will be fetched\&.
 251 .sp
 252 See the PRUNING section of
 253 \fBgit-fetch\fR(1)
 254 for what it\(cqll prune depending on various configuration\&.
 255 .sp
 256 With
 257 \fB\-\-dry\-run\fR
 258 option, report what branches would be pruned, but do not actually prune them\&.
 259 .RE
 260 .PP
 261 \fIupdate\fR
 262 .RS 4
 263 Fetch updates for remotes or remote groups in the repository as defined by
 264 \fBremotes\&.<group>\fR\&. If neither group nor remote is specified on the command line, the configuration parameter remotes\&.default will be used; if remotes\&.default is not defined, all remotes which do not have the configuration parameter
 265 \fBremote\&.<name>\&.skipDefaultUpdate\fR
 266 set to true will be updated\&. (See
 267 \fBgit-config\fR(1))\&.
 268 .sp
 269 With
 270 \fB\-\-prune\fR
 271 option, run pruning against all the remotes that are updated\&.
 272 .RE
 273 .SH "DISCUSSION"
 274 .sp
 275 The remote configuration is achieved using the \fBremote\&.origin\&.url\fR and \fBremote\&.origin\&.fetch\fR configuration variables\&. (See \fBgit-config\fR(1))\&.
 276 .SH "EXIT STATUS"
 277 .sp
 278 On success, the exit status is \fB0\fR\&.
 279 .sp
 280 When subcommands such as \fIadd\fR, \fIrename\fR, and \fIremove\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\&.
 281 .sp
 282 On any other error, the exit status may be any other non\-zero value\&.
 283 .SH "EXAMPLES"
 284 .sp
 285 .RS 4
 286 .ie n \{\
 287 \h'-04'\(bu\h'+03'\c
 288 .\}
 289 .el \{\
 290 .sp -1
 291 .IP \(bu 2.3
 292 .\}
 293 Add a new remote, fetch, and check out a branch from it
 294 .sp
 295 .if n \{\
 296 .RS 4
 297 .\}
 298 .nf
 299 $ git remote
 300 origin
 301 $ git branch \-r
 302   origin/HEAD \-> origin/master
 303   origin/master
 304 $ git remote add staging git://git\&.kernel\&.org/\&.\&.\&./gregkh/staging\&.git
 305 $ git remote
 306 origin
 307 staging
 308 $ git fetch staging
 309 \&.\&.\&.
 310 From git://git\&.kernel\&.org/pub/scm/linux/kernel/git/gregkh/staging
 311  * [new branch]      master     \-> staging/master
 312  * [new branch]      staging\-linus \-> staging/staging\-linus
 313  * [new branch]      staging\-next \-> staging/staging\-next
 314 $ git branch \-r
 315   origin/HEAD \-> origin/master
 316   origin/master
 317   staging/master
 318   staging/staging\-linus
 319   staging/staging\-next
 320 $ git switch \-c staging staging/master
 321 \&.\&.\&.
 322 .fi
 323 .if n \{\
 324 .RE
 325 .\}
 326 .RE
 327 .sp
 328 .RS 4
 329 .ie n \{\
 330 \h'-04'\(bu\h'+03'\c
 331 .\}
 332 .el \{\
 333 .sp -1
 334 .IP \(bu 2.3
 335 .\}
 336 Imitate
 337 \fIgit clone\fR
 338 but track only selected branches
 339 .sp
 340 .if n \{\
 341 .RS 4
 342 .\}
 343 .nf
 344 $ mkdir project\&.git
 345 $ cd project\&.git
 346 $ git init
 347 $ git remote add \-f \-t master \-m master origin git://example\&.com/git\&.git/
 348 $ git merge origin
 349 .fi
 350 .if n \{\
 351 .RE
 352 .\}
 353 .RE
 354 .SH "SEE ALSO"
 355 .sp
 356 \fBgit-fetch\fR(1) \fBgit-branch\fR(1) \fBgit-config\fR(1)
 357 .SH "GIT"
 358 .sp
 359 Part of the \fBgit\fR(1) suite