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