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 index 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 index to the working directory
64 gitlink:git-commit-tree[1]::
65 Creates a new commit object
67 gitlink:git-hash-object[1]::
68 Computes the object ID from a file.
70 gitlink:git-index-pack.html[1]::
71 Build pack index file for an existing packed archive.
73 gitlink:git-init-db[1]::
74 Creates an empty git object database
76 gitlink:git-merge-index[1]::
77 Runs a merge for files needing merging
79 gitlink:git-mktag[1]::
80 Creates a tag object
82 gitlink:git-pack-objects[1]::
83 Creates a packed archive of objects.
85 gitlink:git-prune-packed[1]::
86 Remove extra objects that are already in pack files.
88 gitlink:git-read-tree[1]::
89 Reads tree information into the directory index
91 gitlink:git-unpack-objects[1]::
92 Unpacks objects out of a packed archive.
94 gitlink:git-update-index[1]::
95 Modifies the index or directory cache
97 gitlink:git-write-tree[1]::
98 Creates a tree from the current index
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 index and repository
110 gitlink:git-diff-files[1]::
111 Compares files in the working tree and the index
113 gitlink:git-diff-stages[1]::
114 Compares two "merge stages" in the index file.
116 gitlink:git-diff-tree[1]::
117 Compares the content and mode of blobs found via two tree objects
119 gitlink:git-fsck-objects[1]::
120 Verifies the connectivity and validity of the objects in the database
122 gitlink:git-ls-files[1]::
123 Information about files in the index/working directory
125 gitlink:git-ls-tree[1]::
126 Displays a tree object in human readable form
128 gitlink:git-merge-base[1]::
129 Finds as good a common ancestor as possible for a merge
131 gitlink:git-name-rev[1]::
132 Find symbolic names for given revs
134 gitlink:git-rev-list[1]::
135 Lists commit objects in reverse chronological order
137 gitlink:git-show-index[1]::
138 Displays contents of a pack idx file.
140 gitlink:git-tar-tree[1]::
141 Creates a tar archive of the files in the named tree
143 gitlink:git-unpack-file[1]::
144 Creates a temporary file with a blob's contents
146 gitlink:git-var[1]::
147 Displays a git logical variable
149 gitlink:git-verify-pack[1]::
150 Validates packed git archive files
152 The interrogate commands may create files - and you can force them to
153 touch the working file set - but in general they don't
156 Synching repositories
157 ~~~~~~~~~~~~~~~~~~~~~
159 gitlink:git-clone-pack[1]::
160 Clones a repository into the current repository (engine
161 for ssh and local transport)
163 gitlink:git-fetch-pack[1]::
164 Updates from a remote repository.
166 gitlink:git-http-fetch[1]::
167 Downloads a remote git repository via HTTP
169 gitlink:git-local-fetch[1]::
170 Duplicates another git repository on a local system
172 gitlink:git-peek-remote[1]::
173 Lists references on a remote repository using upload-pack protocol.
175 gitlink:git-receive-pack[1]::
176 Invoked by 'git-send-pack' to receive what is pushed to it.
178 gitlink:git-send-pack[1]::
179 Pushes to a remote repository, intelligently.
181 gitlink:git-shell[1]::
182 Restricted shell for GIT-only SSH access.
184 gitlink:git-ssh-fetch[1]::
185 Pulls from a remote repository over ssh connection
187 gitlink:git-ssh-upload[1]::
188 Helper "server-side" program used by git-ssh-fetch
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.
205 gitlink:git-am[1]::
206 Apply patches from a mailbox, but cooler.
208 gitlink:git-applymbox[1]::
209 Apply patches from a mailbox.
211 gitlink:git-bisect[1]::
212 Find the change that introduced a bug.
214 gitlink:git-branch[1]::
215 Create and Show branches.
217 gitlink:git-checkout[1]::
218 Checkout and switch to a branch.
220 gitlink:git-cherry-pick[1]::
221 Cherry-pick the effect of an existing commit.
223 gitlink:git-clone[1]::
224 Clones a repository into a new directory.
226 gitlink:git-commit[1]::
227 Record changes to the repository.
229 gitlink:git-diff[1]::
230 Show changes between commits, commit and working tree, etc.
232 gitlink:git-fetch[1]::
233 Download from a remote repository via various protocols.
235 gitlink:git-format-patch[1]::
236 Prepare patches for e-mail submission.
238 gitlink:git-grep[1]::
239 Print lines matching a pattern
241 gitlink:git-log[1]::
242 Shows commit logs.
244 gitlink:git-ls-remote[1]::
245 Shows references in a remote or local repository.
247 gitlink:git-merge[1]::
248 Grand unified merge driver.
250 gitlink:git-mv[1]::
251 Move or rename a file, a directory, or a symlink.
253 gitlink:git-octopus[1]::
254 Merge more than two commits.
256 gitlink:git-pull[1]::
257 Fetch from and merge with a remote repository.
259 gitlink:git-push[1]::
260 Update remote refs along with associated objects.
262 gitlink:git-rebase[1]::
263 Rebase local commits to new upstream head.
265 gitlink:git-rename[1]::
266 Rename files and directories.
268 gitlink:git-repack[1]::
269 Pack unpacked objects in a repository.
271 gitlink:git-reset[1]::
272 Reset current HEAD to the specified state.
274 gitlink:git-resolve[1]::
275 Merge two commits.
277 gitlink:git-revert[1]::
278 Revert an existing commit.
280 gitlink:git-shortlog[1]::
281 Summarizes 'git log' output.
283 gitlink:git-show-branch[1]::
284 Show branches and their commits.
286 gitlink:git-status[1]::
287 Shows the working tree status.
289 gitlink:git-verify-tag[1]::
290 Check the GPG signature of tag.
292 gitlink:git-whatchanged[1]::
293 Shows commit logs and differences they introduce.
296 Ancillary Commands
297 ------------------
298 Manipulators:
300 gitlink:git-applypatch[1]::
301 Apply one patch extracted from an e-mail.
303 gitlink:git-archimport[1]::
304 Import an arch repository into git.
306 gitlink:git-convert-objects[1]::
307 Converts old-style git repository
309 gitlink:git-cvsimport[1]::
310 Salvage your data out of another SCM people love to hate.
312 gitlink:git-lost+found[1]::
313 Recover lost refs that luckily have not yet been pruned.
315 gitlink:git-merge-one-file[1]::
316 The standard helper program to use with "git-merge-index"
318 gitlink:git-prune[1]::
319 Prunes all unreachable objects from the object database
321 gitlink:git-relink[1]::
322 Hardlink common objects in local repositories.
324 gitlink:git-svnimport[1]::
325 Import a SVN repository into git.
327 gitlink:git-sh-setup[1]::
328 Common git shell script setup code.
330 gitlink:git-symbolic-ref[1]::
331 Read and modify symbolic refs
333 gitlink:git-tag[1]::
334 An example script to create a tag object signed with GPG
336 gitlink:git-update-ref[1]::
337 Update the object name stored in a ref safely.
340 Interrogators:
342 gitlink:git-check-ref-format[1]::
343 Make sure ref name is well formed.
345 gitlink:git-cherry[1]::
346 Find commits not merged upstream.
348 gitlink:git-count-objects[1]::
349 Count unpacked number of objects and their disk consumption.
351 gitlink:git-daemon[1]::
352 A really simple server for git repositories.
354 gitlink:git-get-tar-commit-id[1]::
355 Extract commit ID from an archive created using git-tar-tree.
357 gitlink:git-mailinfo[1]::
358 Extracts patch from a single e-mail message.
360 gitlink:git-mailsplit[1]::
361 git-mailsplit.
363 gitlink:git-patch-id[1]::
364 Compute unique ID for a patch.
366 gitlink:git-parse-remote[1]::
367 Routines to help parsing $GIT_DIR/remotes/
369 gitlink:git-request-pull[1]::
370 git-request-pull.
372 gitlink:git-rev-parse[1]::
373 Pick out and massage parameters.
375 gitlink:git-send-email[1]::
376 Send patch e-mails out of "format-patch --mbox" output.
378 gitlink:git-symbolic-refs[1]::
379 Read and modify symbolic refs.
381 gitlink:git-stripspace[1]::
382 Filter out empty lines.
385 Commands not yet documented
386 ---------------------------
388 gitlink:gitk[1]::
389 gitk.
392 Configuration Mechanism
393 -----------------------
395 Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file
396 is used to hold per-repository configuration options. It is a
397 simple text file modelled after `.ini` format familiar to some
398 people. Here is an example:
400 ------------
401 #
402 # This is the config file, and
403 # a '#' or ';' character indicates
404 # a comment
405 #
407 ; core variables
408 [core]
409 ; Don't trust file modes
410 filemode = false
412 ; user identity
413 [user]
414 name = "Junio C Hamano"
415 email = "junkio@twinsun.com"
417 ------------
419 Various commands read from the configuration file and adjust
420 their operation accordingly.
423 Identifier Terminology
424 ----------------------
425 <object>::
426 Indicates the sha1 identifier for any type of object
428 <blob>::
429 Indicates a blob object sha1 identifier
431 <tree>::
432 Indicates a tree object sha1 identifier
434 <commit>::
435 Indicates a commit object sha1 identifier
437 <tree-ish>::
438 Indicates a tree, commit or tag object sha1 identifier. A
439 command that takes a <tree-ish> argument ultimately wants to
440 operate on a <tree> object but automatically dereferences
441 <commit> and <tag> objects that point at a <tree>.
443 <type>::
444 Indicates that an object type is required.
445 Currently one of: blob/tree/commit/tag
447 <file>::
448 Indicates a filename - always relative to the root of
449 the tree structure GIT_INDEX_FILE describes.
451 Symbolic Identifiers
452 --------------------
453 Any git command accepting any <object> can also use the following
454 symbolic notation:
456 HEAD::
457 indicates the head of the repository (ie the contents of
458 `$GIT_DIR/HEAD`)
459 <tag>::
460 a valid tag 'name'+
461 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
462 <head>::
463 a valid head 'name'+
464 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
465 <snap>::
466 a valid snapshot 'name'+
467 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
470 File/Directory Structure
471 ------------------------
473 Please see link:repository-layout.html[repository layout] document.
475 Higher level SCMs may provide and manage additional information in the
476 GIT_DIR.
479 Terminology
480 -----------
481 Please see link:glossary.html[glossary] document.
484 Environment Variables
485 ---------------------
486 Various git commands use the following environment variables:
488 The git Repository
489 ~~~~~~~~~~~~~~~~~~
490 These environment variables apply to 'all' core git commands. Nb: it
491 is worth noting that they may be used/overridden by SCMS sitting above
492 git so take care if using Cogito etc
494 'GIT_INDEX_FILE'::
495 This environment allows the specification of an alternate
496 index file. If not specified, the default of `$GIT_DIR/index`
497 is used.
499 'GIT_OBJECT_DIRECTORY'::
500 If the object storage directory is specified via this
501 environment variable then the sha1 directories are created
502 underneath - otherwise the default `$GIT_DIR/objects`
503 directory is used.
505 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
506 Due to the immutable nature of git objects, old objects can be
507 archived into shared, read-only directories. This variable
508 specifies a ":" separated list of git object directories which
509 can be used to search for git objects. New objects will not be
510 written to these directories.
512 'GIT_DIR'::
513 If the 'GIT_DIR' environment variable is set then it specifies
514 a path to use instead of `./.git` for the base of the
515 repository.
517 git Commits
518 ~~~~~~~~~~~
519 'GIT_AUTHOR_NAME'::
520 'GIT_AUTHOR_EMAIL'::
521 'GIT_AUTHOR_DATE'::
522 'GIT_COMMITTER_NAME'::
523 'GIT_COMMITTER_EMAIL'::
524 see gitlink:git-commit-tree[1]
526 git Diffs
527 ~~~~~~~~~
528 'GIT_DIFF_OPTS'::
529 'GIT_EXTERNAL_DIFF'::
530 see the "generating patches" section in :
531 gitlink:git-diff-index[1];
532 gitlink:git-diff-files[1];
533 gitlink:git-diff-tree[1]
535 Discussion[[Discussion]]
536 ------------------------
537 include::../README[]
539 Author
540 ------
541 Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
543 Documentation
544 --------------
545 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
547 GIT
548 ---
549 Part of the gitlink:git[7] suite