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-rev-list[1]::
163 Lists commit objects in reverse chronological order.
165 gitlink:git-show-index[1]::
166 Displays contents of a pack idx file.
168 gitlink:git-tar-tree[1]::
169 Creates a tar archive of the files in the named tree object.
171 gitlink:git-unpack-file[1]::
172 Creates a temporary file with a blob's contents.
174 gitlink:git-var[1]::
175 Displays a git logical variable.
177 gitlink:git-verify-pack[1]::
178 Validates packed git archive files.
180 In general, the interrogate commands do not touch the files in
181 the working tree.
184 Synching repositories
185 ~~~~~~~~~~~~~~~~~~~~~
187 gitlink:git-clone-pack[1]::
188 Clones a repository into the current repository (engine
189 for ssh and local transport).
191 gitlink:git-fetch-pack[1]::
192 Updates from a remote repository (engine for ssh and
193 local transport).
195 gitlink:git-http-fetch[1]::
196 Downloads a remote git repository via HTTP by walking
197 commit chain.
199 gitlink:git-local-fetch[1]::
200 Duplicates another git repository on a local system by
201 walking commit chain.
203 gitlink:git-peek-remote[1]::
204 Lists references on a remote repository using
205 upload-pack protocol (engine for ssh and local
206 transport).
208 gitlink:git-receive-pack[1]::
209 Invoked by 'git-send-pack' to receive what is pushed to it.
211 gitlink:git-send-pack[1]::
212 Pushes to a remote repository, intelligently.
214 gitlink:git-shell[1]::
215 Restricted shell for GIT-only SSH access.
217 gitlink:git-ssh-fetch[1]::
218 Pulls from a remote repository over ssh connection by
219 walking commit chain.
221 gitlink:git-ssh-upload[1]::
222 Helper "server-side" program used by git-ssh-fetch.
224 gitlink:git-update-server-info[1]::
225 Updates auxiliary information on a dumb server to help
226 clients discover references and packs on it.
228 gitlink:git-upload-pack[1]::
229 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
230 what are asked for.
233 Porcelain-ish Commands
234 ----------------------
236 gitlink:git-add[1]::
237 Add paths to the index.
239 gitlink:git-am[1]::
240 Apply patches from a mailbox, but cooler.
242 gitlink:git-applymbox[1]::
243 Apply patches from a mailbox, original version by Linus.
245 gitlink:git-bisect[1]::
246 Find the change that introduced a bug by binary search.
248 gitlink:git-branch[1]::
249 Create and Show branches.
251 gitlink:git-checkout[1]::
252 Checkout and switch to a branch.
254 gitlink:git-cherry-pick[1]::
255 Cherry-pick the effect of an existing commit.
257 gitlink:git-clone[1]::
258 Clones a repository into a new directory.
260 gitlink:git-commit[1]::
261 Record changes to the repository.
263 gitlink:git-diff[1]::
264 Show changes between commits, commit and working tree, etc.
266 gitlink:git-fetch[1]::
267 Download from a remote repository via various protocols.
269 gitlink:git-format-patch[1]::
270 Prepare patches for e-mail submission.
272 gitlink:git-grep[1]::
273 Print lines matching a pattern.
275 gitlink:git-log[1]::
276 Shows commit logs.
278 gitlink:git-ls-remote[1]::
279 Shows references in a remote or local repository.
281 gitlink:git-merge[1]::
282 Grand unified merge driver.
284 gitlink:git-mv[1]::
285 Move or rename a file, a directory, or a symlink.
287 gitlink:git-octopus[1]::
288 Merge more than two commits.
290 gitlink:git-pull[1]::
291 Fetch from and merge with a remote repository.
293 gitlink:git-push[1]::
294 Update remote refs along with associated objects.
296 gitlink:git-rebase[1]::
297 Rebase local commits to the updated upstream head.
299 gitlink:git-repack[1]::
300 Pack unpacked objects in a repository.
302 gitlink:git-reset[1]::
303 Reset current HEAD to the specified state.
305 gitlink:git-resolve[1]::
306 Merge two commits.
308 gitlink:git-revert[1]::
309 Revert an existing commit.
311 gitlink:git-shortlog[1]::
312 Summarizes 'git log' output.
314 gitlink:git-show-branch[1]::
315 Show branches and their commits.
317 gitlink:git-status[1]::
318 Shows the working tree status.
320 gitlink:git-verify-tag[1]::
321 Check the GPG signature of tag.
323 gitlink:git-whatchanged[1]::
324 Shows commit logs and differences they introduce.
327 Ancillary Commands
328 ------------------
329 Manipulators:
331 gitlink:git-applypatch[1]::
332 Apply one patch extracted from an e-mail.
334 gitlink:git-archimport[1]::
335 Import an arch repository into git.
337 gitlink:git-convert-objects[1]::
338 Converts old-style git repository.
340 gitlink:git-cvsimport[1]::
341 Salvage your data out of another SCM people love to hate.
343 gitlink:git-lost-found[1]::
344 Recover lost refs that luckily have not yet been pruned.
346 gitlink:git-merge-one-file[1]::
347 The standard helper program to use with `git-merge-index`.
349 gitlink:git-prune[1]::
350 Prunes all unreachable objects from the object database.
352 gitlink:git-relink[1]::
353 Hardlink common objects in local repositories.
355 gitlink:git-svnimport[1]::
356 Import a SVN repository into git.
358 gitlink:git-sh-setup[1]::
359 Common git shell script setup code.
361 gitlink:git-symbolic-ref[1]::
362 Read and modify symbolic refs.
364 gitlink:git-tag[1]::
365 An example script to create a tag object signed with GPG.
367 gitlink:git-update-ref[1]::
368 Update the object name stored in a ref safely.
371 Interrogators:
373 gitlink:git-check-ref-format[1]::
374 Make sure ref name is well formed.
376 gitlink:git-cherry[1]::
377 Find commits not merged upstream.
379 gitlink:git-count-objects[1]::
380 Count unpacked number of objects and their disk consumption.
382 gitlink:git-daemon[1]::
383 A really simple server for git repositories.
385 gitlink:git-get-tar-commit-id[1]::
386 Extract commit ID from an archive created using git-tar-tree.
388 gitlink:git-mailinfo[1]::
389 Extracts patch and authorship information from a single
390 e-mail message, optionally transliterating the commit
391 message into utf-8.
393 gitlink:git-mailsplit[1]::
394 A stupid program to split UNIX mbox format mailbox into
395 individual pieces of e-mail.
397 gitlink:git-patch-id[1]::
398 Compute unique ID for a patch.
400 gitlink:git-parse-remote[1]::
401 Routines to help parsing `$GIT_DIR/remotes/` files.
403 gitlink:git-request-pull[1]::
404 git-request-pull.
406 gitlink:git-rev-parse[1]::
407 Pick out and massage parameters.
409 gitlink:git-send-email[1]::
410 Send patch e-mails out of "format-patch --mbox" output.
412 gitlink:git-symbolic-refs[1]::
413 Read and modify symbolic refs.
415 gitlink:git-stripspace[1]::
416 Filter out empty lines.
419 Commands not yet documented
420 ---------------------------
422 gitlink:gitk[1]::
423 The gitk repository browser.
426 Configuration Mechanism
427 -----------------------
429 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
430 is used to hold per-repository configuration options. It is a
431 simple text file modelled after `.ini` format familiar to some
432 people. Here is an example:
434 ------------
435 #
436 # A '#' or ';' character indicates a comment.
437 #
439 ; core variables
440 [core]
441 ; Don't trust file modes
442 filemode = false
444 ; user identity
445 [user]
446 name = "Junio C Hamano"
447 email = "junkio@twinsun.com"
449 ------------
451 Various commands read from the configuration file and adjust
452 their operation accordingly.
455 Identifier Terminology
456 ----------------------
457 <object>::
458 Indicates the object name for any type of object.
460 <blob>::
461 Indicates a blob object name.
463 <tree>::
464 Indicates a tree object name.
466 <commit>::
467 Indicates a commit object name.
469 <tree-ish>::
470 Indicates a tree, commit or tag object name. A
471 command that takes a <tree-ish> argument ultimately wants to
472 operate on a <tree> object but automatically dereferences
473 <commit> and <tag> objects that point at a <tree>.
475 <type>::
476 Indicates that an object type is required.
477 Currently one of: `blob`, `tree`, `commit`, or `tag`.
479 <file>::
480 Indicates a filename - almost always relative to the
481 root of the tree structure `GIT_INDEX_FILE` describes.
483 Symbolic Identifiers
484 --------------------
485 Any git command accepting any <object> can also use the following
486 symbolic notation:
488 HEAD::
489 indicates the head of the current branch (i.e. the
490 contents of `$GIT_DIR/HEAD`).
492 <tag>::
493 a valid tag 'name'
494 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
496 <head>::
497 a valid head 'name'
498 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
500 <snap>::
501 a valid snapshot 'name'
502 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
505 File/Directory Structure
506 ------------------------
508 Please see link:repository-layout.html[repository layout] document.
510 Higher level SCMs may provide and manage additional information in the
511 `$GIT_DIR`.
514 Terminology
515 -----------
516 Please see link:glossary.html[glossary] document.
519 Environment Variables
520 ---------------------
521 Various git commands use the following environment variables:
523 The git Repository
524 ~~~~~~~~~~~~~~~~~~
525 These environment variables apply to 'all' core git commands. Nb: it
526 is worth noting that they may be used/overridden by SCMS sitting above
527 git so take care if using Cogito etc.
529 'GIT_INDEX_FILE'::
530 This environment allows the specification of an alternate
531 index file. If not specified, the default of `$GIT_DIR/index`
532 is used.
534 'GIT_OBJECT_DIRECTORY'::
535 If the object storage directory is specified via this
536 environment variable then the sha1 directories are created
537 underneath - otherwise the default `$GIT_DIR/objects`
538 directory is used.
540 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
541 Due to the immutable nature of git objects, old objects can be
542 archived into shared, read-only directories. This variable
543 specifies a ":" separated list of git object directories which
544 can be used to search for git objects. New objects will not be
545 written to these directories.
547 'GIT_DIR'::
548 If the 'GIT_DIR' environment variable is set then it
549 specifies a path to use instead of the default `.git`
550 for the base of the repository.
552 git Commits
553 ~~~~~~~~~~~
554 'GIT_AUTHOR_NAME'::
555 'GIT_AUTHOR_EMAIL'::
556 'GIT_AUTHOR_DATE'::
557 'GIT_COMMITTER_NAME'::
558 'GIT_COMMITTER_EMAIL'::
559 see gitlink:git-commit-tree[1]
561 git Diffs
562 ~~~~~~~~~
563 'GIT_DIFF_OPTS'::
564 'GIT_EXTERNAL_DIFF'::
565 see the "generating patches" section in :
566 gitlink:git-diff-index[1];
567 gitlink:git-diff-files[1];
568 gitlink:git-diff-tree[1]
570 Discussion[[Discussion]]
571 ------------------------
572 include::../README[]
574 Authors
575 -------
576 git's founding father is Linus Torvalds <torvalds@osdl.org>.
577 The current git nurse is Junio C Hamano <junkio@cox.net>.
578 The git potty was written by Andres Ericsson <ae@op5.se>.
579 General upbringing is handled by the git-list <git@vger.kernel.org>.
581 Documentation
582 --------------
583 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
585 GIT
586 ---
587 Part of the gitlink:git[7] suite