]>
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>] |
09ffc706 | 15 | [--separate-git-dir <git dir>] |
3e6e0edd | 16 | [--depth <depth>] [--[no-]single-branch] |
0460ed2c | 17 | [--recursive | --recurse-submodules] [--] <repository> |
ccdd3da6 | 18 | [<directory>] |
6ec311da JH |
19 | |
20 | DESCRIPTION | |
21 | ----------- | |
4607166d | 22 | |
db9819a4 BF |
23 | Clones a repository into a newly created directory, creates |
24 | remote-tracking branches for each branch in the cloned repository | |
33405be3 JN |
25 | (visible using `git branch -r`), and creates and checks out an |
26 | initial branch that is forked from the cloned repository's | |
27 | currently active branch. | |
4607166d | 28 | |
db9819a4 BF |
29 | After the clone, a plain `git fetch` without arguments will update |
30 | all the remote-tracking branches, and a `git pull` without | |
31 | arguments will in addition merge the remote master branch into the | |
31b808a0 RT |
32 | current master branch, if any (this is untrue when "--single-branch" |
33 | is given; see below). | |
4607166d | 34 | |
db9819a4 | 35 | This default configuration is achieved by creating references to |
cc1b8d8b | 36 | the remote branch heads under `refs/remotes/origin` and |
db9819a4 BF |
37 | by initializing `remote.origin.url` and `remote.origin.fetch` |
38 | configuration variables. | |
6ec311da | 39 | |
f4bf2184 | 40 | |
6ec311da JH |
41 | OPTIONS |
42 | ------- | |
a2775c2a | 43 | --local:: |
6ec311da JH |
44 | -l:: |
45 | When the repository to clone from is on a local machine, | |
2de9b711 | 46 | this flag bypasses the normal "Git aware" transport |
6ec311da JH |
47 | mechanism and clones the repository by making a copy of |
48 | HEAD and everything under objects and refs directories. | |
3d5c418f | 49 | The files under `.git/objects/` directory are hardlinked |
9197a10c JK |
50 | to save space when possible. |
51 | + | |
52 | If the repository is specified as a local path (e.g., `/path/to/repo`), | |
53 | this is the default, and --local is essentially a no-op. If the | |
54 | repository is specified as a URL, then this flag is ignored (and we | |
189260b1 JK |
55 | never use the local optimizations). Specifying `--no-local` will |
56 | override the default when `/path/to/repo` is given, using the regular | |
2de9b711 | 57 | Git transport instead. |
9197a10c JK |
58 | + |
59 | To force copying instead of hardlinking (which may be desirable if you | |
60 | are trying to make a back-up of your repository), but still avoid the | |
2de9b711 | 61 | usual "Git aware" transport mechanism, `--no-hardlinks` can be used. |
3d5c418f JH |
62 | |
63 | --no-hardlinks:: | |
64 | Optimize the cloning process from a repository on a | |
65 | local filesystem by copying files under `.git/objects` | |
66 | directory. | |
6ec311da | 67 | |
a2775c2a EB |
68 | --shared:: |
69 | -s:: | |
70 | When the repository to clone is on the local machine, | |
4607166d | 71 | instead of using hard links, automatically setup |
550c66f3 | 72 | `.git/objects/info/alternates` to share the objects |
4607166d JH |
73 | with the source repository. The resulting repository |
74 | starts out without any object of its own. | |
84668872 MV |
75 | + |
76 | *NOTE*: this is a possibly dangerous operation; do *not* use | |
77 | it unless you understand what it does. If you clone your | |
2498a1ad | 78 | repository using this option and then delete branches (or use any |
2de9b711 | 79 | other Git command that makes any existing commit unreferenced) in the |
2498a1ad | 80 | source repository, some objects may become unreferenced (or dangling). |
2de9b711 | 81 | These objects may be removed by normal Git operations (such as `git commit`) |
483bc4f0 JN |
82 | which automatically call `git gc --auto`. (See linkgit:git-gc[1].) |
83 | If these objects are removed and were referenced by the cloned repository, | |
84 | then the cloned repository will become corrupt. | |
13354f53 JK |
85 | + |
86 | Note that running `git repack` without the `-l` option in a repository | |
87 | cloned with `-s` will copy objects from the source repository into a pack | |
88 | in the cloned repository, removing the disk space savings of `clone -s`. | |
89 | It is safe, however, to run `git gc`, which uses the `-l` option by | |
90 | default. | |
91 | + | |
92 | If you want to break the dependency of a repository cloned with `-s` on | |
93 | its source repository, you can simply run `git repack -a` to copy all | |
94 | objects from the source repository into a pack in the cloned repository. | |
a2775c2a | 95 | |
23edecbc | 96 | --reference <repository>:: |
40592376 | 97 | If the reference repository is on the local machine, |
550c66f3 | 98 | automatically setup `.git/objects/info/alternates` to |
23edecbc SP |
99 | obtain objects from the reference repository. Using |
100 | an already existing repository as an alternate will | |
451e5931 | 101 | require fewer objects to be copied from the repository |
23edecbc | 102 | being cloned, reducing network and local storage costs. |
2498a1ad | 103 | + |
550c66f3 | 104 | *NOTE*: see the NOTE for the `--shared` option. |
23edecbc | 105 | |
a2775c2a | 106 | --quiet:: |
6ec311da | 107 | -q:: |
488c3163 TRC |
108 | Operate quietly. Progress is not reported to the standard |
109 | error stream. This flag is also passed to the `rsync' | |
d3296e37 | 110 | command when given. |
6ec311da | 111 | |
21188b1e MV |
112 | --verbose:: |
113 | -v:: | |
c54b74af TRC |
114 | Run verbosely. Does not affect the reporting of progress status |
115 | to the standard error stream. | |
5a518ad4 TRC |
116 | |
117 | --progress:: | |
488c3163 TRC |
118 | Progress status is reported on the standard error stream |
119 | by default when it is attached to a terminal, unless -q | |
120 | is specified. This flag forces progress status even if the | |
121 | standard error stream is not directed to a terminal. | |
21188b1e | 122 | |
fd0368f9 | 123 | --no-checkout:: |
a2775c2a EB |
124 | -n:: |
125 | No checkout of HEAD is performed after the clone is complete. | |
126 | ||
87e80c4b | 127 | --bare:: |
48a8c26c | 128 | Make a 'bare' Git repository. That is, instead of |
8a1a120c JH |
129 | creating `<directory>` and placing the administrative |
130 | files in `<directory>/.git`, make the `<directory>` | |
71821351 PB |
131 | itself the `$GIT_DIR`. This obviously implies the `-n` |
132 | because there is nowhere to check out the working tree. | |
133 | Also the branch heads at the remote are copied directly | |
134 | to corresponding local branch heads, without mapping | |
135 | them to `refs/remotes/origin/`. When this option is | |
36566cc0 BF |
136 | used, neither remote-tracking branches nor the related |
137 | configuration variables are created. | |
8a1a120c | 138 | |
bc699afc | 139 | --mirror:: |
6db2103f UKK |
140 | Set up a mirror of the source repository. This implies `--bare`. |
141 | Compared to `--bare`, `--mirror` not only maps local branches of the | |
142 | source to local branches of the target, it maps all refs (including | |
29b9a66f | 143 | remote-tracking branches, notes etc.) and sets up a refspec configuration such |
6db2103f UKK |
144 | that all these refs are overwritten by a `git remote update` in the |
145 | target repository. | |
bc699afc | 146 | |
ba158a32 | 147 | --origin <name>:: |
e6c310fd | 148 | -o <name>:: |
550c66f3 BG |
149 | Instead of using the remote name `origin` to keep track |
150 | of the upstream repository, use `<name>`. | |
e6c310fd | 151 | |
7a4ee28f JK |
152 | --branch <name>:: |
153 | -b <name>:: | |
154 | Instead of pointing the newly created HEAD to the branch pointed | |
550c66f3 | 155 | to by the cloned repository's HEAD, point to `<name>` branch |
31b808a0 RT |
156 | instead. In a non-bare repository, this is the branch that will |
157 | be checked out. | |
158 | `--branch` can also take tags and detaches the HEAD at that commit | |
159 | in the resulting repository. | |
7a4ee28f | 160 | |
a2775c2a | 161 | --upload-pack <upload-pack>:: |
6ec311da | 162 | -u <upload-pack>:: |
d3296e37 SH |
163 | When given, and the repository to clone from is accessed |
164 | via ssh, this specifies a non-default path for the command | |
6ec311da JH |
165 | run on the other end. |
166 | ||
a57c8bac JH |
167 | --template=<template_directory>:: |
168 | Specify the directory from which templates will be used; | |
d8a8488d | 169 | (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) |
a57c8bac | 170 | |
84054f79 JK |
171 | --config <key>=<value>:: |
172 | -c <key>=<value>:: | |
173 | Set a configuration variable in the newly-created repository; | |
174 | this takes effect immediately after the repository is | |
175 | initialized, but before the remote history is fetched or any | |
176 | files checked out. The key is in the same format as expected by | |
177 | linkgit:git-config[1] (e.g., `core.eol=true`). If multiple | |
178 | values are given for the same key, each value will be written to | |
179 | the config file. This makes it safe, for example, to add | |
180 | additional fetch refspecs to the origin remote. | |
181 | ||
f496454e | 182 | --depth <depth>:: |
f4bf2184 | 183 | Create a 'shallow' clone with a history truncated to the |
d9d10bb8 | 184 | specified number of revisions. A shallow repository has a |
5333f2af JH |
185 | number of limitations (you cannot clone or fetch from |
186 | it, nor push from nor into it), but is adequate if you | |
187 | are only interested in the recent history of a large project | |
188 | with a long history, and would want to send in fixes | |
189 | as patches. | |
f4bf2184 | 190 | |
0460ed2c | 191 | --[no-]single-branch:: |
3e6e0edd NTND |
192 | Clone only the history leading to the tip of a single branch, |
193 | either specified by the `--branch` option or the primary | |
194 | branch remote's `HEAD` points at. When creating a shallow | |
195 | clone with the `--depth` option, this is the default, unless | |
196 | `--no-single-branch` is given to fetch the histories near the | |
197 | tips of all branches. | |
31b808a0 | 198 | Further fetches into the resulting repository will only update the |
a6d3bde5 | 199 | remote-tracking branch for the branch this option was used for the |
31b808a0 | 200 | initial cloning. If the HEAD at the remote did not point at any |
a6d3bde5 | 201 | branch when `--single-branch` clone was made, no remote-tracking |
31b808a0 | 202 | branch is created. |
3e6e0edd | 203 | |
e7fed18a | 204 | --recursive:: |
ccdd3da6 | 205 | --recurse-submodules:: |
e7fed18a JH |
206 | After the clone is created, initialize all submodules within, |
207 | using their default settings. This is equivalent to running | |
550c66f3 | 208 | `git submodule update --init --recursive` immediately after |
e7fed18a JH |
209 | the clone is finished. This option is ignored if the cloned |
210 | repository does not have a worktree/checkout (i.e. if any of | |
211 | `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) | |
212 | ||
b57fb80a NTND |
213 | --separate-git-dir=<git dir>:: |
214 | Instead of placing the cloned repository where it is supposed | |
215 | to be, place the cloned repository at the specified directory, | |
2de9b711 TA |
216 | then make a filesytem-agnostic Git symbolic link to there. |
217 | The result is Git repository can be separated from working | |
b57fb80a NTND |
218 | tree. |
219 | ||
220 | ||
6ec311da | 221 | <repository>:: |
37ba0561 AR |
222 | The (possibly remote) repository to clone from. See the |
223 | <<URLS,URLS>> section below for more information on specifying | |
224 | repositories. | |
6ec311da JH |
225 | |
226 | <directory>:: | |
fb6a9f93 | 227 | The name of a new directory to clone into. The "humanish" |
0879aa28 | 228 | part of the source repository is used if no directory is |
550c66f3 BG |
229 | explicitly given (`repo` for `/path/to/repo.git` and `foo` |
230 | for `host.xz:foo/.git`). Cloning into an existing directory | |
ec00d6e0 | 231 | is only allowed if the directory is empty. |
4607166d | 232 | |
347989f4 | 233 | :git-clone: 1 |
37ba0561 AR |
234 | include::urls.txt[] |
235 | ||
1e2ccd3a | 236 | Examples |
2b5f3ed3 | 237 | -------- |
1e2ccd3a | 238 | |
47638685 | 239 | * Clone from upstream: |
1e2ccd3a JH |
240 | + |
241 | ------------ | |
283efb01 TK |
242 | $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux |
243 | $ cd my-linux | |
1e2ccd3a JH |
244 | $ make |
245 | ------------ | |
246 | ||
247 | ||
47638685 | 248 | * Make a local clone that borrows from the current directory, without checking things out: |
1e2ccd3a JH |
249 | + |
250 | ------------ | |
251 | $ git clone -l -s -n . ../copy | |
a6e3768f | 252 | $ cd ../copy |
1e2ccd3a JH |
253 | $ git show-branch |
254 | ------------ | |
255 | ||
8a1a120c | 256 | |
47638685 | 257 | * Clone from upstream while borrowing from an existing local directory: |
23edecbc SP |
258 | + |
259 | ------------ | |
f22a6543 TK |
260 | $ git clone --reference /git/linux.git \ |
261 | git://git.kernel.org/pub/scm/.../linux.git \ | |
262 | my-linux | |
263 | $ cd my-linux | |
23edecbc SP |
264 | ------------ |
265 | ||
266 | ||
47638685 | 267 | * Create a bare repository to publish your changes to the public: |
8a1a120c JH |
268 | + |
269 | ------------ | |
87e80c4b | 270 | $ git clone --bare -l /home/proj/.git /pub/scm/proj.git |
8a1a120c JH |
271 | ------------ |
272 | ||
273 | ||
6ec311da JH |
274 | GIT |
275 | --- | |
9e1f0a85 | 276 | Part of the linkgit:git[1] suite |