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 [--[no-]progress] <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. For
29 promisor remotes, also show which filter (blob:none etc.) are
30 configured. NOTE: This must be placed between remote and
31 subcommand.
32
34 With no arguments, shows a list of existing remotes. Several
35 subcommands are available to perform operations on the remotes.
36 add
38 Add a remote named <name> for the repository at <URL>. The command
39 git fetch <name> can then be used to create and update
40 remote-tracking branches <name>/<branch>.
41 With -f option, git fetch <name> is run immediately after the
43 remote information is set up.
44 With --tags option, git fetch <name> imports every tag from the
46 remote repository.
47 With --no-tags option, git fetch <name> does not import tags from
49 the remote repository.
50 By default, only tags on fetched branches are imported (see git-
52 fetch(1)).
53 With -t <branch> option, instead of the default glob refspec for
55 the remote to track all branches under the refs/remotes/<name>/
56 namespace, a refspec to track only <branch> is created. You can
57 give more than one -t <branch> to track multiple branches without
58 grabbing all branches.
59 With -m <master> option, a symbolic-ref refs/remotes/<name>/HEAD is
61 set up to point at remote’s <master> branch. See also the set-head
62 command.
63 When a fetch mirror is created with --mirror=fetch, the refs will
65 not be stored in the refs/remotes/ namespace, but rather everything
66 in refs/ on the remote will be directly mirrored into refs/ in the
67 local repository. This option only makes sense in bare
68 repositories, because a fetch would overwrite any local commits.
69 When a push mirror is created with --mirror=push, then git push
71 will always behave as if --mirror was passed.
72 rename
74 Rename the remote named <old> to <new>. All remote-tracking
75 branches and configuration settings for the remote are updated.
76 In case <old> and <new> are the same, and <old> is a file under
78 $GIT_DIR/remotes or $GIT_DIR/branches, the remote is converted to
79 the configuration file format.
80 remove, rm
82 Remove the remote named <name>. All remote-tracking branches and
83 configuration settings for the remote are removed.
84 set-head
86 Sets or deletes the default branch (i.e. the target of the
87 symbolic-ref refs/remotes/<name>/HEAD) for the named remote. Having
88 a default branch for a remote is not required, but allows the name
89 of the remote to be specified in lieu of a specific branch. For
90 example, if the default branch for origin is set to master, then
91 origin may be specified wherever you would normally specify
92 origin/master.
93 With -d or --delete, the symbolic ref refs/remotes/<name>/HEAD is
95 deleted.
96 With -a or --auto, the remote is queried to determine its HEAD,
98 then the symbolic-ref refs/remotes/<name>/HEAD is set to the same
99 branch. e.g., if the remote HEAD is pointed at next, git remote
100 set-head origin -a will set the symbolic-ref
101 refs/remotes/origin/HEAD to refs/remotes/origin/next. This will
102 only work if refs/remotes/origin/next already exists; if not it
103 must be fetched first.
104 Use <branch> to set the symbolic-ref refs/remotes/<name>/HEAD
106 explicitly. e.g., git remote set-head origin master will set the
107 symbolic-ref refs/remotes/origin/HEAD to
108 refs/remotes/origin/master. This will only work if
109 refs/remotes/origin/master already exists; if not it must be
110 fetched first.
111 set-branches
113 Changes the list of branches tracked by the named remote. This can
114 be used to track a subset of the available remote branches after
115 the initial setup for a remote.
116 The named branches will be interpreted as if specified with the -t
118 option on the git remote add command line.
119 With --add, instead of replacing the list of currently tracked
121 branches, adds to that list.
122 get-url
124 Retrieves the URLs for a remote. Configurations for insteadOf and
125 pushInsteadOf are expanded here. By default, only the first URL is
126 listed.
127 With --push, push URLs are queried rather than fetch URLs.
129 With --all, all URLs for the remote will be listed.
131 set-url
133 Changes URLs for the remote. Sets first URL for remote <name> that
134 matches regex <oldurl> (first URL if no <oldurl> is given) to
135 <newurl>. If <oldurl> doesn’t match any URL, an error occurs and
136 nothing is changed.
137 With --push, push URLs are manipulated instead of fetch URLs.
139 With --add, instead of changing existing URLs, new URL is added.
141 With --delete, instead of changing existing URLs, all URLs matching
143 regex <URL> are deleted for remote <name>. Trying to delete all
144 non-push URLs is an error.
145 Note that the push URL and the fetch URL, even though they can be
147 set differently, must still refer to the same place. What you
148 pushed to the push URL should be what you would see if you
149 immediately fetched from the fetch URL. If you are trying to fetch
150 from one place (e.g. your upstream) and push to another (e.g. your
151 publishing repository), use two separate remotes.
152 show
154 Gives some information about the remote <name>.
155 With -n option, the remote heads are not queried first with git
157 ls-remote <name>; cached information is used instead.
158 prune
160 Deletes stale references associated with <name>. By default, stale
161 remote-tracking branches under <name> are deleted, but depending on
162 global configuration and the configuration of the remote we might
163 even prune local tags that haven’t been pushed there. Equivalent to
164 git fetch --prune <name>, except that no new references will be
165 fetched.
166 See the PRUNING section of git-fetch(1) for what it’ll prune
168 depending on various configuration.
169 With --dry-run option, report what branches would be pruned, but do
171 not actually prune them.
172 update
174 Fetch updates for remotes or remote groups in the repository as
175 defined by remotes.<group>. If neither group nor remote is
176 specified on the command line, the configuration parameter
177 remotes.default will be used; if remotes.default is not defined,
178 all remotes which do not have the configuration parameter
179 remote.<name>.skipDefaultUpdate set to true will be updated. (See
180 git-config(1)).
181 With --prune option, run pruning against all the remotes that are
183 updated.
184
186 The remote configuration is achieved using the remote.origin.url and
187 remote.origin.fetch configuration variables. (See git-config(1)).
188
190 On success, the exit status is 0.
191 When subcommands such as add, rename, and remove can’t find the remote
193 in question, the exit status is 2. When the remote already exists, the
194 exit status is 3.
195 On any other error, the exit status may be any other non-zero value.
197
199 • Add a new remote, fetch, and check out a branch from it
200 $ git remote
202 origin
203 $ git branch -r
204 origin/HEAD -> origin/master
205 origin/master
206 $ git remote add staging git://git.kernel.org/.../gregkh/staging.git
207 $ git remote
208 origin
209 staging
210 $ git fetch staging
211 ...
212 From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
213 * [new branch] master -> staging/master
214 * [new branch] staging-linus -> staging/staging-linus
215 * [new branch] staging-next -> staging/staging-next
216 $ git branch -r
217 origin/HEAD -> origin/master
218 origin/master
219 staging/master
220 staging/staging-linus
221 staging/staging-next
222 $ git switch -c staging staging/master
223 ...
224 • Imitate git clone but track only selected branches
226 $ mkdir project.git
228 $ cd project.git
229 $ git init
230 $ git remote add -f -t master -m master origin git://example.com/git.git/
231 $ git merge origin
232
234 git-fetch(1) git-branch(1) git-config(1)
235
237 Part of the git(1) suite
238Git 2.39.1 2023-01-13 GIT-REMOTE(1)