Rename git-config-set to git-repo-config
[git.git] / Documentation / git.txt
bloba5182498633c637d618fd465cd814417a65793fe
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.
41 The <<Discussion>> section below contains much useful definition and
42 clarification info - read that first.  And of the commands, I suggest
43 reading gitlink:git-update-index[1] and
44 gitlink:git-read-tree[1] first - I wish I had!
46 If you are migrating from CVS, link:cvs-migration.html[cvs migration]
47 document may be helpful after you finish the tutorial.
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.
54 David Greaves <david@dgreaves.com>
55 08/05/05
57 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
58 reflect recent changes.
60 Commands Overview
61 -----------------
62 The git commands can helpfully be split into those that manipulate
63 the repository, the index and the working fileset, those that
64 interrogate and compare them, and those that moves objects and
65 references between repositories.
67 In addition, git itself comes with a spartan set of porcelain
68 commands.  They are usable but are not meant to compete with real
69 Porcelains.
71 There are also some ancillary programs that can be viewed as useful
72 aids for using the core commands but which are unlikely to be used by
73 SCMs layered over git.
75 Manipulation commands
76 ~~~~~~~~~~~~~~~~~~~~~
77 gitlink:git-apply[1]::
78         Reads a "diff -up1" or git generated patch file and
79         applies it to the working tree.
81 gitlink:git-checkout-index[1]::
82         Copy files from the index to the working directory
84 gitlink:git-commit-tree[1]::
85         Creates a new commit object
87 gitlink:git-hash-object[1]::
88         Computes the object ID from a file.
90 gitlink:git-index-pack[1]::
91         Build pack index file for an existing packed archive.
93 gitlink:git-init-db[1]::
94         Creates an empty git object database
96 gitlink:git-merge-index[1]::
97         Runs a merge for files needing merging
99 gitlink:git-mktag[1]::
100         Creates a tag object
102 gitlink:git-pack-objects[1]::
103         Creates a packed archive of objects.
105 gitlink:git-prune-packed[1]::
106         Remove extra objects that are already in pack files.
108 gitlink:git-read-tree[1]::
109         Reads tree information into the directory index
111 gitlink:git-repo-config[1]::
112         Get and set options in .git/config.
114 gitlink:git-unpack-objects[1]::
115         Unpacks objects out of a packed archive.
117 gitlink:git-update-index[1]::
118         Modifies the index or directory cache
120 gitlink:git-write-tree[1]::
121         Creates a tree from the current index
124 Interrogation commands
125 ~~~~~~~~~~~~~~~~~~~~~~
127 gitlink:git-cat-file[1]::
128         Provide content or type information for repository objects
130 gitlink:git-diff-index[1]::
131         Compares content and mode of blobs between the index and repository
133 gitlink:git-diff-files[1]::
134         Compares files in the working tree and the index
136 gitlink:git-diff-stages[1]::
137         Compares two "merge stages" in the index file.
139 gitlink:git-diff-tree[1]::
140         Compares the content and mode of blobs found via two tree objects
142 gitlink:git-fsck-objects[1]::
143         Verifies the connectivity and validity of the objects in the database
145 gitlink:git-ls-files[1]::
146         Information about files in the index/working directory
148 gitlink:git-ls-tree[1]::
149         Displays a tree object in human readable form
151 gitlink:git-merge-base[1]::
152         Finds as good a common ancestor as possible for a merge
154 gitlink:git-name-rev[1]::
155         Find symbolic names for given revs
157 gitlink:git-rev-list[1]::
158         Lists commit objects in reverse chronological order
160 gitlink:git-show-index[1]::
161         Displays contents of a pack idx file.
163 gitlink:git-tar-tree[1]::
164         Creates a tar archive of the files in the named tree
166 gitlink:git-unpack-file[1]::
167         Creates a temporary file with a blob's contents
169 gitlink:git-var[1]::
170         Displays a git logical variable
172 gitlink:git-verify-pack[1]::
173         Validates packed git archive files
175 The interrogate commands may create files - and you can force them to
176 touch the working file set - but in general they don't
179 Synching repositories
180 ~~~~~~~~~~~~~~~~~~~~~
182 gitlink:git-clone-pack[1]::
183         Clones a repository into the current repository (engine
184         for ssh and local transport)
186 gitlink:git-fetch-pack[1]::
187         Updates from a remote repository.
189 gitlink:git-http-fetch[1]::
190         Downloads a remote git repository via HTTP
192 gitlink:git-local-fetch[1]::
193         Duplicates another git repository on a local system
195 gitlink:git-peek-remote[1]::
196         Lists references on a remote repository using upload-pack protocol.
198 gitlink:git-receive-pack[1]::
199         Invoked by 'git-send-pack' to receive what is pushed to it.
201 gitlink:git-send-pack[1]::
202         Pushes to a remote repository, intelligently.
204 gitlink:git-shell[1]::
205         Restricted shell for GIT-only SSH access.
207 gitlink:git-ssh-fetch[1]::
208         Pulls from a remote repository over ssh connection
210 gitlink:git-ssh-upload[1]::
211         Helper "server-side" program used by git-ssh-fetch
213 gitlink:git-update-server-info[1]::
214         Updates auxiliary information on a dumb server to help
215         clients discover references and packs on it.
217 gitlink:git-upload-pack[1]::
218         Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
219         what are asked for.
222 Porcelain-ish Commands
223 ----------------------
225 gitlink:git-add[1]::
226         Add paths to the index file.
228 gitlink:git-am[1]::
229         Apply patches from a mailbox, but cooler.
231 gitlink:git-applymbox[1]::
232         Apply patches from a mailbox.
234 gitlink:git-bisect[1]::
235         Find the change that introduced a bug.
237 gitlink:git-branch[1]::
238         Create and Show branches.
240 gitlink:git-checkout[1]::
241         Checkout and switch to a branch.
243 gitlink:git-cherry-pick[1]::
244         Cherry-pick the effect of an existing commit.
246 gitlink:git-clone[1]::
247         Clones a repository into a new directory.
249 gitlink:git-commit[1]::
250         Record changes to the repository.
252 gitlink:git-diff[1]::
253         Show changes between commits, commit and working tree, etc.
255 gitlink:git-fetch[1]::
256         Download from a remote repository via various protocols.
258 gitlink:git-format-patch[1]::
259         Prepare patches for e-mail submission.
261 gitlink:git-grep[1]::
262         Print lines matching a pattern
264 gitlink:git-log[1]::
265         Shows commit logs.
267 gitlink:git-ls-remote[1]::
268         Shows references in a remote or local repository.
270 gitlink:git-merge[1]::
271         Grand unified merge driver.
273 gitlink:git-mv[1]::
274         Move or rename a file, a directory, or a symlink.
276 gitlink:git-octopus[1]::
277         Merge more than two commits.
279 gitlink:git-pull[1]::
280         Fetch from and merge with a remote repository.
282 gitlink:git-push[1]::
283         Update remote refs along with associated objects.
285 gitlink:git-rebase[1]::
286         Rebase local commits to new upstream head.
288 gitlink:git-repack[1]::
289         Pack unpacked objects in a repository.
291 gitlink:git-reset[1]::
292         Reset current HEAD to the specified state.
294 gitlink:git-resolve[1]::
295         Merge two commits.
297 gitlink:git-revert[1]::
298         Revert an existing commit.
300 gitlink:git-shortlog[1]::
301         Summarizes 'git log' output.
303 gitlink:git-show-branch[1]::
304         Show branches and their commits.
306 gitlink:git-status[1]::
307         Shows the working tree status.
309 gitlink:git-verify-tag[1]::
310         Check the GPG signature of tag.
312 gitlink:git-whatchanged[1]::
313         Shows commit logs and differences they introduce.
316 Ancillary Commands
317 ------------------
318 Manipulators:
320 gitlink:git-applypatch[1]::
321         Apply one patch extracted from an e-mail.
323 gitlink:git-archimport[1]::
324         Import an arch repository into git.
326 gitlink:git-convert-objects[1]::
327         Converts old-style git repository
329 gitlink:git-cvsimport[1]::
330         Salvage your data out of another SCM people love to hate.
332 gitlink:git-lost-found[1]::
333         Recover lost refs that luckily have not yet been pruned.
335 gitlink:git-merge-one-file[1]::
336         The standard helper program to use with "git-merge-index"
338 gitlink:git-prune[1]::
339         Prunes all unreachable objects from the object database
341 gitlink:git-relink[1]::
342         Hardlink common objects in local repositories.
344 gitlink:git-svnimport[1]::
345         Import a SVN repository into git.
347 gitlink:git-sh-setup[1]::
348         Common git shell script setup code.
350 gitlink:git-symbolic-ref[1]::
351         Read and modify symbolic refs
353 gitlink:git-tag[1]::
354         An example script to create a tag object signed with GPG
356 gitlink:git-update-ref[1]::
357         Update the object name stored in a ref safely.
360 Interrogators:
362 gitlink:git-check-ref-format[1]::
363         Make sure ref name is well formed.
365 gitlink:git-cherry[1]::
366         Find commits not merged upstream.
368 gitlink:git-count-objects[1]::
369         Count unpacked number of objects and their disk consumption.
371 gitlink:git-daemon[1]::
372         A really simple server for git repositories.
374 gitlink:git-get-tar-commit-id[1]::
375         Extract commit ID from an archive created using git-tar-tree.
377 gitlink:git-mailinfo[1]::
378         Extracts patch from a single e-mail message.
380 gitlink:git-mailsplit[1]::
381         git-mailsplit.
383 gitlink:git-patch-id[1]::
384         Compute unique ID for a patch.
386 gitlink:git-parse-remote[1]::
387         Routines to help parsing $GIT_DIR/remotes/
389 gitlink:git-request-pull[1]::
390         git-request-pull.
392 gitlink:git-rev-parse[1]::
393         Pick out and massage parameters.
395 gitlink:git-send-email[1]::
396         Send patch e-mails out of "format-patch --mbox" output.
398 gitlink:git-symbolic-refs[1]::
399         Read and modify symbolic refs.
401 gitlink:git-stripspace[1]::
402         Filter out empty lines.
405 Commands not yet documented
406 ---------------------------
408 gitlink:gitk[1]::
409         gitk.
412 Configuration Mechanism
413 -----------------------
415 Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file
416 is used to hold per-repository configuration options.  It is a
417 simple text file modelled after `.ini` format familiar to some
418 people.  Here is an example:
420 ------------
422 # This is the config file, and
423 # a '#' or ';' character indicates
424 # a comment
427 ; core variables
428 [core]
429         ; Don't trust file modes
430         filemode = false
432 ; user identity
433 [user]
434         name = "Junio C Hamano"
435         email = "junkio@twinsun.com"
437 ------------
439 Various commands read from the configuration file and adjust
440 their operation accordingly.
443 Identifier Terminology
444 ----------------------
445 <object>::
446         Indicates the sha1 identifier for any type of object
448 <blob>::
449         Indicates a blob object sha1 identifier
451 <tree>::
452         Indicates a tree object sha1 identifier
454 <commit>::
455         Indicates a commit object sha1 identifier
457 <tree-ish>::
458         Indicates a tree, commit or tag object sha1 identifier.  A
459         command that takes a <tree-ish> argument ultimately wants to
460         operate on a <tree> object but automatically dereferences
461         <commit> and <tag> objects that point at a <tree>.
463 <type>::
464         Indicates that an object type is required.
465         Currently one of: blob/tree/commit/tag
467 <file>::
468         Indicates a filename - always relative to the root of
469         the tree structure GIT_INDEX_FILE describes.
471 Symbolic Identifiers
472 --------------------
473 Any git command accepting any <object> can also use the following
474 symbolic notation:
476 HEAD::
477         indicates the head of the repository (ie the contents of
478         `$GIT_DIR/HEAD`)
479 <tag>::
480         a valid tag 'name'+
481         (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
482 <head>::
483         a valid head 'name'+
484         (ie the contents of `$GIT_DIR/refs/heads/<head>`)
485 <snap>::
486         a valid snapshot 'name'+
487         (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
490 File/Directory Structure
491 ------------------------
493 Please see link:repository-layout.html[repository layout] document.
495 Higher level SCMs may provide and manage additional information in the
496 GIT_DIR.
499 Terminology
500 -----------
501 Please see link:glossary.html[glossary] document.
504 Environment Variables
505 ---------------------
506 Various git commands use the following environment variables:
508 The git Repository
509 ~~~~~~~~~~~~~~~~~~
510 These environment variables apply to 'all' core git commands. Nb: it
511 is worth noting that they may be used/overridden by SCMS sitting above
512 git so take care if using Cogito etc
514 'GIT_INDEX_FILE'::
515         This environment allows the specification of an alternate
516         index file. If not specified, the default of `$GIT_DIR/index`
517         is used.
519 'GIT_OBJECT_DIRECTORY'::
520         If the object storage directory is specified via this
521         environment variable then the sha1 directories are created
522         underneath - otherwise the default `$GIT_DIR/objects`
523         directory is used.
525 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
526         Due to the immutable nature of git objects, old objects can be
527         archived into shared, read-only directories. This variable
528         specifies a ":" separated list of git object directories which
529         can be used to search for git objects. New objects will not be
530         written to these directories.
532 'GIT_DIR'::
533         If the 'GIT_DIR' environment variable is set then it specifies
534         a path to use instead of `./.git` for the base of the
535         repository.
537 git Commits
538 ~~~~~~~~~~~
539 'GIT_AUTHOR_NAME'::
540 'GIT_AUTHOR_EMAIL'::
541 'GIT_AUTHOR_DATE'::
542 'GIT_COMMITTER_NAME'::
543 'GIT_COMMITTER_EMAIL'::
544         see gitlink:git-commit-tree[1]
546 git Diffs
547 ~~~~~~~~~
548 'GIT_DIFF_OPTS'::
549 'GIT_EXTERNAL_DIFF'::
550         see the "generating patches" section in :
551         gitlink:git-diff-index[1];
552         gitlink:git-diff-files[1];
553         gitlink:git-diff-tree[1]
555 Discussion[[Discussion]]
556 ------------------------
557 include::../README[]
559 Authors
560 -------
561         git's founding father is Linus Torvalds <torvalds@osdl.org>.
562         The current git nurse is Junio C. Hamano <junkio@cox.net>.
563         The git potty was written by Andres Ericsson <ae@op5.se>.
564         General upbringing is handled by the git-list <git@vger.kernel.org>.
566 Documentation
567 --------------
568 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
572 Part of the gitlink:git[7] suite