1GIT-REMOTE(1) Git Manual GIT-REMOTE(1)
2
6 git-remote - Manage set of tracked repositories
7
9 git remote [-v | --verbose]
10 git remote add [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url>
11 git remote rename <old> <new>
12 git remote remove <name>
13 git remote set-head <name> (-a | --auto | -d | --delete | <branch>)
14 git remote set-branches [--add] <name> <branch>...
15 git remote get-url [--push] [--all] <name>
16 git remote set-url [--push] <name> <newurl> [<oldurl>]
17 git remote set-url --add [--push] <name> <newurl>
18 git remote set-url --delete [--push] <name> <url>
19 git remote [-v | --verbose] show [-n] <name>...
20 git remote prune [-n | --dry-run] <name>...
21 git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...]
22
24 Manage the set of repositories ("remotes") whose branches you track.
25
27 -v, --verbose
28 Be a little more verbose and show remote url after name. NOTE: This
29 must be placed between remote and subcommand.
30
32 With no arguments, shows a list of existing remotes. Several
33 subcommands are available to perform operations on the remotes.
34 add
36 Add a remote named <name> for the repository at <url>. The command
37 git fetch <name> can then be used to create and update
38 remote-tracking branches <name>/<branch>.
39 With -f option, git fetch <name> is run immediately after the
41 remote information is set up.
42 With --tags option, git fetch <name> imports every tag from the
44 remote repository.
45 With --no-tags option, git fetch <name> does not import tags from
47 the remote repository.
48 By default, only tags on fetched branches are imported (see git-
50 fetch(1)).
51 With -t <branch> option, instead of the default glob refspec for
53 the remote to track all branches under the refs/remotes/<name>/
54 namespace, a refspec to track only <branch> is created. You can
55 give more than one -t <branch> to track multiple branches without
56 grabbing all branches.
57 With -m <master> option, a symbolic-ref refs/remotes/<name>/HEAD is
59 set up to point at remote’s <master> branch. See also the set-head
60 command.
61 When a fetch mirror is created with --mirror=fetch, the refs will
63 not be stored in the refs/remotes/ namespace, but rather everything
64 in refs/ on the remote will be directly mirrored into refs/ in the
65 local repository. This option only makes sense in bare
66 repositories, because a fetch would overwrite any local commits.
67 When a push mirror is created with --mirror=push, then git push
69 will always behave as if --mirror was passed.
70 rename
72 Rename the remote named <old> to <new>. All remote-tracking
73 branches and configuration settings for the remote are updated.
74 In case <old> and <new> are the same, and <old> is a file under
76 $GIT_DIR/remotes or $GIT_DIR/branches, the remote is converted to
77 the configuration file format.
78 remove, rm
80 Remove the remote named <name>. All remote-tracking branches and
81 configuration settings for the remote are removed.
82 set-head
84 Sets or deletes the default branch (i.e. the target of the
85 symbolic-ref refs/remotes/<name>/HEAD) for the named remote. Having
86 a default branch for a remote is not required, but allows the name
87 of the remote to be specified in lieu of a specific branch. For
88 example, if the default branch for origin is set to master, then
89 origin may be specified wherever you would normally specify
90 origin/master.
91 With -d or --delete, the symbolic ref refs/remotes/<name>/HEAD is
93 deleted.
94 With -a or --auto, the remote is queried to determine its HEAD,
96 then the symbolic-ref refs/remotes/<name>/HEAD is set to the same
97 branch. e.g., if the remote HEAD is pointed at next, git remote
98 set-head origin -a will set the symbolic-ref
99 refs/remotes/origin/HEAD to refs/remotes/origin/next. This will
100 only work if refs/remotes/origin/next already exists; if not it
101 must be fetched first.
102 Use <branch> to set the symbolic-ref refs/remotes/<name>/HEAD
104 explicitly. e.g., git remote set-head origin master will set the
105 symbolic-ref refs/remotes/origin/HEAD to
106 refs/remotes/origin/master. This will only work if
107 refs/remotes/origin/master already exists; if not it must be
108 fetched first.
109 set-branches
111 Changes the list of branches tracked by the named remote. This can
112 be used to track a subset of the available remote branches after
113 the initial setup for a remote.
114 The named branches will be interpreted as if specified with the -t
116 option on the git remote add command line.
117 With --add, instead of replacing the list of currently tracked
119 branches, adds to that list.
120 get-url
122 Retrieves the URLs for a remote. Configurations for insteadOf and
123 pushInsteadOf are expanded here. By default, only the first URL is
124 listed.
125 With --push, push URLs are queried rather than fetch URLs.
127 With --all, all URLs for the remote will be listed.
129 set-url
131 Changes URLs for the remote. Sets first URL for remote <name> that
132 matches regex <oldurl> (first URL if no <oldurl> is given) to
133 <newurl>. If <oldurl> doesn’t match any URL, an error occurs and
134 nothing is changed.
135 With --push, push URLs are manipulated instead of fetch URLs.
137 With --add, instead of changing existing URLs, new URL is added.
139 With --delete, instead of changing existing URLs, all URLs matching
141 regex <url> are deleted for remote <name>. Trying to delete all
142 non-push URLs is an error.
143 Note that the push URL and the fetch URL, even though they can be
145 set differently, must still refer to the same place. What you
146 pushed to the push URL should be what you would see if you
147 immediately fetched from the fetch URL. If you are trying to fetch
148 from one place (e.g. your upstream) and push to another (e.g. your
149 publishing repository), use two separate remotes.
150 show
152 Gives some information about the remote <name>.
153 With -n option, the remote heads are not queried first with git
155 ls-remote <name>; cached information is used instead.
156 prune
158 Deletes stale references associated with <name>. By default, stale
159 remote-tracking branches under <name> are deleted, but depending on
160 global configuration and the configuration of the remote we might
161 even prune local tags that haven’t been pushed there. Equivalent to
162 git fetch --prune <name>, except that no new references will be
163 fetched.
164 See the PRUNING section of git-fetch(1) for what it’ll prune
166 depending on various configuration.
167 With --dry-run option, report what branches would be pruned, but do
169 not actually prune them.
170 update
172 Fetch updates for remotes or remote groups in the repository as
173 defined by remotes.<group>. If neither group nor remote is
174 specified on the command line, the configuration parameter
175 remotes.default will be used; if remotes.default is not defined,
176 all remotes which do not have the configuration parameter
177 remote.<name>.skipDefaultUpdate set to true will be updated. (See
178 git-config(1)).
179 With --prune option, run pruning against all the remotes that are
181 updated.
182
184 The remote configuration is achieved using the remote.origin.url and
185 remote.origin.fetch configuration variables. (See git-config(1)).
186
188 On success, the exit status is 0.
189 When subcommands such as add, rename, and remove can’t find the remote
191 in question, the exit status is 2. When the remote already exists, the
192 exit status is 3.
193 On any other error, the exit status may be any other non-zero value.
195
197 • Add a new remote, fetch, and check out a branch from it
198 $ git remote
200 origin
201 $ git branch -r
202 origin/HEAD -> origin/master
203 origin/master
204 $ git remote add staging git://git.kernel.org/.../gregkh/staging.git
205 $ git remote
206 origin
207 staging
208 $ git fetch staging
209 ...
210 From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
211 * [new branch] master -> staging/master
212 * [new branch] staging-linus -> staging/staging-linus
213 * [new branch] staging-next -> staging/staging-next
214 $ git branch -r
215 origin/HEAD -> origin/master
216 origin/master
217 staging/master
218 staging/staging-linus
219 staging/staging-next
220 $ git switch -c staging staging/master
221 ...
222 • Imitate git clone but track only selected branches
224 $ mkdir project.git
226 $ cd project.git
227 $ git init
228 $ git remote add -f -t master -m master origin git://example.com/git.git/
229 $ git merge origin
230
232 git-fetch(1) git-branch(1) git-config(1)
233
235 Part of the git(1) suite
236Git 2.33.1 2021-10-12 GIT-REMOTE(1)