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