GIT 1.1.3
[git.git] / Documentation / git.txt
1 git(7)
2 ======
3
4 NAME
5 ----
6 git - the stupid content tracker
7
8
9 SYNOPSIS
10 --------
11 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]
12
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).
19
20 OPTIONS
21 -------
22 --version::
23         prints the git suite version that the 'git' program came from.
24
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.
29
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.
35
36
37 NOT LEARNING CORE GIT COMMANDS
38 ------------------------------
39
40 This manual is intended to give complete background information
41 and internal workings of git, which may be too much for most
42 people.  The <<Discussion>> section below contains much useful
43 definition and clarification - read that first.
44
45 If you 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.
48 Most likely, that will get you started, and you can go a long
49 way without knowing the low level details too much.
50
51 The link:tutorial.html[tutorial] document covers how things
52 internally work.
53
54 If you are migrating from CVS, link:cvs-migration.html[cvs
55 migration] document may be helpful after you finish the
56 tutorial.
57
58 After you get the general feel from the tutorial and this
59 overview page, you may want to take a look at the
60 link:howto-index.html[howto] documents.
61
62
63 CORE GIT COMMANDS
64 -----------------
65
66 If you are writing your own Porcelain, you need to be familiar
67 with most of the low level commands --- I suggest starting from
68 gitlink:git-update-index[1] and gitlink:git-read-tree[1].
69
70
71 Commands Overview
72 -----------------
73 The git commands can helpfully be split into those that manipulate
74 the repository, the index and the files in the working tree, those that
75 interrogate and compare them, and those that moves objects and
76 references between repositories.
77
78 In addition, git itself comes with a spartan set of porcelain
79 commands.  They are usable but are not meant to compete with real
80 Porcelains.
81
82 There are also some ancillary programs that can be viewed as useful
83 aids for using the core commands but which are unlikely to be used by
84 SCMs layered over git.
85
86 Manipulation commands
87 ~~~~~~~~~~~~~~~~~~~~~
88 gitlink:git-apply[1]::
89         Reads a "diff -up1" or git generated patch file and
90         applies it to the working tree.
91
92 gitlink:git-checkout-index[1]::
93         Copy files from the index to the working tree.
94
95 gitlink:git-commit-tree[1]::
96         Creates a new commit object.
97
98 gitlink:git-hash-object[1]::
99         Computes the object ID from a file.
100
101 gitlink:git-index-pack[1]::
102         Build pack idx file for an existing packed archive.
103
104 gitlink:git-init-db[1]::
105         Creates an empty git object database, or reinitialize an
106         existing one.
107
108 gitlink:git-merge-index[1]::
109         Runs a merge for files needing merging.
110
111 gitlink:git-mktag[1]::
112         Creates a tag object.
113
114 gitlink:git-pack-objects[1]::
115         Creates a packed archive of objects.
116
117 gitlink:git-prune-packed[1]::
118         Remove extra objects that are already in pack files.
119
120 gitlink:git-read-tree[1]::
121         Reads tree information into the index.
122
123 gitlink:git-repo-config[1]::
124         Get and set options in .git/config.
125
126 gitlink:git-unpack-objects[1]::
127         Unpacks objects out of a packed archive.
128
129 gitlink:git-update-index[1]::
130         Registers files in the working tree to the index.
131
132 gitlink:git-write-tree[1]::
133         Creates a tree from the index.
134
135
136 Interrogation commands
137 ~~~~~~~~~~~~~~~~~~~~~~
138
139 gitlink:git-cat-file[1]::
140         Provide content or type/size information for repository objects.
141
142 gitlink:git-describe[1]::
143         Show the most recent tag that is reachable from a commit.
144
145 gitlink:git-diff-index[1]::
146         Compares content and mode of blobs between the index and repository.
147
148 gitlink:git-diff-files[1]::
149         Compares files in the working tree and the index.
150
151 gitlink:git-diff-stages[1]::
152         Compares two "merge stages" in the index.
153
154 gitlink:git-diff-tree[1]::
155         Compares the content and mode of blobs found via two tree objects.
156
157 gitlink:git-fsck-objects[1]::
158         Verifies the connectivity and validity of the objects in the database.
159
160 gitlink:git-ls-files[1]::
161         Information about files in the index and the working tree.
162
163 gitlink:git-ls-tree[1]::
164         Displays a tree object in human readable form.
165
166 gitlink:git-merge-base[1]::
167         Finds as good common ancestors as possible for a merge.
168
169 gitlink:git-name-rev[1]::
170         Find symbolic names for given revs.
171
172 gitlink:git-pack-redundant[1]::
173         Find redundant pack files.
174
175 gitlink:git-rev-list[1]::
176         Lists commit objects in reverse chronological order.
177
178 gitlink:git-show-index[1]::
179         Displays contents of a pack idx file.
180
181 gitlink:git-tar-tree[1]::
182         Creates a tar archive of the files in the named tree object.
183
184 gitlink:git-unpack-file[1]::
185         Creates a temporary file with a blob's contents.
186
187 gitlink:git-var[1]::
188         Displays a git logical variable.
189
190 gitlink:git-verify-pack[1]::
191         Validates packed git archive files.
192
193 In general, the interrogate commands do not touch the files in
194 the working tree.
195
196
197 Synching repositories
198 ~~~~~~~~~~~~~~~~~~~~~
199
200 gitlink:git-clone-pack[1]::
201         Clones a repository into the current repository (engine
202         for ssh and local transport).
203
204 gitlink:git-fetch-pack[1]::
205         Updates from a remote repository (engine for ssh and
206         local transport).
207
208 gitlink:git-http-fetch[1]::
209         Downloads a remote git repository via HTTP by walking
210         commit chain.
211
212 gitlink:git-local-fetch[1]::
213         Duplicates another git repository on a local system by
214         walking commit chain.
215
216 gitlink:git-peek-remote[1]::
217         Lists references on a remote repository using
218         upload-pack protocol (engine for ssh and local
219         transport).
220
221 gitlink:git-receive-pack[1]::
222         Invoked by 'git-send-pack' to receive what is pushed to it.
223
224 gitlink:git-send-pack[1]::
225         Pushes to a remote repository, intelligently.
226
227 gitlink:git-http-push[1]::
228         Push missing objects using HTTP/DAV.
229
230 gitlink:git-shell[1]::
231         Restricted shell for GIT-only SSH access.
232
233 gitlink:git-ssh-fetch[1]::
234         Pulls from a remote repository over ssh connection by
235         walking commit chain.
236
237 gitlink:git-ssh-upload[1]::
238         Helper "server-side" program used by git-ssh-fetch.
239
240 gitlink:git-update-server-info[1]::
241         Updates auxiliary information on a dumb server to help
242         clients discover references and packs on it.
243
244 gitlink:git-upload-pack[1]::
245         Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
246         what are asked for.
247
248
249 Porcelain-ish Commands
250 ----------------------
251
252 gitlink:git-add[1]::
253         Add paths to the index.
254
255 gitlink:git-am[1]::
256         Apply patches from a mailbox, but cooler.
257
258 gitlink:git-applymbox[1]::
259         Apply patches from a mailbox, original version by Linus.
260
261 gitlink:git-bisect[1]::
262         Find the change that introduced a bug by binary search.
263
264 gitlink:git-branch[1]::
265         Create and Show branches.
266
267 gitlink:git-checkout[1]::
268         Checkout and switch to a branch.
269
270 gitlink:git-cherry-pick[1]::
271         Cherry-pick the effect of an existing commit.
272
273 gitlink:git-clone[1]::
274         Clones a repository into a new directory.
275
276 gitlink:git-commit[1]::
277         Record changes to the repository.
278
279 gitlink:git-diff[1]::
280         Show changes between commits, commit and working tree, etc.
281
282 gitlink:git-fetch[1]::
283         Download from a remote repository via various protocols.
284
285 gitlink:git-format-patch[1]::
286         Prepare patches for e-mail submission.
287
288 gitlink:git-grep[1]::
289         Print lines matching a pattern.
290
291 gitlink:git-log[1]::
292         Shows commit logs.
293
294 gitlink:git-ls-remote[1]::
295         Shows references in a remote or local repository.
296
297 gitlink:git-merge[1]::
298         Grand unified merge driver.
299
300 gitlink:git-mv[1]::
301         Move or rename a file, a directory, or a symlink.
302
303 gitlink:git-pull[1]::
304         Fetch from and merge with a remote repository.
305
306 gitlink:git-push[1]::
307         Update remote refs along with associated objects.
308
309 gitlink:git-rebase[1]::
310         Rebase local commits to the updated upstream head.
311
312 gitlink:git-repack[1]::
313         Pack unpacked objects in a repository.
314
315 gitlink:git-reset[1]::
316         Reset current HEAD to the specified state.
317
318 gitlink:git-resolve[1]::
319         Merge two commits.
320
321 gitlink:git-revert[1]::
322         Revert an existing commit.
323
324 gitlink:git-shortlog[1]::
325         Summarizes 'git log' output.
326
327 gitlink:git-show-branch[1]::
328         Show branches and their commits.
329
330 gitlink:git-status[1]::
331         Shows the working tree status.
332
333 gitlink:git-verify-tag[1]::
334         Check the GPG signature of tag.
335
336 gitlink:git-whatchanged[1]::
337         Shows commit logs and differences they introduce.
338
339
340 Ancillary Commands
341 ------------------
342 Manipulators:
343
344 gitlink:git-applypatch[1]::
345         Apply one patch extracted from an e-mail.
346
347 gitlink:git-archimport[1]::
348         Import an arch repository into git.
349
350 gitlink:git-convert-objects[1]::
351         Converts old-style git repository.
352
353 gitlink:git-cvsimport[1]::
354         Salvage your data out of another SCM people love to hate.
355
356 gitlink:git-cvsexportcommit[1]::
357         Export a single commit to a CVS checkout.
358
359 gitlink:git-lost-found[1]::
360         Recover lost refs that luckily have not yet been pruned.
361
362 gitlink:git-merge-one-file[1]::
363         The standard helper program to use with `git-merge-index`.
364
365 gitlink:git-prune[1]::
366         Prunes all unreachable objects from the object database.
367
368 gitlink:git-relink[1]::
369         Hardlink common objects in local repositories.
370
371 gitlink:git-svnimport[1]::
372         Import a SVN repository into git.
373
374 gitlink:git-sh-setup[1]::
375         Common git shell script setup code.
376
377 gitlink:git-symbolic-ref[1]::
378         Read and modify symbolic refs.
379
380 gitlink:git-tag[1]::
381         An example script to create a tag object signed with GPG.
382
383 gitlink:git-update-ref[1]::
384         Update the object name stored in a ref safely.
385
386
387 Interrogators:
388
389 gitlink:git-check-ref-format[1]::
390         Make sure ref name is well formed.
391
392 gitlink:git-cherry[1]::
393         Find commits not merged upstream.
394
395 gitlink:git-count-objects[1]::
396         Count unpacked number of objects and their disk consumption.
397
398 gitlink:git-daemon[1]::
399         A really simple server for git repositories.
400
401 gitlink:git-get-tar-commit-id[1]::
402         Extract commit ID from an archive created using git-tar-tree.
403
404 gitlink:git-mailinfo[1]::
405         Extracts patch and authorship information from a single
406         e-mail message, optionally transliterating the commit
407         message into utf-8.
408
409 gitlink:git-mailsplit[1]::
410         A stupid program to split UNIX mbox format mailbox into
411         individual pieces of e-mail.
412
413 gitlink:git-patch-id[1]::
414         Compute unique ID for a patch.
415
416 gitlink:git-parse-remote[1]::
417         Routines to help parsing `$GIT_DIR/remotes/` files.
418
419 gitlink:git-request-pull[1]::
420         git-request-pull.
421
422 gitlink:git-rev-parse[1]::
423         Pick out and massage parameters.
424
425 gitlink:git-send-email[1]::
426         Send patch e-mails out of "format-patch --mbox" output.
427
428 gitlink:git-symbolic-ref[1]::
429         Read and modify symbolic refs.
430
431 gitlink:git-stripspace[1]::
432         Filter out empty lines.
433
434
435 Commands not yet documented
436 ---------------------------
437
438 gitlink:gitk[1]::
439         The gitk repository browser.
440
441
442 Configuration Mechanism
443 -----------------------
444
445 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
446 is used to hold per-repository configuration options.  It is a
447 simple text file modelled after `.ini` format familiar to some
448 people.  Here is an example:
449
450 ------------
451 #
452 # A '#' or ';' character indicates a comment.
453 #
454
455 ; core variables
456 [core]
457         ; Don't trust file modes
458         filemode = false
459
460 ; user identity
461 [user]
462         name = "Junio C Hamano"
463         email = "junkio@twinsun.com"
464
465 ------------
466
467 Various commands read from the configuration file and adjust
468 their operation accordingly.
469
470
471 Identifier Terminology
472 ----------------------
473 <object>::
474         Indicates the object name for any type of object.
475
476 <blob>::
477         Indicates a blob object name.
478
479 <tree>::
480         Indicates a tree object name.
481
482 <commit>::
483         Indicates a commit object name.
484
485 <tree-ish>::
486         Indicates a tree, commit or tag object name.  A
487         command that takes a <tree-ish> argument ultimately wants to
488         operate on a <tree> object but automatically dereferences
489         <commit> and <tag> objects that point at a <tree>.
490
491 <type>::
492         Indicates that an object type is required.
493         Currently one of: `blob`, `tree`, `commit`, or `tag`.
494
495 <file>::
496         Indicates a filename - almost always relative to the
497         root of the tree structure `GIT_INDEX_FILE` describes.
498
499 Symbolic Identifiers
500 --------------------
501 Any git command accepting any <object> can also use the following
502 symbolic notation:
503
504 HEAD::
505         indicates the head of the current branch (i.e. the
506         contents of `$GIT_DIR/HEAD`).
507
508 <tag>::
509         a valid tag 'name'
510         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
511
512 <head>::
513         a valid head 'name'
514         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
515
516 <snap>::
517         a valid snapshot 'name'
518         (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
519
520
521 File/Directory Structure
522 ------------------------
523
524 Please see link:repository-layout.html[repository layout] document.
525
526 Higher level SCMs may provide and manage additional information in the
527 `$GIT_DIR`.
528
529
530 Terminology
531 -----------
532 Please see link:glossary.html[glossary] document.
533
534
535 Environment Variables
536 ---------------------
537 Various git commands use the following environment variables:
538
539 The git Repository
540 ~~~~~~~~~~~~~~~~~~
541 These environment variables apply to 'all' core git commands. Nb: it
542 is worth noting that they may be used/overridden by SCMS sitting above
543 git so take care if using Cogito etc.
544
545 'GIT_INDEX_FILE'::
546         This environment allows the specification of an alternate
547         index file. If not specified, the default of `$GIT_DIR/index`
548         is used.
549
550 'GIT_OBJECT_DIRECTORY'::
551         If the object storage directory is specified via this
552         environment variable then the sha1 directories are created
553         underneath - otherwise the default `$GIT_DIR/objects`
554         directory is used.
555
556 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
557         Due to the immutable nature of git objects, old objects can be
558         archived into shared, read-only directories. This variable
559         specifies a ":" separated list of git object directories which
560         can be used to search for git objects. New objects will not be
561         written to these directories.
562
563 'GIT_DIR'::
564         If the 'GIT_DIR' environment variable is set then it
565         specifies a path to use instead of the default `.git`
566         for the base of the repository.
567
568 git Commits
569 ~~~~~~~~~~~
570 'GIT_AUTHOR_NAME'::
571 'GIT_AUTHOR_EMAIL'::
572 'GIT_AUTHOR_DATE'::
573 'GIT_COMMITTER_NAME'::
574 'GIT_COMMITTER_EMAIL'::
575         see gitlink:git-commit-tree[1]
576
577 git Diffs
578 ~~~~~~~~~
579 'GIT_DIFF_OPTS'::
580 'GIT_EXTERNAL_DIFF'::
581         see the "generating patches" section in :
582         gitlink:git-diff-index[1];
583         gitlink:git-diff-files[1];
584         gitlink:git-diff-tree[1]
585
586 Discussion[[Discussion]]
587 ------------------------
588 include::../README[]
589
590 Authors
591 -------
592 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
593 * The current git nurse is Junio C Hamano <junkio@cox.net>.
594 * The git potty was written by Andres Ericsson <ae@op5.se>.
595 * General upbringing is handled by the git-list <git@vger.kernel.org>.
596
597 Documentation
598 --------------
599 The documentation for git suite was started by David Greaves
600 <david@dgreaves.com>, and later enhanced greatly by the
601 contributors on the git-list <git@vger.kernel.org>.
602
603 GIT
604 ---
605 Part of the gitlink:git[7] suite
606