1 git(7)
2 ======
4 NAME
5 ----
6 git - the stupid content tracker
9 SYNOPSIS
10 --------
11 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]
13 DESCRIPTION
14 -----------
15 'git' is both a program and a directory content tracker system.
16 The program 'git' is just a wrapper to reach the core git programs
17 (or a potty if you like, as it's not exactly porcelain but still
18 brings your stuff to the plumbing).
20 OPTIONS
21 -------
22 --version::
23 prints the git suite version that the 'git' program came from.
25 --help::
26 prints the synopsis and a list of available commands.
27 If a git command is named this option will bring up the
28 man-page for that command.
30 --exec-path::
31 path to wherever your core git programs are installed.
32 This can also be controlled by setting the GIT_EXEC_PATH
33 environment variable. If no path is given 'git' will print
34 the current setting and then exit.
36 CORE GIT COMMANDS
37 -----------------
38 Before reading this cover to cover, you may want to take a look
39 at the link:tutorial.html[tutorial] document. If you are
40 migrating from CVS, link:cvs-migration.html[cvs migration]
41 document may be helpful after you finish the tutorial.
43 The <<Discussion>> section below contains much useful definition
44 and clarification info - read that first. After that, if you
45 are interested in using git to manage (version control)
46 projects, use link:everyday.html[Everyday GIT] as a guide to the
47 minimum set of commands you need to know for day-to-day work.
49 After you get the general feel from the tutorial and this
50 overview page, you may want to take a look at the
51 link:howto-index.html[howto] documents.
53 If you are writing your own Porcelain, you need to be familiar
54 with most of the low level commands --- I suggest starting from
55 gitlink:git-update-index[1] and gitlink:git-read-tree[1].
58 David Greaves <david@dgreaves.com>
59 08/05/05
61 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 and
62 further on 2005-12-07 to reflect recent changes.
64 Commands Overview
65 -----------------
66 The git commands can helpfully be split into those that manipulate
67 the repository, the index and the files in the working tree, those that
68 interrogate and compare them, and those that moves objects and
69 references between repositories.
71 In addition, git itself comes with a spartan set of porcelain
72 commands. They are usable but are not meant to compete with real
73 Porcelains.
75 There are also some ancillary programs that can be viewed as useful
76 aids for using the core commands but which are unlikely to be used by
77 SCMs layered over git.
79 Manipulation commands
80 ~~~~~~~~~~~~~~~~~~~~~
81 gitlink:git-apply[1]::
82 Reads a "diff -up1" or git generated patch file and
83 applies it to the working tree.
85 gitlink:git-checkout-index[1]::
86 Copy files from the index to the working tree.
88 gitlink:git-commit-tree[1]::
89 Creates a new commit object.
91 gitlink:git-hash-object[1]::
92 Computes the object ID from a file.
94 gitlink:git-index-pack[1]::
95 Build pack idx file for an existing packed archive.
97 gitlink:git-init-db[1]::
98 Creates an empty git object database, or reinitialize an
99 existing one.
101 gitlink:git-merge-index[1]::
102 Runs a merge for files needing merging.
104 gitlink:git-mktag[1]::
105 Creates a tag object.
107 gitlink:git-pack-objects[1]::
108 Creates a packed archive of objects.
110 gitlink:git-prune-packed[1]::
111 Remove extra objects that are already in pack files.
113 gitlink:git-read-tree[1]::
114 Reads tree information into the index.
116 gitlink:git-repo-config[1]::
117 Get and set options in .git/config.
119 gitlink:git-unpack-objects[1]::
120 Unpacks objects out of a packed archive.
122 gitlink:git-update-index[1]::
123 Registers files in the working tree to the index.
125 gitlink:git-write-tree[1]::
126 Creates a tree from the index.
129 Interrogation commands
130 ~~~~~~~~~~~~~~~~~~~~~~
132 gitlink:git-cat-file[1]::
133 Provide content or type/size information for repository objects.
135 gitlink:git-diff-index[1]::
136 Compares content and mode of blobs between the index and repository.
138 gitlink:git-diff-files[1]::
139 Compares files in the working tree and the index.
141 gitlink:git-diff-stages[1]::
142 Compares two "merge stages" in the index.
144 gitlink:git-diff-tree[1]::
145 Compares the content and mode of blobs found via two tree objects.
147 gitlink:git-fsck-objects[1]::
148 Verifies the connectivity and validity of the objects in the database.
150 gitlink:git-ls-files[1]::
151 Information about files in the index and the working tree.
153 gitlink:git-ls-tree[1]::
154 Displays a tree object in human readable form.
156 gitlink:git-merge-base[1]::
157 Finds as good common ancestors as possible for a merge.
159 gitlink:git-name-rev[1]::
160 Find symbolic names for given revs.
162 gitlink:git-pack-redundant[1]::
163 Find redundant pack files.
165 gitlink:git-rev-list[1]::
166 Lists commit objects in reverse chronological order.
168 gitlink:git-show-index[1]::
169 Displays contents of a pack idx file.
171 gitlink:git-tar-tree[1]::
172 Creates a tar archive of the files in the named tree object.
174 gitlink:git-unpack-file[1]::
175 Creates a temporary file with a blob's contents.
177 gitlink:git-var[1]::
178 Displays a git logical variable.
180 gitlink:git-verify-pack[1]::
181 Validates packed git archive files.
183 In general, the interrogate commands do not touch the files in
184 the working tree.
187 Synching repositories
188 ~~~~~~~~~~~~~~~~~~~~~
190 gitlink:git-clone-pack[1]::
191 Clones a repository into the current repository (engine
192 for ssh and local transport).
194 gitlink:git-fetch-pack[1]::
195 Updates from a remote repository (engine for ssh and
196 local transport).
198 gitlink:git-http-fetch[1]::
199 Downloads a remote git repository via HTTP by walking
200 commit chain.
202 gitlink:git-local-fetch[1]::
203 Duplicates another git repository on a local system by
204 walking commit chain.
206 gitlink:git-peek-remote[1]::
207 Lists references on a remote repository using
208 upload-pack protocol (engine for ssh and local
209 transport).
211 gitlink:git-receive-pack[1]::
212 Invoked by 'git-send-pack' to receive what is pushed to it.
214 gitlink:git-send-pack[1]::
215 Pushes to a remote repository, intelligently.
217 gitlink:git-http-push[1]::
218 Push missing objects using HTTP/DAV.
220 gitlink:git-shell[1]::
221 Restricted shell for GIT-only SSH access.
223 gitlink:git-ssh-fetch[1]::
224 Pulls from a remote repository over ssh connection by
225 walking commit chain.
227 gitlink:git-ssh-upload[1]::
228 Helper "server-side" program used by git-ssh-fetch.
230 gitlink:git-update-server-info[1]::
231 Updates auxiliary information on a dumb server to help
232 clients discover references and packs on it.
234 gitlink:git-upload-pack[1]::
235 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
236 what are asked for.
239 Porcelain-ish Commands
240 ----------------------
242 gitlink:git-add[1]::
243 Add paths to the index.
245 gitlink:git-am[1]::
246 Apply patches from a mailbox, but cooler.
248 gitlink:git-applymbox[1]::
249 Apply patches from a mailbox, original version by Linus.
251 gitlink:git-bisect[1]::
252 Find the change that introduced a bug by binary search.
254 gitlink:git-branch[1]::
255 Create and Show branches.
257 gitlink:git-checkout[1]::
258 Checkout and switch to a branch.
260 gitlink:git-cherry-pick[1]::
261 Cherry-pick the effect of an existing commit.
263 gitlink:git-clone[1]::
264 Clones a repository into a new directory.
266 gitlink:git-commit[1]::
267 Record changes to the repository.
269 gitlink:git-diff[1]::
270 Show changes between commits, commit and working tree, etc.
272 gitlink:git-fetch[1]::
273 Download from a remote repository via various protocols.
275 gitlink:git-format-patch[1]::
276 Prepare patches for e-mail submission.
278 gitlink:git-grep[1]::
279 Print lines matching a pattern.
281 gitlink:git-log[1]::
282 Shows commit logs.
284 gitlink:git-ls-remote[1]::
285 Shows references in a remote or local repository.
287 gitlink:git-merge[1]::
288 Grand unified merge driver.
290 gitlink:git-mv[1]::
291 Move or rename a file, a directory, or a symlink.
293 gitlink:git-octopus[1]::
294 Merge more than two commits.
296 gitlink:git-pull[1]::
297 Fetch from and merge with a remote repository.
299 gitlink:git-push[1]::
300 Update remote refs along with associated objects.
302 gitlink:git-rebase[1]::
303 Rebase local commits to the updated upstream head.
305 gitlink:git-repack[1]::
306 Pack unpacked objects in a repository.
308 gitlink:git-reset[1]::
309 Reset current HEAD to the specified state.
311 gitlink:git-resolve[1]::
312 Merge two commits.
314 gitlink:git-revert[1]::
315 Revert an existing commit.
317 gitlink:git-shortlog[1]::
318 Summarizes 'git log' output.
320 gitlink:git-show-branch[1]::
321 Show branches and their commits.
323 gitlink:git-status[1]::
324 Shows the working tree status.
326 gitlink:git-verify-tag[1]::
327 Check the GPG signature of tag.
329 gitlink:git-whatchanged[1]::
330 Shows commit logs and differences they introduce.
333 Ancillary Commands
334 ------------------
335 Manipulators:
337 gitlink:git-applypatch[1]::
338 Apply one patch extracted from an e-mail.
340 gitlink:git-archimport[1]::
341 Import an arch repository into git.
343 gitlink:git-convert-objects[1]::
344 Converts old-style git repository.
346 gitlink:git-cvsimport[1]::
347 Salvage your data out of another SCM people love to hate.
349 gitlink:git-cvsexportcommit[1]::
350 Export a single commit to a CVS checkout.
352 gitlink:git-lost-found[1]::
353 Recover lost refs that luckily have not yet been pruned.
355 gitlink:git-merge-one-file[1]::
356 The standard helper program to use with `git-merge-index`.
358 gitlink:git-prune[1]::
359 Prunes all unreachable objects from the object database.
361 gitlink:git-relink[1]::
362 Hardlink common objects in local repositories.
364 gitlink:git-svnimport[1]::
365 Import a SVN repository into git.
367 gitlink:git-sh-setup[1]::
368 Common git shell script setup code.
370 gitlink:git-symbolic-ref[1]::
371 Read and modify symbolic refs.
373 gitlink:git-tag[1]::
374 An example script to create a tag object signed with GPG.
376 gitlink:git-update-ref[1]::
377 Update the object name stored in a ref safely.
380 Interrogators:
382 gitlink:git-check-ref-format[1]::
383 Make sure ref name is well formed.
385 gitlink:git-cherry[1]::
386 Find commits not merged upstream.
388 gitlink:git-count-objects[1]::
389 Count unpacked number of objects and their disk consumption.
391 gitlink:git-daemon[1]::
392 A really simple server for git repositories.
394 gitlink:git-get-tar-commit-id[1]::
395 Extract commit ID from an archive created using git-tar-tree.
397 gitlink:git-mailinfo[1]::
398 Extracts patch and authorship information from a single
399 e-mail message, optionally transliterating the commit
400 message into utf-8.
402 gitlink:git-mailsplit[1]::
403 A stupid program to split UNIX mbox format mailbox into
404 individual pieces of e-mail.
406 gitlink:git-patch-id[1]::
407 Compute unique ID for a patch.
409 gitlink:git-parse-remote[1]::
410 Routines to help parsing `$GIT_DIR/remotes/` files.
412 gitlink:git-request-pull[1]::
413 git-request-pull.
415 gitlink:git-rev-parse[1]::
416 Pick out and massage parameters.
418 gitlink:git-send-email[1]::
419 Send patch e-mails out of "format-patch --mbox" output.
421 gitlink:git-symbolic-refs[1]::
422 Read and modify symbolic refs.
424 gitlink:git-stripspace[1]::
425 Filter out empty lines.
428 Commands not yet documented
429 ---------------------------
431 gitlink:gitk[1]::
432 The gitk repository browser.
435 Configuration Mechanism
436 -----------------------
438 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
439 is used to hold per-repository configuration options. It is a
440 simple text file modelled after `.ini` format familiar to some
441 people. Here is an example:
443 ------------
444 #
445 # A '#' or ';' character indicates a comment.
446 #
448 ; core variables
449 [core]
450 ; Don't trust file modes
451 filemode = false
453 ; user identity
454 [user]
455 name = "Junio C Hamano"
456 email = "junkio@twinsun.com"
458 ------------
460 Various commands read from the configuration file and adjust
461 their operation accordingly.
464 Identifier Terminology
465 ----------------------
466 <object>::
467 Indicates the object name for any type of object.
469 <blob>::
470 Indicates a blob object name.
472 <tree>::
473 Indicates a tree object name.
475 <commit>::
476 Indicates a commit object name.
478 <tree-ish>::
479 Indicates a tree, commit or tag object name. A
480 command that takes a <tree-ish> argument ultimately wants to
481 operate on a <tree> object but automatically dereferences
482 <commit> and <tag> objects that point at a <tree>.
484 <type>::
485 Indicates that an object type is required.
486 Currently one of: `blob`, `tree`, `commit`, or `tag`.
488 <file>::
489 Indicates a filename - almost always relative to the
490 root of the tree structure `GIT_INDEX_FILE` describes.
492 Symbolic Identifiers
493 --------------------
494 Any git command accepting any <object> can also use the following
495 symbolic notation:
497 HEAD::
498 indicates the head of the current branch (i.e. the
499 contents of `$GIT_DIR/HEAD`).
501 <tag>::
502 a valid tag 'name'
503 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
505 <head>::
506 a valid head 'name'
507 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
509 <snap>::
510 a valid snapshot 'name'
511 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
514 File/Directory Structure
515 ------------------------
517 Please see link:repository-layout.html[repository layout] document.
519 Higher level SCMs may provide and manage additional information in the
520 `$GIT_DIR`.
523 Terminology
524 -----------
525 Please see link:glossary.html[glossary] document.
528 Environment Variables
529 ---------------------
530 Various git commands use the following environment variables:
532 The git Repository
533 ~~~~~~~~~~~~~~~~~~
534 These environment variables apply to 'all' core git commands. Nb: it
535 is worth noting that they may be used/overridden by SCMS sitting above
536 git so take care if using Cogito etc.
538 'GIT_INDEX_FILE'::
539 This environment allows the specification of an alternate
540 index file. If not specified, the default of `$GIT_DIR/index`
541 is used.
543 'GIT_OBJECT_DIRECTORY'::
544 If the object storage directory is specified via this
545 environment variable then the sha1 directories are created
546 underneath - otherwise the default `$GIT_DIR/objects`
547 directory is used.
549 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
550 Due to the immutable nature of git objects, old objects can be
551 archived into shared, read-only directories. This variable
552 specifies a ":" separated list of git object directories which
553 can be used to search for git objects. New objects will not be
554 written to these directories.
556 'GIT_DIR'::
557 If the 'GIT_DIR' environment variable is set then it
558 specifies a path to use instead of the default `.git`
559 for the base of the repository.
561 git Commits
562 ~~~~~~~~~~~
563 'GIT_AUTHOR_NAME'::
564 'GIT_AUTHOR_EMAIL'::
565 'GIT_AUTHOR_DATE'::
566 'GIT_COMMITTER_NAME'::
567 'GIT_COMMITTER_EMAIL'::
568 see gitlink:git-commit-tree[1]
570 git Diffs
571 ~~~~~~~~~
572 'GIT_DIFF_OPTS'::
573 'GIT_EXTERNAL_DIFF'::
574 see the "generating patches" section in :
575 gitlink:git-diff-index[1];
576 gitlink:git-diff-files[1];
577 gitlink:git-diff-tree[1]
579 Discussion[[Discussion]]
580 ------------------------
581 include::../README[]
583 Authors
584 -------
585 git's founding father is Linus Torvalds <torvalds@osdl.org>.
586 The current git nurse is Junio C Hamano <junkio@cox.net>.
587 The git potty was written by Andres Ericsson <ae@op5.se>.
588 General upbringing is handled by the git-list <git@vger.kernel.org>.
590 Documentation
591 --------------
592 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
594 GIT
595 ---
596 Part of the gitlink:git[7] suite