]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-clone(1) |
2 | ============ | |
6ec311da JH |
3 | |
4 | NAME | |
5 | ---- | |
29cf5e12 | 6 | git-clone - Clone a repository into a new directory |
6ec311da JH |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
353ce815 | 11 | [verse] |
76880f05 JNA |
12 | `git clone` [++--template=++__<template-directory>__] |
13 | [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`] | |
14 | [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_] | |
15 | [`--dissociate`] [`--separate-git-dir` _<git-dir>_] | |
16 | [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`] | |
17 | [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`] | |
18 | [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`] | |
19 | [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_ | |
20 | [_<directory>_] | |
6ec311da JH |
21 | |
22 | DESCRIPTION | |
23 | ----------- | |
4607166d | 24 | |
db9819a4 BF |
25 | Clones a repository into a newly created directory, creates |
26 | remote-tracking branches for each branch in the cloned repository | |
3711d1cd | 27 | (visible using `git branch --remotes`), and creates and checks out an |
33405be3 JN |
28 | initial branch that is forked from the cloned repository's |
29 | currently active branch. | |
4607166d | 30 | |
db9819a4 BF |
31 | After the clone, a plain `git fetch` without arguments will update |
32 | all the remote-tracking branches, and a `git pull` without | |
33 | arguments will in addition merge the remote master branch into the | |
76880f05 | 34 | current master branch, if any (this is untrue when `--single-branch` |
31b808a0 | 35 | is given; see below). |
4607166d | 36 | |
db9819a4 | 37 | This default configuration is achieved by creating references to |
cc1b8d8b | 38 | the remote branch heads under `refs/remotes/origin` and |
db9819a4 BF |
39 | by initializing `remote.origin.url` and `remote.origin.fetch` |
40 | configuration variables. | |
6ec311da | 41 | |
f4bf2184 | 42 | |
6ec311da JH |
43 | OPTIONS |
44 | ------- | |
76880f05 JNA |
45 | `-l`:: |
46 | `--local`:: | |
6ec311da | 47 | When the repository to clone from is on a local machine, |
2de9b711 | 48 | this flag bypasses the normal "Git aware" transport |
6ec311da | 49 | mechanism and clones the repository by making a copy of |
76880f05 | 50 | `HEAD` and everything under objects and refs directories. |
3d5c418f | 51 | The files under `.git/objects/` directory are hardlinked |
9197a10c JK |
52 | to save space when possible. |
53 | + | |
54 | If the repository is specified as a local path (e.g., `/path/to/repo`), | |
55 | this is the default, and --local is essentially a no-op. If the | |
56 | repository is specified as a URL, then this flag is ignored (and we | |
189260b1 JK |
57 | never use the local optimizations). Specifying `--no-local` will |
58 | override the default when `/path/to/repo` is given, using the regular | |
2de9b711 | 59 | Git transport instead. |
a4a1ca22 | 60 | + |
4e33535e GC |
61 | If the repository's `$GIT_DIR/objects` has symbolic links or is a |
62 | symbolic link, the clone will fail. This is a security measure to | |
63 | prevent the unintentional copying of files by dereferencing the symbolic | |
64 | links. | |
65 | + | |
a4a1ca22 TB |
66 | *NOTE*: this operation can race with concurrent modification to the |
67 | source repository, similar to running `cp -r src dst` while modifying | |
68 | `src`. | |
3d5c418f | 69 | |
76880f05 | 70 | `--no-hardlinks`:: |
897e3e45 ALI |
71 | Force the cloning process from a repository on a local |
72 | filesystem to copy the files under the `.git/objects` | |
73 | directory instead of using hardlinks. This may be desirable | |
74 | if you are trying to make a back-up of your repository. | |
6ec311da | 75 | |
76880f05 JNA |
76 | `-s`:: |
77 | `--shared`:: | |
a2775c2a | 78 | When the repository to clone is on the local machine, |
4607166d | 79 | instead of using hard links, automatically setup |
550c66f3 | 80 | `.git/objects/info/alternates` to share the objects |
4607166d JH |
81 | with the source repository. The resulting repository |
82 | starts out without any object of its own. | |
84668872 MV |
83 | + |
84 | *NOTE*: this is a possibly dangerous operation; do *not* use | |
85 | it unless you understand what it does. If you clone your | |
2498a1ad | 86 | repository using this option and then delete branches (or use any |
2de9b711 | 87 | other Git command that makes any existing commit unreferenced) in the |
2498a1ad | 88 | source repository, some objects may become unreferenced (or dangling). |
2de9b711 | 89 | These objects may be removed by normal Git operations (such as `git commit`) |
a95ce124 DS |
90 | which automatically call `git maintenance run --auto`. (See |
91 | linkgit:git-maintenance[1].) If these objects are removed and were referenced | |
92 | by the cloned repository, then the cloned repository will become corrupt. | |
13354f53 | 93 | + |
3711d1cd QN |
94 | Note that running `git repack` without the `--local` option in a repository |
95 | cloned with `--shared` will copy objects from the source repository into a pack | |
96 | in the cloned repository, removing the disk space savings of `clone --shared`. | |
97 | It is safe, however, to run `git gc`, which uses the `--local` option by | |
13354f53 JK |
98 | default. |
99 | + | |
3711d1cd | 100 | If you want to break the dependency of a repository cloned with `--shared` on |
13354f53 JK |
101 | its source repository, you can simply run `git repack -a` to copy all |
102 | objects from the source repository into a pack in the cloned repository. | |
a2775c2a | 103 | |
76880f05 | 104 | `--reference`[`-if-able`] _<repository>_:: |
45d5ed3e | 105 | If the reference _<repository>_ is on the local machine, |
550c66f3 | 106 | automatically setup `.git/objects/info/alternates` to |
45d5ed3e | 107 | obtain objects from the reference _<repository>_. Using |
23edecbc | 108 | an already existing repository as an alternate will |
451e5931 | 109 | require fewer objects to be copied from the repository |
23edecbc | 110 | being cloned, reducing network and local storage costs. |
f7415b4d SB |
111 | When using the `--reference-if-able`, a non existing |
112 | directory is skipped with a warning instead of aborting | |
113 | the clone. | |
2498a1ad | 114 | + |
fb1d6dab JH |
115 | *NOTE*: see the NOTE for the `--shared` option, and also the |
116 | `--dissociate` option. | |
117 | ||
76880f05 | 118 | `--dissociate`:: |
fb1d6dab JH |
119 | Borrow the objects from reference repositories specified |
120 | with the `--reference` options only to reduce network | |
0181681e AR |
121 | transfer, and stop borrowing from them after a clone is made |
122 | by making necessary local copies of borrowed objects. This | |
123 | option can also be used when cloning locally from a | |
124 | repository that already borrows objects from another | |
125 | repository--the new repository will borrow objects from the | |
126 | same repository, and this option can be used to stop the | |
127 | borrowing. | |
23edecbc | 128 | |
76880f05 JNA |
129 | `-q`:: |
130 | `--quiet`:: | |
488c3163 | 131 | Operate quietly. Progress is not reported to the standard |
0d0bac67 | 132 | error stream. |
6ec311da | 133 | |
76880f05 JNA |
134 | `-v`:: |
135 | `--verbose`:: | |
c54b74af TRC |
136 | Run verbosely. Does not affect the reporting of progress status |
137 | to the standard error stream. | |
5a518ad4 | 138 | |
76880f05 | 139 | `--progress`:: |
488c3163 | 140 | Progress status is reported on the standard error stream |
3711d1cd | 141 | by default when it is attached to a terminal, unless `--quiet` |
488c3163 TRC |
142 | is specified. This flag forces progress status even if the |
143 | standard error stream is not directed to a terminal. | |
21188b1e | 144 | |
76880f05 | 145 | ++--server-option=++__<option>__:: |
6e983059 JT |
146 | Transmit the given string to the server when communicating using |
147 | protocol version 2. The given string must not contain a NUL or LF | |
148 | character. The server's handling of server options, including | |
149 | unknown ones, is server-specific. | |
76880f05 | 150 | When multiple ++--server-option=++__<option>__ are given, they are all |
6e983059 JT |
151 | sent to the other side in the order listed on the command line. |
152 | ||
76880f05 JNA |
153 | `-n`:: |
154 | `--no-checkout`:: | |
a2775c2a EB |
155 | No checkout of HEAD is performed after the clone is complete. |
156 | ||
76880f05 | 157 | `--`[`no-`]`reject-shallow`:: |
4fe788b1 | 158 | Fail if the source repository is a shallow repository. |
d3717e1e | 159 | The `clone.rejectShallow` configuration variable can be used to |
4fe788b1 LL |
160 | specify the default. |
161 | ||
76880f05 | 162 | `--bare`:: |
48a8c26c | 163 | Make a 'bare' Git repository. That is, instead of |
45d5ed3e | 164 | creating _<directory>_ and placing the administrative |
76880f05 | 165 | files in _<directory>_`/.git`, make the _<directory>_ |
3711d1cd | 166 | itself the `$GIT_DIR`. This obviously implies the `--no-checkout` |
71821351 PB |
167 | because there is nowhere to check out the working tree. |
168 | Also the branch heads at the remote are copied directly | |
169 | to corresponding local branch heads, without mapping | |
170 | them to `refs/remotes/origin/`. When this option is | |
36566cc0 BF |
171 | used, neither remote-tracking branches nor the related |
172 | configuration variables are created. | |
8a1a120c | 173 | |
76880f05 | 174 | `--sparse`:: |
d30e2bbe EN |
175 | Employ a sparse-checkout, with only files in the toplevel |
176 | directory initially being present. The | |
177 | linkgit:git-sparse-checkout[1] command can be used to grow the | |
178 | working directory as needed. | |
d89f09c8 | 179 | |
76880f05 | 180 | ++--filter=++__<filter-spec>__:: |
4a465443 DS |
181 | Use the partial clone feature and request that the server sends |
182 | a subset of reachable objects according to a given object filter. | |
45d5ed3e | 183 | When using `--filter`, the supplied _<filter-spec>_ is used for |
4a465443 DS |
184 | the partial clone filter. For example, `--filter=blob:none` will |
185 | filter out all blobs (file contents) until needed by Git. Also, | |
76880f05 | 186 | ++--filter=blob:limit=++__<size>__ will filter out all blobs of size |
45d5ed3e | 187 | at least _<size>_. For more details on filter specifications, see |
4a465443 DS |
188 | the `--filter` option in linkgit:git-rev-list[1]. |
189 | ||
76880f05 | 190 | `--also-filter-submodules`:: |
f05da2b4 JS |
191 | Also apply the partial clone filter to any submodules in the repository. |
192 | Requires `--filter` and `--recurse-submodules`. This can be turned on by | |
193 | default by setting the `clone.filterSubmodules` config option. | |
194 | ||
76880f05 | 195 | `--mirror`:: |
6db2103f UKK |
196 | Set up a mirror of the source repository. This implies `--bare`. |
197 | Compared to `--bare`, `--mirror` not only maps local branches of the | |
198 | source to local branches of the target, it maps all refs (including | |
29b9a66f | 199 | remote-tracking branches, notes etc.) and sets up a refspec configuration such |
6db2103f UKK |
200 | that all these refs are overwritten by a `git remote update` in the |
201 | target repository. | |
bc699afc | 202 | |
76880f05 JNA |
203 | `-o` _<name>_:: |
204 | `--origin` _<name>_:: | |
de9ed3ef | 205 | Instead of using the remote name `origin` to keep track of the upstream |
45d5ed3e | 206 | repository, use _<name>_. Overrides `clone.defaultRemoteName` from the |
de9ed3ef | 207 | config. |
e6c310fd | 208 | |
76880f05 JNA |
209 | `-b` _<name>_:: |
210 | `--branch` _<name>_:: | |
7a4ee28f | 211 | Instead of pointing the newly created HEAD to the branch pointed |
45d5ed3e | 212 | to by the cloned repository's HEAD, point to _<name>_ branch |
31b808a0 RT |
213 | instead. In a non-bare repository, this is the branch that will |
214 | be checked out. | |
215 | `--branch` can also take tags and detaches the HEAD at that commit | |
216 | in the resulting repository. | |
7a4ee28f | 217 | |
76880f05 JNA |
218 | `-u` _<upload-pack>_:: |
219 | `--upload-pack` _<upload-pack>_:: | |
d3296e37 SH |
220 | When given, and the repository to clone from is accessed |
221 | via ssh, this specifies a non-default path for the command | |
6ec311da JH |
222 | run on the other end. |
223 | ||
76880f05 | 224 | ++--template=++__<template-directory>__:: |
a57c8bac | 225 | Specify the directory from which templates will be used; |
d8a8488d | 226 | (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) |
a57c8bac | 227 | |
76880f05 JNA |
228 | `-c` __<key>__++=++__<value>__:: |
229 | `--config` __<key>__++=++__<value>__:: | |
84054f79 JK |
230 | Set a configuration variable in the newly-created repository; |
231 | this takes effect immediately after the repository is | |
232 | initialized, but before the remote history is fetched or any | |
45d5ed3e | 233 | files checked out. The _<key>_ is in the same format as expected by |
84054f79 JK |
234 | linkgit:git-config[1] (e.g., `core.eol=true`). If multiple |
235 | values are given for the same key, each value will be written to | |
236 | the config file. This makes it safe, for example, to add | |
237 | additional fetch refspecs to the origin remote. | |
7eae4a3a SG |
238 | + |
239 | Due to limitations of the current implementation, some configuration | |
240 | variables do not take effect until after the initial fetch and checkout. | |
241 | Configuration variables known to not take effect are: | |
76880f05 | 242 | ++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++. Use the |
7eae4a3a | 243 | corresponding `--mirror` and `--no-tags` options instead. |
84054f79 | 244 | |
76880f05 | 245 | `--depth` _<depth>_:: |
f4bf2184 | 246 | Create a 'shallow' clone with a history truncated to the |
fc142811 | 247 | specified number of commits. Implies `--single-branch` unless |
28a1b569 | 248 | `--no-single-branch` is given to fetch the histories near the |
18a74a09 JH |
249 | tips of all branches. If you want to clone submodules shallowly, |
250 | also pass `--shallow-submodules`. | |
f4bf2184 | 251 | |
76880f05 | 252 | ++--shallow-since=++__<date>__:: |
994c2aaf NTND |
253 | Create a shallow clone with a history after the specified time. |
254 | ||
76880f05 | 255 | ++--shallow-exclude=++__<revision>__:: |
859e5df9 NTND |
256 | Create a shallow clone with a history, excluding commits |
257 | reachable from a specified remote branch or tag. This option | |
258 | can be specified multiple times. | |
259 | ||
76880f05 | 260 | `--`[`no-`]`single-branch`:: |
3e6e0edd NTND |
261 | Clone only the history leading to the tip of a single branch, |
262 | either specified by the `--branch` option or the primary | |
28a1b569 | 263 | branch remote's `HEAD` points at. |
31b808a0 | 264 | Further fetches into the resulting repository will only update the |
a6d3bde5 | 265 | remote-tracking branch for the branch this option was used for the |
d3717e1e | 266 | initial cloning. If the `HEAD` at the remote did not point at any |
a6d3bde5 | 267 | branch when `--single-branch` clone was made, no remote-tracking |
31b808a0 | 268 | branch is created. |
3e6e0edd | 269 | |
76880f05 | 270 | `--no-tags`:: |
0dab2468 ÆAB |
271 | Don't clone any tags, and set |
272 | `remote.<remote>.tagOpt=--no-tags` in the config, ensuring | |
273 | that future `git pull` and `git fetch` operations won't follow | |
274 | any tags. Subsequent explicit tag fetches will still work, | |
275 | (see linkgit:git-fetch[1]). | |
276 | + | |
277 | Can be used in conjunction with `--single-branch` to clone and | |
278 | maintain a branch with no references other than a single cloned | |
279 | branch. This is useful e.g. to maintain minimal clones of the default | |
280 | branch of some repository for search indexing. | |
281 | ||
76880f05 | 282 | `--recurse-submodules`[`=`{empty}__<pathspec>__]:: |
bb62e0a9 | 283 | After the clone is created, initialize and clone submodules |
45d5ed3e | 284 | within based on the provided _<pathspec>_. If no _=<pathspec>_ is |
bb62e0a9 | 285 | provided, all submodules are initialized and cloned. |
bc29b0b9 SB |
286 | This option can be given multiple times for pathspecs consisting |
287 | of multiple entries. The resulting clone has `submodule.active` set to | |
bb62e0a9 | 288 | the provided pathspec, or "." (meaning all submodules) if no |
bc29b0b9 SB |
289 | pathspec is provided. |
290 | + | |
291 | Submodules are initialized and cloned using their default settings. This is | |
292 | equivalent to running | |
293 | `git submodule update --init --recursive <pathspec>` immediately after | |
294 | the clone is finished. This option is ignored if the cloned repository does | |
295 | not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, | |
296 | or `--mirror` is given) | |
e7fed18a | 297 | |
76880f05 | 298 | `--`[`no-`]`shallow-submodules`:: |
d22eb044 SB |
299 | All submodules which are cloned will be shallow with a depth of 1. |
300 | ||
76880f05 | 301 | `--`[`no-`]`remote-submodules`:: |
fd5041e1 | 302 | All submodules which are cloned will use the status of the submodule's |
4c691016 | 303 | remote-tracking branch to update the submodule, rather than the |
fd5041e1 | 304 | superproject's recorded SHA-1. Equivalent to passing `--remote` to |
4c691016 BA |
305 | `git submodule update`. |
306 | ||
76880f05 | 307 | `--separate-git-dir=`{empty}__<git-dir>__:: |
b57fb80a NTND |
308 | Instead of placing the cloned repository where it is supposed |
309 | to be, place the cloned repository at the specified directory, | |
5fe8f49b | 310 | then make a filesystem-agnostic Git symbolic link to there. |
2de9b711 | 311 | The result is Git repository can be separated from working |
b57fb80a NTND |
312 | tree. |
313 | ||
76880f05 | 314 | `--ref-format=`{empty}__<ref-format>__:: |
5ed860f5 PS |
315 | |
316 | Specify the given ref storage format for the repository. The valid values are: | |
317 | + | |
318 | include::ref-storage-format.txt[] | |
319 | ||
76880f05 JNA |
320 | `-j` _<n>_:: |
321 | `--jobs` _<n>_:: | |
72290d6a SB |
322 | The number of submodules fetched at the same time. |
323 | Defaults to the `submodule.fetchJobs` option. | |
b57fb80a | 324 | |
76880f05 | 325 | _<repository>_:: |
45d5ed3e | 326 | The (possibly remote) _<repository>_ to clone from. See the |
73364e4f | 327 | <<URLS,GIT URLS>> section below for more information on specifying |
37ba0561 | 328 | repositories. |
6ec311da | 329 | |
76880f05 | 330 | _<directory>_:: |
fb6a9f93 | 331 | The name of a new directory to clone into. The "humanish" |
45d5ed3e | 332 | part of the source repository is used if no _<directory>_ is |
550c66f3 BG |
333 | explicitly given (`repo` for `/path/to/repo.git` and `foo` |
334 | for `host.xz:foo/.git`). Cloning into an existing directory | |
ec00d6e0 | 335 | is only allowed if the directory is empty. |
4607166d | 336 | |
76880f05 | 337 | `--bundle-uri=`{empty}__<uri>__:: |
55568919 | 338 | Before fetching from the remote, fetch a bundle from the given |
45d5ed3e | 339 | _<uri>_ and unbundle the data into the local repository. The refs |
55568919 | 340 | in the bundle will be stored under the hidden `refs/bundle/*` |
e21e663c DS |
341 | namespace. This option is incompatible with `--depth`, |
342 | `--shallow-since`, and `--shallow-exclude`. | |
55568919 | 343 | |
347989f4 | 344 | :git-clone: 1 |
37ba0561 AR |
345 | include::urls.txt[] |
346 | ||
76a8788c | 347 | EXAMPLES |
2b5f3ed3 | 348 | -------- |
1e2ccd3a | 349 | |
47638685 | 350 | * Clone from upstream: |
1e2ccd3a JH |
351 | + |
352 | ------------ | |
283efb01 TK |
353 | $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux |
354 | $ cd my-linux | |
1e2ccd3a JH |
355 | $ make |
356 | ------------ | |
357 | ||
358 | ||
47638685 | 359 | * Make a local clone that borrows from the current directory, without checking things out: |
1e2ccd3a JH |
360 | + |
361 | ------------ | |
362 | $ git clone -l -s -n . ../copy | |
a6e3768f | 363 | $ cd ../copy |
1e2ccd3a JH |
364 | $ git show-branch |
365 | ------------ | |
366 | ||
8a1a120c | 367 | |
47638685 | 368 | * Clone from upstream while borrowing from an existing local directory: |
23edecbc SP |
369 | + |
370 | ------------ | |
f22a6543 TK |
371 | $ git clone --reference /git/linux.git \ |
372 | git://git.kernel.org/pub/scm/.../linux.git \ | |
373 | my-linux | |
374 | $ cd my-linux | |
23edecbc SP |
375 | ------------ |
376 | ||
377 | ||
47638685 | 378 | * Create a bare repository to publish your changes to the public: |
8a1a120c JH |
379 | + |
380 | ------------ | |
87e80c4b | 381 | $ git clone --bare -l /home/proj/.git /pub/scm/proj.git |
8a1a120c JH |
382 | ------------ |
383 | ||
16f6b0d1 ÆAB |
384 | CONFIGURATION |
385 | ------------- | |
386 | ||
387 | include::includes/cmd-config-section-all.txt[] | |
388 | ||
9274dea3 ÆAB |
389 | include::config/init.txt[] |
390 | ||
16f6b0d1 ÆAB |
391 | include::config/clone.txt[] |
392 | ||
8a1a120c | 393 | |
6ec311da JH |
394 | GIT |
395 | --- | |
9e1f0a85 | 396 | Part of the linkgit:git[1] suite |