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