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-11-20
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.47.0.305.g4083a6f052
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-REMOTE" "1" "2024-11-20" "Git 2\&.47\&.0\&.305\&.g4083a6" "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\fR
  69 \fBfetch\fR
  70 \fI<name>\fR
  71 can then be used to create and update remote\-tracking branches <name>/<branch>\&.
  72 .sp
  73 With
  74 \fB\-f\fR
  75 option,
  76 \fBgit\fR
  77 \fBfetch\fR
  78 \fI<name>\fR
  79 is run immediately after the remote information is set up\&.
  80 .sp
  81 With
  82 \fB\-\-tags\fR
  83 option,
  84 \fBgit\fR
  85 \fBfetch\fR
  86 \fI<name>\fR
  87 imports every tag from the remote repository\&.
  88 .sp
  89 With
  90 \fB\-\-no\-tags\fR
  91 option,
  92 \fBgit\fR
  93 \fBfetch\fR
  94 \fI<name>\fR
  95 does not import tags from the remote repository\&.
  96 .sp
  97 By default, only tags on fetched branches are imported (see
  98 \fBgit-fetch\fR(1))\&.
  99 .sp
 100 With
 101 \fB\-t\fR
 102 \fI<branch>\fR
 103 option, instead of the default glob refspec for the remote to track all branches under the
 104 \fBrefs/remotes/\fR\fI<name>\fR\fB/\fR
 105 namespace, a refspec to track only
 106 \fI<branch>\fR
 107 is created\&. You can give more than one
 108 \fB\-t\fR
 109 \fI<branch>\fR
 110 to track multiple branches without grabbing all branches\&.
 111 .sp
 112 With
 113 \fB\-m\fR
 114 \fI<master>\fR
 115 option, a symbolic\-ref
 116 \fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR
 117 is set up to point at remote\(cqs
 118 \fI<master>\fR
 119 branch\&. See also the set\-head command\&.
 120 .sp
 121 When a fetch mirror is created with
 122 \fB\-\-mirror=fetch\fR, the refs will not be stored in the
 123 \fIrefs/remotes/\fR
 124 namespace, but rather everything in
 125 \fIrefs/\fR
 126 on the remote will be directly mirrored into
 127 \fIrefs/\fR
 128 in the local repository\&. This option only makes sense in bare repositories, because a fetch would overwrite any local commits\&.
 129 .sp
 130 When a push mirror is created with
 131 \fB\-\-mirror=push\fR, then
 132 \fBgit\fR
 133 \fBpush\fR
 134 will always behave as if
 135 \fB\-\-mirror\fR
 136 was passed\&.
 137 .RE
 138 .PP
 139 \fIrename\fR
 140 .RS 4
 141 Rename the remote named <old> to <new>\&. All remote\-tracking branches and configuration settings for the remote are updated\&.
 142 .sp
 143 In case <old> and <new> are the same, and <old> is a file under
 144 \fB$GIT_DIR/remotes\fR
 145 or
 146 \fB$GIT_DIR/branches\fR, the remote is converted to the configuration file format\&.
 147 .RE
 148 .PP
 149 \fIremove\fR, \fIrm\fR
 150 .RS 4
 151 Remove the remote named <name>\&. All remote\-tracking branches and configuration settings for the remote are removed\&.
 152 .RE
 153 .PP
 154 \fIset\-head\fR
 155 .RS 4
 156 Sets or deletes the default branch (i\&.e\&. the target of the symbolic\-ref
 157 \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
 158 \fBorigin\fR
 159 is set to
 160 \fBmaster\fR, then
 161 \fBorigin\fR
 162 may be specified wherever you would normally specify
 163 \fBorigin/master\fR\&.
 164 .sp
 165 With
 166 \fB\-d\fR
 167 or
 168 \fB\-\-delete\fR, the symbolic ref
 169 \fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR
 170 is deleted\&.
 171 .sp
 172 With
 173 \fB\-a\fR
 174 or
 175 \fB\-\-auto\fR, the remote is queried to determine its
 176 \fBHEAD\fR, then the symbolic\-ref
 177 \fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR
 178 is set to the same branch\&. e\&.g\&., if the remote
 179 \fBHEAD\fR
 180 is pointed at
 181 \fBnext\fR,
 182 \fBgit\fR
 183 \fBremote\fR
 184 \fBset\-head\fR
 185 \fBorigin\fR
 186 \fB\-a\fR
 187 will set the symbolic\-ref
 188 \fBrefs/remotes/origin/HEAD\fR
 189 to
 190 \fBrefs/remotes/origin/next\fR\&. This will only work if
 191 \fBrefs/remotes/origin/next\fR
 192 already exists; if not it must be fetched first\&.
 193 .sp
 194 Use
 195 \fI<branch>\fR
 196 to set the symbolic\-ref
 197 \fBrefs/remotes/\fR\fI<name>\fR\fB/HEAD\fR
 198 explicitly\&. e\&.g\&.,
 199 \fBgit\fR
 200 \fBremote\fR
 201 \fBset\-head\fR
 202 \fBorigin\fR
 203 \fBmaster\fR
 204 will set the symbolic\-ref
 205 \fBrefs/remotes/origin/HEAD\fR
 206 to
 207 \fBrefs/remotes/origin/master\fR\&. This will only work if
 208 \fBrefs/remotes/origin/master\fR
 209 already exists; if not it must be fetched first\&.
 210 .RE
 211 .PP
 212 \fIset\-branches\fR
 213 .RS 4
 214 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\&.
 215 .sp
 216 The named branches will be interpreted as if specified with the
 217 \fB\-t\fR
 218 option on the
 219 \fBgit\fR
 220 \fBremote\fR
 221 \fBadd\fR
 222 command line\&.
 223 .sp
 224 With
 225 \fB\-\-add\fR, instead of replacing the list of currently tracked branches, adds to that list\&.
 226 .RE
 227 .PP
 228 \fIget\-url\fR
 229 .RS 4
 230 Retrieves the URLs for a remote\&. Configurations for
 231 \fBinsteadOf\fR
 232 and
 233 \fBpushInsteadOf\fR
 234 are expanded here\&. By default, only the first URL is listed\&.
 235 .sp
 236 With
 237 \fB\-\-push\fR, push URLs are queried rather than fetch URLs\&.
 238 .sp
 239 With
 240 \fB\-\-all\fR, all URLs for the remote will be listed\&.
 241 .RE
 242 .PP
 243 \fIset\-url\fR
 244 .RS 4
 245 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\&.
 246 .sp
 247 With
 248 \fB\-\-push\fR, push URLs are manipulated instead of fetch URLs\&.
 249 .sp
 250 With
 251 \fB\-\-add\fR, instead of changing existing URLs, new URL is added\&.
 252 .sp
 253 With
 254 \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\&.
 255 .sp
 256 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\&.
 257 .RE
 258 .PP
 259 \fIshow\fR
 260 .RS 4
 261 Gives some information about the remote <name>\&.
 262 .sp
 263 With
 264 \fB\-n\fR
 265 option, the remote heads are not queried first with
 266 \fBgit\fR
 267 \fBls\-remote\fR
 268 \fI<name>\fR; cached information is used instead\&.
 269 .RE
 270 .PP
 271 \fIprune\fR
 272 .RS 4
 273 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
 274 \fBgit\fR
 275 \fBfetch\fR
 276 \fB\-\-prune\fR
 277 \fI<name>\fR, except that no new references will be fetched\&.
 278 .sp
 279 See the PRUNING section of
 280 \fBgit-fetch\fR(1)
 281 for what it\(cqll prune depending on various configuration\&.
 282 .sp
 283 With
 284 \fB\-\-dry\-run\fR
 285 option, report what branches would be pruned, but do not actually prune them\&.
 286 .RE
 287 .PP
 288 \fIupdate\fR
 289 .RS 4
 290 Fetch updates for remotes or remote groups in the repository as defined by
 291 \fBremotes\&.\fR\fI<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
 292 \fBremote\&.\fR\fI<name>\fR\fB\&.skipDefaultUpdate\fR
 293 set to true will be updated\&. (See
 294 \fBgit-config\fR(1))\&.
 295 .sp
 296 With
 297 \fB\-\-prune\fR
 298 option, run pruning against all the remotes that are updated\&.
 299 .RE
 300 .SH "DISCUSSION"
 301 .sp
 302 The remote configuration is achieved using the \fBremote\&.origin\&.url\fR and \fBremote\&.origin\&.fetch\fR configuration variables\&. (See \fBgit-config\fR(1))\&.
 303 .SH "EXIT STATUS"
 304 .sp
 305 On success, the exit status is \fB0\fR\&.
 306 .sp
 307 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\&.
 308 .sp
 309 On any other error, the exit status may be any other non\-zero value\&.
 310 .SH "EXAMPLES"
 311 .sp
 312 .RS 4
 313 .ie n \{\
 314 \h'-04'\(bu\h'+03'\c
 315 .\}
 316 .el \{\
 317 .sp -1
 318 .IP \(bu 2.3
 319 .\}
 320 Add a new remote, fetch, and check out a branch from it
 321 .sp
 322 .if n \{\
 323 .RS 4
 324 .\}
 325 .nf
 326 $ git remote
 327 origin
 328 $ git branch \-r
 329   origin/HEAD \-> origin/master
 330   origin/master
 331 $ git remote add staging git://git\&.kernel\&.org/\&.\&.\&./gregkh/staging\&.git
 332 $ git remote
 333 origin
 334 staging
 335 $ git fetch staging
 336 \&.\&.\&.
 337 From git://git\&.kernel\&.org/pub/scm/linux/kernel/git/gregkh/staging
 338  * [new branch]      master     \-> staging/master
 339  * [new branch]      staging\-linus \-> staging/staging\-linus
 340  * [new branch]      staging\-next \-> staging/staging\-next
 341 $ git branch \-r
 342   origin/HEAD \-> origin/master
 343   origin/master
 344   staging/master
 345   staging/staging\-linus
 346   staging/staging\-next
 347 $ git switch \-c staging staging/master
 348 \&.\&.\&.
 349 .fi
 350 .if n \{\
 351 .RE
 352 .\}
 353 .RE
 354 .sp
 355 .RS 4
 356 .ie n \{\
 357 \h'-04'\(bu\h'+03'\c
 358 .\}
 359 .el \{\
 360 .sp -1
 361 .IP \(bu 2.3
 362 .\}
 363 Imitate
 364 \fIgit clone\fR
 365 but track only selected branches
 366 .sp
 367 .if n \{\
 368 .RS 4
 369 .\}
 370 .nf
 371 $ mkdir project\&.git
 372 $ cd project\&.git
 373 $ git init
 374 $ git remote add \-f \-t master \-m master origin git://example\&.com/git\&.git/
 375 $ git merge origin
 376 .fi
 377 .if n \{\
 378 .RE
 379 .\}
 380 .RE
 381 .SH "SEE ALSO"
 382 .sp
 383 \fBgit-fetch\fR(1) \fBgit-branch\fR(1) \fBgit-config\fR(1)
 384 .SH "GIT"
 385 .sp
 386 Part of the \fBgit\fR(1) suite