f8dd76ac24db980facefe95f6139707100dfabb6
1 git(7)
2 ======
4 NAME
5 ----
6 git - the stupid content tracker
9 SYNOPSIS
10 --------
11 'git-<command>' <args>
13 DESCRIPTION
14 -----------
16 This is reference information for the core git commands.
18 Before reading this cover to cover, you may want to take a look
19 at the link:tutorial.html[tutorial] document.
21 The <<Discussion>> section below contains much useful definition and
22 clarification info - read that first. And of the commands, I suggest
23 reading gitlink:git-update-index[1] and
24 gitlink:git-read-tree[1] first - I wish I had!
26 If you are migrating from CVS, link:cvs-migration.html[cvs migration]
27 document may be helpful after you finish the tutorial.
29 After you get the general feel from the tutorial and this
30 overview page, you may want to take a look at the
31 link:howto-index.html[howto] documents.
34 David Greaves <david@dgreaves.com>
35 08/05/05
37 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
38 reflect recent changes.
40 Commands Overview
41 -----------------
42 The git commands can helpfully be split into those that manipulate
43 the repository, the cache and the working fileset, those that
44 interrogate and compare them, and those that moves objects and
45 references between repositories.
47 In addition, git itself comes with a spartan set of porcelain
48 commands. They are usable but are not meant to compete with real
49 Porcelains.
51 There are also some ancillary programs that can be viewed as useful
52 aids for using the core commands but which are unlikely to be used by
53 SCMs layered over git.
55 Manipulation commands
56 ~~~~~~~~~~~~~~~~~~~~~
57 gitlink:git-apply[1]::
58 Reads a "diff -up1" or git generated patch file and
59 applies it to the working tree.
61 gitlink:git-checkout-index[1]::
62 Copy files from the cache to the working directory
63 Previously this command was known as git-checkout-cache.
65 gitlink:git-commit-tree[1]::
66 Creates a new commit object
68 gitlink:git-hash-object[1]::
69 Computes the object ID from a file.
71 gitlink:git-init-db[1]::
72 Creates an empty git object database
74 gitlink:git-merge-index[1]::
75 Runs a merge for files needing merging
76 Previously this command was known as git-merge-cache.
78 gitlink:git-mktag[1]::
79 Creates a tag object
81 gitlink:git-pack-objects[1]::
82 Creates a packed archive of objects.
84 gitlink:git-prune-packed[1]::
85 Remove extra objects that are already in pack files.
87 gitlink:git-read-tree[1]::
88 Reads tree information into the directory cache
90 gitlink:git-unpack-objects[1]::
91 Unpacks objects out of a packed archive.
93 gitlink:git-update-index[1]::
94 Modifies the index or directory cache
95 Previously this command was known as git-update-cache.
97 gitlink:git-write-tree[1]::
98 Creates a tree from the current cache
101 Interrogation commands
102 ~~~~~~~~~~~~~~~~~~~~~~
104 gitlink:git-cat-file[1]::
105 Provide content or type information for repository objects
107 gitlink:git-diff-index[1]::
108 Compares content and mode of blobs between the cache and repository
109 Previously this command was known as git-diff-cache.
111 gitlink:git-diff-files[1]::
112 Compares files in the working tree and the cache
114 gitlink:git-diff-stages[1]::
115 Compares two "merge stages" in the index file.
117 gitlink:git-diff-tree[1]::
118 Compares the content and mode of blobs found via two tree objects
120 gitlink:git-fsck-objects[1]::
121 Verifies the connectivity and validity of the objects in the database
122 Previously this command was known as git-fsck-cache.
124 gitlink:git-ls-files[1]::
125 Information about files in the cache/working directory
127 gitlink:git-ls-tree[1]::
128 Displays a tree object in human readable form
130 gitlink:git-merge-base[1]::
131 Finds as good a common ancestor as possible for a merge
133 gitlink:git-rev-list[1]::
134 Lists commit objects in reverse chronological order
136 gitlink:git-show-index[1]::
137 Displays contents of a pack idx file.
139 gitlink:git-tar-tree[1]::
140 Creates a tar archive of the files in the named tree
142 gitlink:git-unpack-file[1]::
143 Creates a temporary file with a blob's contents
145 gitlink:git-var[1]::
146 Displays a git logical variable
148 gitlink:git-verify-pack[1]::
149 Validates packed GIT archive files
151 The interrogate commands may create files - and you can force them to
152 touch the working file set - but in general they don't
155 Synching repositories
156 ~~~~~~~~~~~~~~~~~~~~~
158 gitlink:git-clone-pack[1]::
159 Clones a repository into the current repository (engine
160 for ssh and local transport)
162 gitlink:git-fetch-pack[1]::
163 Updates from a remote repository.
165 gitlink:git-http-fetch[1]::
166 Downloads a remote GIT repository via HTTP
167 Previously this command was known as git-http-pull.
169 gitlink:git-local-fetch[1]::
170 Duplicates another GIT repository on a local system
171 Previously this command was known as git-local-pull.
173 gitlink:git-peek-remote[1]::
174 Lists references on a remote repository using upload-pack protocol.
176 gitlink:git-receive-pack[1]::
177 Invoked by 'git-send-pack' to receive what is pushed to it.
179 gitlink:git-send-pack[1]::
180 Pushes to a remote repository, intelligently.
182 gitlink:git-ssh-fetch[1]::
183 Pulls from a remote repository over ssh connection
184 Previously this command was known as git-ssh-pull.
186 gitlink:git-ssh-upload[1]::
187 Helper "server-side" program used by git-ssh-fetch
188 Previously this command was known as git-ssh-push.
190 gitlink:git-update-server-info[1]::
191 Updates auxiliary information on a dumb server to help
192 clients discover references and packs on it.
194 gitlink:git-upload-pack[1]::
195 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
196 what are asked for.
199 Porcelain-ish Commands
200 ----------------------
202 gitlink:git-add[1]::
203 Add paths to the index file.
204 Previously this command was known as git-add-script.
206 gitlink:git-applymbox[1]::
207 Apply patches from a mailbox.
209 gitlink:git-bisect[1]::
210 Find the change that introduced a bug.
211 Previously this command was known as git-bisect-script.
213 gitlink:git-branch[1]::
214 Create and Show branches.
215 Previously this command was known as git-branch-script.
217 gitlink:git-checkout[1]::
218 Checkout and switch to a branch.
219 Previously this command was known as git-checkout-script.
221 gitlink:git-cherry-pick[1]::
222 Cherry-pick the effect of an existing commit.
223 Previously this command was known as git-cherry-pick-script.
225 gitlink:git-clone[1]::
226 Clones a repository into a new directory.
227 Previously this command was known as git-clone-script.
229 gitlink:git-commit[1]::
230 Record changes to the repository.
231 Previously this command was known as git-commit-script.
233 gitlink:git-diff[1]::
234 Show changes between commits, commit and working tree, etc.
235 Previously this command was known as git-diff-script.
237 gitlink:git-fetch[1]::
238 Download from a remote repository via various protocols.
239 Previously this command was known as git-fetch-script.
241 gitlink:git-format-patch[1]::
242 Prepare patches for e-mail submission.
243 Previously this command was known as git-format-patch-script.
245 gitlink:git-grep[1]::
246 Print lines matching a pattern
248 gitlink:git-log[1]::
249 Shows commit logs.
250 Previously this command was known as git-log-script.
252 gitlink:git-ls-remote[1]::
253 Shows references in a remote or local repository.
254 Previously this command was known as git-ls-remote-script.
256 gitlink:git-merge[1]::
257 Grand unified merge driver.
259 gitlink:git-octopus[1]::
260 Merge more than two commits.
261 Previously this command was known as git-octopus-script.
263 gitlink:git-pull[1]::
264 Fetch from and merge with a remote repository.
265 Previously this command was known as git-pull-script.
267 gitlink:git-push[1]::
268 Update remote refs along with associated objects.
269 Previously this command was known as git-push-script.
271 gitlink:git-rebase[1]::
272 Rebase local commits to new upstream head.
273 Previously this command was known as git-rebase-script.
275 gitlink:git-rename[1]::
276 Rename files and directories.
277 Previously this command was known as git-rename-script.
279 gitlink:git-repack[1]::
280 Pack unpacked objects in a repository.
281 Previously this command was known as git-repack-script.
283 gitlink:git-reset[1]::
284 Reset current HEAD to the specified state.
285 Previously this command was known as git-reset-script.
287 gitlink:git-resolve[1]::
288 Merge two commits.
289 Previously this command was known as git-resolve-script.
291 gitlink:git-revert[1]::
292 Revert an existing commit.
293 Previously this command was known as git-revert-script.
295 gitlink:git-shortlog[1]::
296 Summarizes 'git log' output.
298 gitlink:git-show-branch[1]::
299 Show branches and their commits.
301 gitlink:git-status[1]::
302 Shows the working tree status.
303 Previously this command was known as git-status-script.
305 gitlink:git-verify-tag[1]::
306 Check the GPG signature of tag.
307 Previously this command was known as git-verify-tag-script.
309 gitlink:git-whatchanged[1]::
310 Shows commit logs and differences they introduce.
313 Ancillary Commands
314 ------------------
315 Manipulators:
317 gitlink:git-applypatch[1]::
318 Apply one patch extracted from an e-mail.
320 gitlink:git-archimport[1]::
321 Import an arch repository into git.
322 Previously this command was known as git-archimport-script.
324 gitlink:git-convert-objects[1]::
325 Converts old-style GIT repository
326 Previously this command was known as git-convert-cache.
328 gitlink:git-cvsimport[1]::
329 Salvage your data out of another SCM people love to hate.
330 Previously this command was known as git-cvsimport-script.
332 gitlink:git-merge-one-file[1]::
333 The standard helper program to use with "git-merge-index"
334 Previously this command was known as git-merge-one-file-script.
336 gitlink:git-prune[1]::
337 Prunes all unreachable objects from the object database
338 Previously this command was known as git-prune-script.
340 gitlink:git-relink[1]::
341 Hardlink common objects in local repositories.
342 Previously this command was known as git-relink-script.
344 gitlink:git-sh-setup[1]::
345 Common git shell script setup code.
346 Previously this command was known as git-sh-setup-script.
348 gitlink:git-tag[1]::
349 An example script to create a tag object signed with GPG
350 Previously this command was known as git-tag-script.
353 Interrogators:
355 gitlink:git-cherry[1]::
356 Find commits not merged upstream.
358 gitlink:git-count-objects[1]::
359 Count unpacked number of objects and their disk consumption.
360 Previously this command was known as git-count-objects-script.
362 gitlink:git-daemon[1]::
363 A really simple server for GIT repositories.
365 gitlink:git-get-tar-commit-id[1]::
366 Extract commit ID from an archive created using git-tar-tree.
368 gitlink:git-mailinfo[1]::
369 Extracts patch from a single e-mail message.
371 gitlink:git-mailsplit[1]::
372 git-mailsplit.
374 gitlink:git-patch-id[1]::
375 Compute unique ID for a patch.
377 gitlink:git-parse-remote[1]::
378 Routines to help parsing $GIT_DIR/remotes/
379 Previously this command was known as git-parse-remote-script.
381 gitlink:git-request-pull[1]::
382 git-request-pull.
383 Previously this command was known as git-request-pull-script.
385 gitlink:git-rev-parse[1]::
386 Pick out and massage parameters.
388 gitlink:git-send-email[1]::
389 Send patch e-mails out of "format-patch --mbox" output.
390 Previously this command was known as git-send-email-script.
392 gitlink:git-stripspace[1]::
393 Filter out empty lines.
396 Commands not yet documented
397 ---------------------------
399 gitlink:gitk[1]::
400 gitk.
403 Identifier Terminology
404 ----------------------
405 <object>::
406 Indicates the sha1 identifier for any type of object
408 <blob>::
409 Indicates a blob object sha1 identifier
411 <tree>::
412 Indicates a tree object sha1 identifier
414 <commit>::
415 Indicates a commit object sha1 identifier
417 <tree-ish>::
418 Indicates a tree, commit or tag object sha1 identifier. A
419 command that takes a <tree-ish> argument ultimately wants to
420 operate on a <tree> object but automatically dereferences
421 <commit> and <tag> objects that point at a <tree>.
423 <type>::
424 Indicates that an object type is required.
425 Currently one of: blob/tree/commit/tag
427 <file>::
428 Indicates a filename - always relative to the root of
429 the tree structure GIT_INDEX_FILE describes.
431 Symbolic Identifiers
432 --------------------
433 Any git command accepting any <object> can also use the following
434 symbolic notation:
436 HEAD::
437 indicates the head of the repository (ie the contents of
438 `$GIT_DIR/HEAD`)
439 <tag>::
440 a valid tag 'name'+
441 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
442 <head>::
443 a valid head 'name'+
444 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
445 <snap>::
446 a valid snapshot 'name'+
447 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
450 File/Directory Structure
451 ------------------------
453 Please see link:repository-layout.html[repository layout] document.
455 Higher level SCMs may provide and manage additional information in the
456 GIT_DIR.
459 Terminology
460 -----------
461 Please see link:glossary.html[glossary] document.
464 Environment Variables
465 ---------------------
466 Various git commands use the following environment variables:
468 The git Repository
469 ~~~~~~~~~~~~~~~~~~
470 These environment variables apply to 'all' core git commands. Nb: it
471 is worth noting that they may be used/overridden by SCMS sitting above
472 git so take care if using Cogito etc
474 'GIT_INDEX_FILE'::
475 This environment allows the specification of an alternate
476 cache/index file. If not specified, the default of
477 `$GIT_DIR/index` is used.
479 'GIT_OBJECT_DIRECTORY'::
480 If the object storage directory is specified via this
481 environment variable then the sha1 directories are created
482 underneath - otherwise the default `$GIT_DIR/objects`
483 directory is used.
485 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
486 Due to the immutable nature of git objects, old objects can be
487 archived into shared, read-only directories. This variable
488 specifies a ":" separated list of git object directories which
489 can be used to search for git objects. New objects will not be
490 written to these directories.
492 'GIT_DIR'::
493 If the 'GIT_DIR' environment variable is set then it specifies
494 a path to use instead of `./.git` for the base of the
495 repository.
497 git Commits
498 ~~~~~~~~~~~
499 'GIT_AUTHOR_NAME'::
500 'GIT_AUTHOR_EMAIL'::
501 'GIT_AUTHOR_DATE'::
502 'GIT_COMMITTER_NAME'::
503 'GIT_COMMITTER_EMAIL'::
504 see gitlink:git-commit-tree[1]
506 git Diffs
507 ~~~~~~~~~
508 'GIT_DIFF_OPTS'::
509 'GIT_EXTERNAL_DIFF'::
510 see the "generating patches" section in :
511 gitlink:git-diff-index[1];
512 gitlink:git-diff-files[1];
513 gitlink:git-diff-tree[1]
515 Discussion[[Discussion]]
516 ------------------------
517 include::../README[]
519 Author
520 ------
521 Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
523 Documentation
524 --------------
525 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
527 GIT
528 ---
529 Part of the gitlink:git[7] suite