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