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