1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
\r
6 <meta name="generator" content="AsciiDoc 7.0.2" />
\r
7 <style type="text/css">
\r
9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
\r
11 border: 1px solid red;
\r
16 margin: 1em 5% 1em 5%;
\r
20 a:visited { color: fuchsia; }
\r
34 h1, h2, h3, h4, h5, h6 {
\r
36 font-family: sans-serif;
\r
38 margin-bottom: 0.5em;
\r
43 border-bottom: 2px solid silver;
\r
46 border-bottom: 2px solid silver;
\r
56 border: 1px solid silver;
\r
61 margin-bottom: 0.5em;
\r
71 font-family: sans-serif;
\r
78 font-family: sans-serif;
\r
82 font-family: sans-serif;
\r
84 border-top: 2px solid silver;
\r
90 padding-bottom: 0.5em;
\r
94 padding-bottom: 0.5em;
\r
98 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
\r
99 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
100 div.admonitionblock {
\r
103 margin-bottom: 1.5em;
\r
105 div.admonitionblock {
\r
107 margin-bottom: 2.5em;
\r
110 div.content { /* Block element content. */
\r
114 /* Block element titles. */
\r
115 div.title, caption.title {
\r
116 font-family: sans-serif;
\r
120 margin-bottom: 0.5em;
\r
126 td div.title:first-child {
\r
129 div.content div.title:first-child {
\r
132 div.content + div.title {
\r
136 div.sidebarblock > div.content {
\r
137 background: #ffffee;
\r
138 border: 1px solid silver;
\r
142 div.listingblock > div.content {
\r
143 border: 1px solid silver;
\r
144 background: #f4f4f4;
\r
148 div.quoteblock > div.content {
\r
149 padding-left: 2.0em;
\r
151 div.quoteblock .attribution {
\r
155 div.admonitionblock .icon {
\r
156 vertical-align: top;
\r
159 text-decoration: underline;
\r
161 padding-right: 0.5em;
\r
163 div.admonitionblock td.content {
\r
164 padding-left: 0.5em;
\r
165 border-left: 2px solid silver;
\r
168 div.exampleblock > div.content {
\r
169 border-left: 2px solid silver;
\r
173 div.verseblock div.content {
\r
177 div.imageblock div.content { padding-left: 0; }
\r
178 div.imageblock img { border: 1px solid silver; }
\r
179 span.image img { border-style: none; }
\r
183 margin-bottom: 0.8em;
\r
188 font-style: italic;
\r
190 dd > *:first-child {
\r
195 list-style-position: outside;
\r
198 list-style-type: lower-alpha;
\r
201 div.tableblock > table {
\r
202 border-color: #527bbd;
\r
206 font-family: sans-serif;
\r
215 margin-bottom: 0.8em;
\r
218 vertical-align: top;
\r
219 font-style: italic;
\r
220 padding-right: 0.8em;
\r
223 vertical-align: top;
\r
227 div#footer-badges { display: none; }
\r
229 include::./stylesheets/xhtml11-manpage.css[]
\r
230 /* Workarounds for IE6's broken and incomplete CSS2. */
\r
232 div.sidebar-content {
\r
233 background: #ffffee;
\r
234 border: 1px solid silver;
\r
237 div.sidebar-title, div.image-title {
\r
238 font-family: sans-serif;
\r
241 margin-bottom: 0.5em;
\r
244 div.listingblock div.content {
\r
245 border: 1px solid silver;
\r
246 background: #f4f4f4;
\r
250 div.quoteblock-content {
\r
251 padding-left: 2.0em;
\r
254 div.exampleblock-content {
\r
255 border-left: 2px solid silver;
\r
256 padding-left: 0.5em;
\r
259 <title>git(7)</title>
\r
267 <div class="sectionbody">
\r
269 the stupid content tracker
\r
274 <div class="sectionbody">
\r
275 <p><em>git</em> [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]</p>
\r
277 <h2>DESCRIPTION</h2>
\r
278 <div class="sectionbody">
\r
279 <p>Git is a fast, scalable, distributed revision control system with an
\r
280 unusually rich command set that provides both high-level operations
\r
281 and full access to internals.</p>
\r
282 <p>See this <a href="tutorial.html">tutorial</a> to get started, then see
\r
283 <a href="everyday.html">Everyday Git</a> for a useful minimum set of commands, and
\r
284 "man git-commandname" for documentation of each command. CVS users may
\r
285 also want to read <a href="cvs-migration.html">CVS migration</a>.</p>
\r
286 <p>The COMMAND is either a name of a Git command (see below) or an alias
\r
287 as defined in the configuration file (see <a href="git-repo-config.html">git-repo-config(1)</a>).</p>
\r
290 <div class="sectionbody">
\r
297 Prints the git suite version that the <em>git</em> program came from.
\r
305 Prints the synopsis and a list of the most commonly used
\r
306 commands. If a git command is named this option will bring up
\r
307 the man-page for that command. If the option <em>--all</em> or <em>-a</em> is
\r
308 given then all available commands are printed.
\r
316 Path to wherever your core git programs are installed.
\r
317 This can also be controlled by setting the GIT_EXEC_PATH
\r
318 environment variable. If no path is given <em>git</em> will print
\r
319 the current setting and then exit.
\r
324 <h2>FURTHER DOCUMENTATION</h2>
\r
325 <div class="sectionbody">
\r
326 <p>See the references above to get started using git. The following is
\r
327 probably more detail than necessary for a first-time user.</p>
\r
328 <p>The <a href="#Discussion">Discussion</a> section below and the
\r
329 <a href="core-tutorial.html">Core tutorial</a> both provide introductions to the
\r
330 underlying git architecture.</p>
\r
331 <p>See also the <a href="howto-index.html">howto</a> documents for some useful
\r
334 <h2>GIT COMMANDS</h2>
\r
335 <div class="sectionbody">
\r
336 <p>We divide git into high level ("porcelain") commands and low level
\r
337 ("plumbing") commands.</p>
\r
339 <h2>Low-level commands (plumbing)</h2>
\r
340 <div class="sectionbody">
\r
341 <p>Although git includes its
\r
342 own porcelain layer, its low-level commands are sufficient to support
\r
343 development of alternative porcelains. Developers of such porcelains
\r
344 might start by reading about <a href="git-update-index.html">git-update-index(1)</a> and
\r
345 <a href="git-read-tree.html">git-read-tree(1)</a>.</p>
\r
346 <p>We divide the low-level commands into commands that manipulate objects (in
\r
347 the repository, index, and working tree), commands that interrogate and
\r
348 compare objects, and commands that move objects and references between
\r
350 <h3>Manipulation commands</h3>
\r
353 <a href="git-apply.html">git-apply(1)</a>
\r
357 Reads a "diff -up1" or git generated patch file and
\r
358 applies it to the working tree.
\r
362 <a href="git-checkout-index.html">git-checkout-index(1)</a>
\r
366 Copy files from the index to the working tree.
\r
370 <a href="git-commit-tree.html">git-commit-tree(1)</a>
\r
374 Creates a new commit object.
\r
378 <a href="git-hash-object.html">git-hash-object(1)</a>
\r
382 Computes the object ID from a file.
\r
386 <a href="git-index-pack.html">git-index-pack(1)</a>
\r
390 Build pack idx file for an existing packed archive.
\r
394 <a href="git-init-db.html">git-init-db(1)</a>
\r
398 Creates an empty git object database, or reinitialize an
\r
403 <a href="git-merge-index.html">git-merge-index(1)</a>
\r
407 Runs a merge for files needing merging.
\r
411 <a href="git-mktag.html">git-mktag(1)</a>
\r
415 Creates a tag object.
\r
419 <a href="git-mktree.html">git-mktree(1)</a>
\r
423 Build a tree-object from ls-tree formatted text.
\r
427 <a href="git-pack-objects.html">git-pack-objects(1)</a>
\r
431 Creates a packed archive of objects.
\r
435 <a href="git-prune-packed.html">git-prune-packed(1)</a>
\r
439 Remove extra objects that are already in pack files.
\r
443 <a href="git-read-tree.html">git-read-tree(1)</a>
\r
447 Reads tree information into the index.
\r
451 <a href="git-repo-config.html">git-repo-config(1)</a>
\r
455 Get and set options in .git/config.
\r
459 <a href="git-unpack-objects.html">git-unpack-objects(1)</a>
\r
463 Unpacks objects out of a packed archive.
\r
467 <a href="git-update-index.html">git-update-index(1)</a>
\r
471 Registers files in the working tree to the index.
\r
475 <a href="git-write-tree.html">git-write-tree(1)</a>
\r
479 Creates a tree from the index.
\r
483 <h3>Interrogation commands</h3>
\r
486 <a href="git-cat-file.html">git-cat-file(1)</a>
\r
490 Provide content or type/size information for repository objects.
\r
494 <a href="git-describe.html">git-describe(1)</a>
\r
498 Show the most recent tag that is reachable from a commit.
\r
502 <a href="git-diff-index.html">git-diff-index(1)</a>
\r
506 Compares content and mode of blobs between the index and repository.
\r
510 <a href="git-diff-files.html">git-diff-files(1)</a>
\r
514 Compares files in the working tree and the index.
\r
518 <a href="git-diff-stages.html">git-diff-stages(1)</a>
\r
522 Compares two "merge stages" in the index.
\r
526 <a href="git-diff-tree.html">git-diff-tree(1)</a>
\r
530 Compares the content and mode of blobs found via two tree objects.
\r
534 <a href="git-fsck-objects.html">git-fsck-objects(1)</a>
\r
538 Verifies the connectivity and validity of the objects in the database.
\r
542 <a href="git-ls-files.html">git-ls-files(1)</a>
\r
546 Information about files in the index and the working tree.
\r
550 <a href="git-ls-tree.html">git-ls-tree(1)</a>
\r
554 Displays a tree object in human readable form.
\r
558 <a href="git-merge-base.html">git-merge-base(1)</a>
\r
562 Finds as good common ancestors as possible for a merge.
\r
566 <a href="git-name-rev.html">git-name-rev(1)</a>
\r
570 Find symbolic names for given revs.
\r
574 <a href="git-pack-redundant.html">git-pack-redundant(1)</a>
\r
578 Find redundant pack files.
\r
582 <a href="git-rev-list.html">git-rev-list(1)</a>
\r
586 Lists commit objects in reverse chronological order.
\r
590 <a href="git-show-index.html">git-show-index(1)</a>
\r
594 Displays contents of a pack idx file.
\r
598 <a href="git-tar-tree.html">git-tar-tree(1)</a>
\r
602 Creates a tar archive of the files in the named tree object.
\r
606 <a href="git-unpack-file.html">git-unpack-file(1)</a>
\r
610 Creates a temporary file with a blob's contents.
\r
614 <a href="git-var.html">git-var(1)</a>
\r
618 Displays a git logical variable.
\r
622 <a href="git-verify-pack.html">git-verify-pack(1)</a>
\r
626 Validates packed git archive files.
\r
630 <p>In general, the interrogate commands do not touch the files in
\r
631 the working tree.</p>
\r
632 <h3>Synching repositories</h3>
\r
635 <a href="git-clone-pack.html">git-clone-pack(1)</a>
\r
639 Clones a repository into the current repository (engine
\r
640 for ssh and local transport).
\r
644 <a href="git-fetch-pack.html">git-fetch-pack(1)</a>
\r
648 Updates from a remote repository (engine for ssh and
\r
653 <a href="git-http-fetch.html">git-http-fetch(1)</a>
\r
657 Downloads a remote git repository via HTTP by walking
\r
662 <a href="git-local-fetch.html">git-local-fetch(1)</a>
\r
666 Duplicates another git repository on a local system by
\r
667 walking commit chain.
\r
671 <a href="git-peek-remote.html">git-peek-remote(1)</a>
\r
675 Lists references on a remote repository using
\r
676 upload-pack protocol (engine for ssh and local
\r
681 <a href="git-receive-pack.html">git-receive-pack(1)</a>
\r
685 Invoked by <em>git-send-pack</em> to receive what is pushed to it.
\r
689 <a href="git-send-pack.html">git-send-pack(1)</a>
\r
693 Pushes to a remote repository, intelligently.
\r
697 <a href="git-http-push.html">git-http-push(1)</a>
\r
701 Push missing objects using HTTP/DAV.
\r
705 <a href="git-shell.html">git-shell(1)</a>
\r
709 Restricted shell for GIT-only SSH access.
\r
713 <a href="git-ssh-fetch.html">git-ssh-fetch(1)</a>
\r
717 Pulls from a remote repository over ssh connection by
\r
718 walking commit chain.
\r
722 <a href="git-ssh-upload.html">git-ssh-upload(1)</a>
\r
726 Helper "server-side" program used by git-ssh-fetch.
\r
730 <a href="git-update-server-info.html">git-update-server-info(1)</a>
\r
734 Updates auxiliary information on a dumb server to help
\r
735 clients discover references and packs on it.
\r
739 <a href="git-upload-pack.html">git-upload-pack(1)</a>
\r
743 Invoked by <em>git-clone-pack</em> and <em>git-fetch-pack</em> to push
\r
744 what are asked for.
\r
748 <a href="git-upload-tar.html">git-upload-tar(1)</a>
\r
752 Invoked by <em>git-tar-tree --remote</em> to return the tar
\r
753 archive the other end asked for.
\r
758 <h2>High-level commands (porcelain)</h2>
\r
759 <div class="sectionbody">
\r
760 <p>We separate the porcelain commands into the main commands and some
\r
761 ancillary user utilities.</p>
\r
762 <h3>Main porcelain commands</h3>
\r
765 <a href="git-add.html">git-add(1)</a>
\r
769 Add paths to the index.
\r
773 <a href="git-am.html">git-am(1)</a>
\r
777 Apply patches from a mailbox, but cooler.
\r
781 <a href="git-applymbox.html">git-applymbox(1)</a>
\r
785 Apply patches from a mailbox, original version by Linus.
\r
789 <a href="git-bisect.html">git-bisect(1)</a>
\r
793 Find the change that introduced a bug by binary search.
\r
797 <a href="git-branch.html">git-branch(1)</a>
\r
801 Create and Show branches.
\r
805 <a href="git-checkout.html">git-checkout(1)</a>
\r
809 Checkout and switch to a branch.
\r
813 <a href="git-cherry-pick.html">git-cherry-pick(1)</a>
\r
817 Cherry-pick the effect of an existing commit.
\r
821 <a href="git-clean.html">git-clean(1)</a>
\r
825 Remove untracked files from the working tree.
\r
829 <a href="git-clone.html">git-clone(1)</a>
\r
833 Clones a repository into a new directory.
\r
837 <a href="git-commit.html">git-commit(1)</a>
\r
841 Record changes to the repository.
\r
845 <a href="git-diff.html">git-diff(1)</a>
\r
849 Show changes between commits, commit and working tree, etc.
\r
853 <a href="git-fetch.html">git-fetch(1)</a>
\r
857 Download from a remote repository via various protocols.
\r
861 <a href="git-format-patch.html">git-format-patch(1)</a>
\r
865 Prepare patches for e-mail submission.
\r
869 <a href="git-grep.html">git-grep(1)</a>
\r
873 Print lines matching a pattern.
\r
877 <a href="git-log.html">git-log(1)</a>
\r
885 <a href="git-ls-remote.html">git-ls-remote(1)</a>
\r
889 Shows references in a remote or local repository.
\r
893 <a href="git-merge.html">git-merge(1)</a>
\r
897 Grand unified merge driver.
\r
901 <a href="git-mv.html">git-mv(1)</a>
\r
905 Move or rename a file, a directory, or a symlink.
\r
909 <a href="git-pull.html">git-pull(1)</a>
\r
913 Fetch from and merge with a remote repository.
\r
917 <a href="git-push.html">git-push(1)</a>
\r
921 Update remote refs along with associated objects.
\r
925 <a href="git-rebase.html">git-rebase(1)</a>
\r
929 Rebase local commits to the updated upstream head.
\r
933 <a href="git-repack.html">git-repack(1)</a>
\r
937 Pack unpacked objects in a repository.
\r
941 <a href="git-rerere.html">git-rerere(1)</a>
\r
945 Reuse recorded resolution of conflicted merges.
\r
949 <a href="git-reset.html">git-reset(1)</a>
\r
953 Reset current HEAD to the specified state.
\r
957 <a href="git-resolve.html">git-resolve(1)</a>
\r
965 <a href="git-revert.html">git-revert(1)</a>
\r
969 Revert an existing commit.
\r
973 <a href="git-rm.html">git-rm(1)</a>
\r
977 Remove files from the working tree and from the index.
\r
981 <a href="git-shortlog.html">git-shortlog(1)</a>
\r
985 Summarizes <em>git log</em> output.
\r
989 <a href="git-show.html">git-show(1)</a>
\r
993 Show one commit log and its diff.
\r
997 <a href="git-show-branch.html">git-show-branch(1)</a>
\r
1001 Show branches and their commits.
\r
1005 <a href="git-status.html">git-status(1)</a>
\r
1009 Shows the working tree status.
\r
1013 <a href="git-verify-tag.html">git-verify-tag(1)</a>
\r
1017 Check the GPG signature of tag.
\r
1021 <a href="git-whatchanged.html">git-whatchanged(1)</a>
\r
1025 Shows commit logs and differences they introduce.
\r
1029 <h3>Ancillary Commands</h3>
\r
1030 <p>Manipulators:</p>
\r
1033 <a href="git-applypatch.html">git-applypatch(1)</a>
\r
1037 Apply one patch extracted from an e-mail.
\r
1041 <a href="git-archimport.html">git-archimport(1)</a>
\r
1045 Import an arch repository into git.
\r
1049 <a href="git-convert-objects.html">git-convert-objects(1)</a>
\r
1053 Converts old-style git repository.
\r
1057 <a href="git-cvsimport.html">git-cvsimport(1)</a>
\r
1061 Salvage your data out of another SCM people love to hate.
\r
1065 <a href="git-cvsexportcommit.html">git-cvsexportcommit(1)</a>
\r
1069 Export a single commit to a CVS checkout.
\r
1073 <a href="git-cvsserver.html">git-cvsserver(1)</a>
\r
1077 A CVS server emulator for git.
\r
1081 <a href="git-lost-found.html">git-lost-found(1)</a>
\r
1085 Recover lost refs that luckily have not yet been pruned.
\r
1089 <a href="git-merge-one-file.html">git-merge-one-file(1)</a>
\r
1093 The standard helper program to use with <tt>git-merge-index</tt>.
\r
1097 <a href="git-prune.html">git-prune(1)</a>
\r
1101 Prunes all unreachable objects from the object database.
\r
1105 <a href="git-quiltimport.html">git-quiltimport(1)</a>
\r
1109 Applies a quilt patchset onto the current branch.
\r
1113 <a href="git-relink.html">git-relink(1)</a>
\r
1117 Hardlink common objects in local repositories.
\r
1121 <a href="git-svnimport.html">git-svnimport(1)</a>
\r
1125 Import a SVN repository into git.
\r
1129 <a href="git-sh-setup.html">git-sh-setup(1)</a>
\r
1133 Common git shell script setup code.
\r
1137 <a href="git-symbolic-ref.html">git-symbolic-ref(1)</a>
\r
1141 Read and modify symbolic refs.
\r
1145 <a href="git-tag.html">git-tag(1)</a>
\r
1149 An example script to create a tag object signed with GPG.
\r
1153 <a href="git-update-ref.html">git-update-ref(1)</a>
\r
1157 Update the object name stored in a ref safely.
\r
1161 <p>Interrogators:</p>
\r
1164 <a href="git-annotate.html">git-annotate(1)</a>
\r
1168 Annotate file lines with commit info.
\r
1172 <a href="git-blame.html">git-blame(1)</a>
\r
1176 Blame file lines on commits.
\r
1180 <a href="git-check-ref-format.html">git-check-ref-format(1)</a>
\r
1184 Make sure ref name is well formed.
\r
1188 <a href="git-cherry.html">git-cherry(1)</a>
\r
1192 Find commits not merged upstream.
\r
1196 <a href="git-count-objects.html">git-count-objects(1)</a>
\r
1200 Count unpacked number of objects and their disk consumption.
\r
1204 <a href="git-daemon.html">git-daemon(1)</a>
\r
1208 A really simple server for git repositories.
\r
1212 <a href="git-fmt-merge-msg.html">git-fmt-merge-msg(1)</a>
\r
1216 Produce a merge commit message.
\r
1220 <a href="git-get-tar-commit-id.html">git-get-tar-commit-id(1)</a>
\r
1224 Extract commit ID from an archive created using git-tar-tree.
\r
1228 <a href="git-imap-send.html">git-imap-send(1)</a>
\r
1232 Dump a mailbox from stdin into an imap folder.
\r
1236 <a href="git-mailinfo.html">git-mailinfo(1)</a>
\r
1240 Extracts patch and authorship information from a single
\r
1241 e-mail message, optionally transliterating the commit
\r
1242 message into utf-8.
\r
1246 <a href="git-mailsplit.html">git-mailsplit(1)</a>
\r
1250 A stupid program to split UNIX mbox format mailbox into
\r
1251 individual pieces of e-mail.
\r
1255 <a href="git-merge-tree.html">git-merge-tree(1)</a>
\r
1259 Show three-way merge without touching index.
\r
1263 <a href="git-patch-id.html">git-patch-id(1)</a>
\r
1267 Compute unique ID for a patch.
\r
1271 <a href="git-parse-remote.html">git-parse-remote(1)</a>
\r
1275 Routines to help parsing <tt>$GIT_DIR/remotes/</tt> files.
\r
1279 <a href="git-request-pull.html">git-request-pull(1)</a>
\r
1287 <a href="git-rev-parse.html">git-rev-parse(1)</a>
\r
1291 Pick out and massage parameters.
\r
1295 <a href="git-send-email.html">git-send-email(1)</a>
\r
1299 Send patch e-mails out of "format-patch --mbox" output.
\r
1303 <a href="git-symbolic-ref.html">git-symbolic-ref(1)</a>
\r
1307 Read and modify symbolic refs.
\r
1311 <a href="git-stripspace.html">git-stripspace(1)</a>
\r
1315 Filter out empty lines.
\r
1320 <h2>Commands not yet documented</h2>
\r
1321 <div class="sectionbody">
\r
1324 <a href="gitk.html">gitk(1)</a>
\r
1328 The gitk repository browser.
\r
1333 <h2>Configuration Mechanism</h2>
\r
1334 <div class="sectionbody">
\r
1335 <p>Starting from 0.99.9 (actually mid 0.99.8.GIT), <tt>.git/config</tt> file
\r
1336 is used to hold per-repository configuration options. It is a
\r
1337 simple text file modelled after <tt>.ini</tt> format familiar to some
\r
1338 people. Here is an example:</p>
\r
1339 <div class="listingblock">
\r
1340 <div class="content">
\r
1342 # A '#' or ';' character indicates a comment.
\r
1347 ; Don't trust file modes
\r
1352 name = "Junio C Hamano"
\r
1353 email = "junkio@twinsun.com"
\r
1356 <p>Various commands read from the configuration file and adjust
\r
1357 their operation accordingly.</p>
\r
1359 <h2>Identifier Terminology</h2>
\r
1360 <div class="sectionbody">
\r
1367 Indicates the object name for any type of object.
\r
1375 Indicates a blob object name.
\r
1383 Indicates a tree object name.
\r
1391 Indicates a commit object name.
\r
1399 Indicates a tree, commit or tag object name. A
\r
1400 command that takes a <tree-ish> argument ultimately wants to
\r
1401 operate on a <tree> object but automatically dereferences
\r
1402 <commit> and <tag> objects that point at a <tree>.
\r
1410 Indicates that an object type is required.
\r
1411 Currently one of: <tt>blob</tt>, <tt>tree</tt>, <tt>commit</tt>, or <tt>tag</tt>.
\r
1419 Indicates a filename - almost always relative to the
\r
1420 root of the tree structure <tt>GIT_INDEX_FILE</tt> describes.
\r
1425 <h2>Symbolic Identifiers</h2>
\r
1426 <div class="sectionbody">
\r
1427 <p>Any git command accepting any <object> can also use the following
\r
1428 symbolic notation:</p>
\r
1435 indicates the head of the current branch (i.e. the
\r
1436 contents of <tt>$GIT_DIR/HEAD</tt>).
\r
1444 a valid tag <em>name</em>
\r
1445 (i.e. the contents of <tt>$GIT_DIR/refs/tags/<tag></tt>).
\r
1453 a valid head <em>name</em>
\r
1454 (i.e. the contents of <tt>$GIT_DIR/refs/heads/<head></tt>).
\r
1459 <h2>File/Directory Structure</h2>
\r
1460 <div class="sectionbody">
\r
1461 <p>Please see <a href="repository-layout.html">repository layout</a> document.</p>
\r
1462 <p>Read <a href="hooks.html">hooks</a> for more details about each hook.</p>
\r
1463 <p>Higher level SCMs may provide and manage additional information in the
\r
1464 <tt>$GIT_DIR</tt>.</p>
\r
1466 <h2>Terminology</h2>
\r
1467 <div class="sectionbody">
\r
1468 <p>Please see <a href="glossary.html">glossary</a> document.</p>
\r
1470 <h2>Environment Variables</h2>
\r
1471 <div class="sectionbody">
\r
1472 <p>Various git commands use the following environment variables:</p>
\r
1473 <h3>The git Repository</h3>
\r
1474 <p>These environment variables apply to <em>all</em> core git commands. Nb: it
\r
1475 is worth noting that they may be used/overridden by SCMS sitting above
\r
1476 git so take care if using Cogito etc.</p>
\r
1479 <em>GIT_INDEX_FILE</em>
\r
1483 This environment allows the specification of an alternate
\r
1484 index file. If not specified, the default of <tt>$GIT_DIR/index</tt>
\r
1489 <em>GIT_OBJECT_DIRECTORY</em>
\r
1493 If the object storage directory is specified via this
\r
1494 environment variable then the sha1 directories are created
\r
1495 underneath - otherwise the default <tt>$GIT_DIR/objects</tt>
\r
1496 directory is used.
\r
1500 <em>GIT_ALTERNATE_OBJECT_DIRECTORIES</em>
\r
1504 Due to the immutable nature of git objects, old objects can be
\r
1505 archived into shared, read-only directories. This variable
\r
1506 specifies a ":" separated list of git object directories which
\r
1507 can be used to search for git objects. New objects will not be
\r
1508 written to these directories.
\r
1516 If the <em>GIT_DIR</em> environment variable is set then it
\r
1517 specifies a path to use instead of the default <tt>.git</tt>
\r
1518 for the base of the repository.
\r
1522 <h3>git Commits</h3>
\r
1525 <em>GIT_AUTHOR_NAME</em>
\r
1528 <em>GIT_AUTHOR_EMAIL</em>
\r
1531 <em>GIT_AUTHOR_DATE</em>
\r
1534 <em>GIT_COMMITTER_NAME</em>
\r
1537 <em>GIT_COMMITTER_EMAIL</em>
\r
1541 see <a href="git-commit-tree.html">git-commit-tree(1)</a>
\r
1545 <h3>git Diffs</h3>
\r
1548 <em>GIT_DIFF_OPTS</em>
\r
1551 <em>GIT_EXTERNAL_DIFF</em>
\r
1555 see the "generating patches" section in :
\r
1556 <a href="git-diff-index.html">git-diff-index(1)</a>;
\r
1557 <a href="git-diff-files.html">git-diff-files(1)</a>;
\r
1558 <a href="git-diff-tree.html">git-diff-tree(1)</a>
\r
1563 <h2>Discussion<a id="Discussion"></a></h2>
\r
1564 <div class="sectionbody">
\r
1565 <p>"git" can mean anything, depending on your mood.</p>
\r
1569 random three-letter combination that is pronounceable, and not
\r
1570 actually used by any common UNIX command. The fact that it is a
\r
1571 mispronunciation of "get" may or may not be relevant.
\r
1576 stupid. contemptible and despicable. simple. Take your pick from the
\r
1577 dictionary of slang.
\r
1582 "global information tracker": you're in a good mood, and it actually
\r
1583 works for you. Angels sing, and a light suddenly fills the room.
\r
1588 "goddamn idiotic truckload of sh*t": when it breaks
\r
1592 <p>This is a stupid (but extremely fast) directory content manager. It
\r
1593 doesn't do a whole lot, but what it <em>does</em> do is track directory
\r
1594 contents efficiently.</p>
\r
1595 <p>There are two object abstractions: the "object database", and the
\r
1596 "current directory cache" aka "index".</p>
\r
1597 <h3>The Object Database</h3>
\r
1598 <p>The object database is literally just a content-addressable collection
\r
1599 of objects. All objects are named by their content, which is
\r
1600 approximated by the SHA1 hash of the object itself. Objects may refer
\r
1601 to other objects (by referencing their SHA1 hash), and so you can
\r
1602 build up a hierarchy of objects.</p>
\r
1603 <p>All objects have a statically determined "type" aka "tag", which is
\r
1604 determined at object creation time, and which identifies the format of
\r
1605 the object (i.e. how it is used, and how it can refer to other
\r
1606 objects). There are currently four different object types: "blob",
\r
1607 "tree", "commit" and "tag".</p>
\r
1608 <p>A "blob" object cannot refer to any other object, and is, like the type
\r
1609 implies, a pure storage object containing some user data. It is used to
\r
1610 actually store the file data, i.e. a blob object is associated with some
\r
1611 particular version of some file.</p>
\r
1612 <p>A "tree" object is an object that ties one or more "blob" objects into a
\r
1613 directory structure. In addition, a tree object can refer to other tree
\r
1614 objects, thus creating a directory hierarchy.</p>
\r
1615 <p>A "commit" object ties such directory hierarchies together into
\r
1616 a DAG of revisions - each "commit" is associated with exactly one tree
\r
1617 (the directory hierarchy at the time of the commit). In addition, a
\r
1618 "commit" refers to one or more "parent" commit objects that describe the
\r
1619 history of how we arrived at that directory hierarchy.</p>
\r
1620 <p>As a special case, a commit object with no parents is called the "root"
\r
1621 object, and is the point of an initial project commit. Each project
\r
1622 must have at least one root, and while you can tie several different
\r
1623 root objects together into one project by creating a commit object which
\r
1624 has two or more separate roots as its ultimate parents, that's probably
\r
1625 just going to confuse people. So aim for the notion of "one root object
\r
1626 per project", even if git itself does not enforce that.</p>
\r
1627 <p>A "tag" object symbolically identifies and can be used to sign other
\r
1628 objects. It contains the identifier and type of another object, a
\r
1629 symbolic name (of course!) and, optionally, a signature.</p>
\r
1630 <p>Regardless of object type, all objects share the following
\r
1631 characteristics: they are all deflated with zlib, and have a header
\r
1632 that not only specifies their type, but also provides size information
\r
1633 about the data in the object. It's worth noting that the SHA1 hash
\r
1634 that is used to name the object is the hash of the original data
\r
1635 plus this header, so <tt>sha1sum</tt> <em>file</em> does not match the object name
\r
1636 for <em>file</em>.
\r
1637 (Historical note: in the dawn of the age of git the hash
\r
1638 was the sha1 of the <em>compressed</em> object.)</p>
\r
1639 <p>As a result, the general consistency of an object can always be tested
\r
1640 independently of the contents or the type of the object: all objects can
\r
1641 be validated by verifying that (a) their hashes match the content of the
\r
1642 file and (b) the object successfully inflates to a stream of bytes that
\r
1643 forms a sequence of <ascii type without space> + <space> + <ascii decimal
\r
1644 size> + <byte\0> + <binary object data>.</p>
\r
1645 <p>The structured objects can further have their structure and
\r
1646 connectivity to other objects verified. This is generally done with
\r
1647 the <tt>git-fsck-objects</tt> program, which generates a full dependency graph
\r
1648 of all objects, and verifies their internal consistency (in addition
\r
1649 to just verifying their superficial consistency through the hash).</p>
\r
1650 <p>The object types in some more detail:</p>
\r
1651 <h3>Blob Object</h3>
\r
1652 <p>A "blob" object is nothing but a binary blob of data, and doesn't
\r
1653 refer to anything else. There is no signature or any other
\r
1654 verification of the data, so while the object is consistent (it <em>is</em>
\r
1655 indexed by its sha1 hash, so the data itself is certainly correct), it
\r
1656 has absolutely no other attributes. No name associations, no
\r
1657 permissions. It is purely a blob of data (i.e. normally "file
\r
1659 <p>In particular, since the blob is entirely defined by its data, if two
\r
1660 files in a directory tree (or in multiple different versions of the
\r
1661 repository) have the same contents, they will share the same blob
\r
1662 object. The object is totally independent of its location in the
\r
1663 directory tree, and renaming a file does not change the object that
\r
1664 file is associated with in any way.</p>
\r
1665 <p>A blob is typically created when <a href="git-update-index.html">git-update-index(1)</a>
\r
1666 is run, and its data can be accessed by <a href="git-cat-file.html">git-cat-file(1)</a>.</p>
\r
1667 <h3>Tree Object</h3>
\r
1668 <p>The next hierarchical object type is the "tree" object. A tree object
\r
1669 is a list of mode/name/blob data, sorted by name. Alternatively, the
\r
1670 mode data may specify a directory mode, in which case instead of
\r
1671 naming a blob, that name is associated with another TREE object.</p>
\r
1672 <p>Like the "blob" object, a tree object is uniquely determined by the
\r
1673 set contents, and so two separate but identical trees will always
\r
1674 share the exact same object. This is true at all levels, i.e. it's
\r
1675 true for a "leaf" tree (which does not refer to any other trees, only
\r
1676 blobs) as well as for a whole subdirectory.</p>
\r
1677 <p>For that reason a "tree" object is just a pure data abstraction: it
\r
1678 has no history, no signatures, no verification of validity, except
\r
1679 that since the contents are again protected by the hash itself, we can
\r
1680 trust that the tree is immutable and its contents never change.</p>
\r
1681 <p>So you can trust the contents of a tree to be valid, the same way you
\r
1682 can trust the contents of a blob, but you don't know where those
\r
1683 contents <em>came</em> from.</p>
\r
1684 <p>Side note on trees: since a "tree" object is a sorted list of
\r
1685 "filename+content", you can create a diff between two trees without
\r
1686 actually having to unpack two trees. Just ignore all common parts,
\r
1687 and your diff will look right. In other words, you can effectively
\r
1688 (and efficiently) tell the difference between any two random trees by
\r
1689 O(n) where "n" is the size of the difference, rather than the size of
\r
1691 <p>Side note 2 on trees: since the name of a "blob" depends entirely and
\r
1692 exclusively on its contents (i.e. there are no names or permissions
\r
1693 involved), you can see trivial renames or permission changes by
\r
1694 noticing that the blob stayed the same. However, renames with data
\r
1695 changes need a smarter "diff" implementation.</p>
\r
1696 <p>A tree is created with <a href="git-write-tree.html">git-write-tree(1)</a> and
\r
1697 its data can be accessed by <a href="git-ls-tree.html">git-ls-tree(1)</a>.
\r
1698 Two trees can be compared with <a href="git-diff-tree.html">git-diff-tree(1)</a>.</p>
\r
1699 <h3>Commit Object</h3>
\r
1700 <p>The "commit" object is an object that introduces the notion of
\r
1701 history into the picture. In contrast to the other objects, it
\r
1702 doesn't just describe the physical state of a tree, it describes how
\r
1703 we got there, and why.</p>
\r
1704 <p>A "commit" is defined by the tree-object that it results in, the
\r
1705 parent commits (zero, one or more) that led up to that point, and a
\r
1706 comment on what happened. Again, a commit is not trusted per se:
\r
1707 the contents are well-defined and "safe" due to the cryptographically
\r
1708 strong signatures at all levels, but there is no reason to believe
\r
1709 that the tree is "good" or that the merge information makes sense.
\r
1710 The parents do not have to actually have any relationship with the
\r
1711 result, for example.</p>
\r
1712 <p>Note on commits: unlike real SCM's, commits do not contain
\r
1713 rename information or file mode change information. All of that is
\r
1714 implicit in the trees involved (the result tree, and the result trees
\r
1715 of the parents), and describing that makes no sense in this idiotic
\r
1717 <p>A commit is created with <a href="git-commit-tree.html">git-commit-tree(1)</a> and
\r
1718 its data can be accessed by <a href="git-cat-file.html">git-cat-file(1)</a>.</p>
\r
1720 <p>An aside on the notion of "trust". Trust is really outside the scope
\r
1721 of "git", but it's worth noting a few things. First off, since
\r
1722 everything is hashed with SHA1, you <em>can</em> trust that an object is
\r
1723 intact and has not been messed with by external sources. So the name
\r
1724 of an object uniquely identifies a known state - just not a state that
\r
1725 you may want to trust.</p>
\r
1726 <p>Furthermore, since the SHA1 signature of a commit refers to the
\r
1727 SHA1 signatures of the tree it is associated with and the signatures
\r
1728 of the parent, a single named commit specifies uniquely a whole set
\r
1729 of history, with full contents. You can't later fake any step of the
\r
1730 way once you have the name of a commit.</p>
\r
1731 <p>So to introduce some real trust in the system, the only thing you need
\r
1732 to do is to digitally sign just <em>one</em> special note, which includes the
\r
1733 name of a top-level commit. Your digital signature shows others
\r
1734 that you trust that commit, and the immutability of the history of
\r
1735 commits tells others that they can trust the whole history.</p>
\r
1736 <p>In other words, you can easily validate a whole archive by just
\r
1737 sending out a single email that tells the people the name (SHA1 hash)
\r
1738 of the top commit, and digitally sign that email using something
\r
1740 <p>To assist in this, git also provides the tag object…</p>
\r
1741 <h3>Tag Object</h3>
\r
1742 <p>Git provides the "tag" object to simplify creating, managing and
\r
1743 exchanging symbolic and signed tokens. The "tag" object at its
\r
1744 simplest simply symbolically identifies another object by containing
\r
1745 the sha1, type and symbolic name.</p>
\r
1746 <p>However it can optionally contain additional signature information
\r
1747 (which git doesn't care about as long as there's less than 8k of
\r
1748 it). This can then be verified externally to git.</p>
\r
1749 <p>Note that despite the tag features, "git" itself only handles content
\r
1750 integrity; the trust framework (and signature provision and
\r
1751 verification) has to come from outside.</p>
\r
1752 <p>A tag is created with <a href="git-mktag.html">git-mktag(1)</a>,
\r
1753 its data can be accessed by <a href="git-cat-file.html">git-cat-file(1)</a>,
\r
1754 and the signature can be verified by
\r
1755 <a href="git-verify-tag.html">git-verify-tag(1)</a>.</p>
\r
1757 <h2>The "index" aka "Current Directory Cache"</h2>
\r
1758 <div class="sectionbody">
\r
1759 <p>The index is a simple binary file, which contains an efficient
\r
1760 representation of a virtual directory content at some random time. It
\r
1761 does so by a simple array that associates a set of names, dates,
\r
1762 permissions and content (aka "blob") objects together. The cache is
\r
1763 always kept ordered by name, and names are unique (with a few very
\r
1764 specific rules) at any point in time, but the cache has no long-term
\r
1765 meaning, and can be partially updated at any time.</p>
\r
1766 <p>In particular, the index certainly does not need to be consistent with
\r
1767 the current directory contents (in fact, most operations will depend on
\r
1768 different ways to make the index <em>not</em> be consistent with the directory
\r
1769 hierarchy), but it has three very important attributes:</p>
\r
1770 <p><em>(a) it can re-generate the full state it caches (not just the
\r
1771 directory structure: it contains pointers to the "blob" objects so
\r
1772 that it can regenerate the data too)</em></p>
\r
1773 <p>As a special case, there is a clear and unambiguous one-way mapping
\r
1774 from a current directory cache to a "tree object", which can be
\r
1775 efficiently created from just the current directory cache without
\r
1776 actually looking at any other data. So a directory cache at any one
\r
1777 time uniquely specifies one and only one "tree" object (but has
\r
1778 additional data to make it easy to match up that tree object with what
\r
1779 has happened in the directory)</p>
\r
1780 <p><em>(b) it has efficient methods for finding inconsistencies between that
\r
1781 cached state ("tree object waiting to be instantiated") and the
\r
1782 current state.</em></p>
\r
1783 <p><em>(c) it can additionally efficiently represent information about merge
\r
1784 conflicts between different tree objects, allowing each pathname to be
\r
1785 associated with sufficient information about the trees involved that
\r
1786 you can create a three-way merge between them.</em></p>
\r
1787 <p>Those are the three ONLY things that the directory cache does. It's a
\r
1788 cache, and the normal operation is to re-generate it completely from a
\r
1789 known tree object, or update/compare it with a live tree that is being
\r
1790 developed. If you blow the directory cache away entirely, you generally
\r
1791 haven't lost any information as long as you have the name of the tree
\r
1792 that it described.</p>
\r
1793 <p>At the same time, the index is at the same time also the
\r
1794 staging area for creating new trees, and creating a new tree always
\r
1795 involves a controlled modification of the index file. In particular,
\r
1796 the index file can have the representation of an intermediate tree that
\r
1797 has not yet been instantiated. So the index can be thought of as a
\r
1798 write-back cache, which can contain dirty information that has not yet
\r
1799 been written back to the backing store.</p>
\r
1801 <h2>The Workflow</h2>
\r
1802 <div class="sectionbody">
\r
1803 <p>Generally, all "git" operations work on the index file. Some operations
\r
1804 work <strong>purely</strong> on the index file (showing the current state of the
\r
1805 index), but most operations move data to and from the index file. Either
\r
1806 from the database or from the working directory. Thus there are four
\r
1807 main combinations:</p>
\r
1808 <h3>1) working directory -> index</h3>
\r
1809 <p>You update the index with information from the working directory with
\r
1810 the <a href="git-update-index.html">git-update-index(1)</a> command. You
\r
1811 generally update the index information by just specifying the filename
\r
1812 you want to update, like so:</p>
\r
1813 <div class="literalblock">
\r
1814 <div class="content">
\r
1815 <pre><tt>git-update-index filename</tt></pre>
\r
1817 <p>but to avoid common mistakes with filename globbing etc, the command
\r
1818 will not normally add totally new entries or remove old entries,
\r
1819 i.e. it will normally just update existing cache entries.</p>
\r
1820 <p>To tell git that yes, you really do realize that certain files no
\r
1821 longer exist, or that new files should be added, you
\r
1822 should use the <tt>--remove</tt> and <tt>--add</tt> flags respectively.</p>
\r
1823 <p>NOTE! A <tt>--remove</tt> flag does <em>not</em> mean that subsequent filenames will
\r
1824 necessarily be removed: if the files still exist in your directory
\r
1825 structure, the index will be updated with their new status, not
\r
1826 removed. The only thing <tt>--remove</tt> means is that update-cache will be
\r
1827 considering a removed file to be a valid thing, and if the file really
\r
1828 does not exist any more, it will update the index accordingly.</p>
\r
1829 <p>As a special case, you can also do <tt>git-update-index --refresh</tt>, which
\r
1830 will refresh the "stat" information of each index to match the current
\r
1831 stat information. It will <em>not</em> update the object status itself, and
\r
1832 it will only update the fields that are used to quickly test whether
\r
1833 an object still matches its old backing store object.</p>
\r
1834 <h3>2) index -> object database</h3>
\r
1835 <p>You write your current index file to a "tree" object with the program</p>
\r
1836 <div class="literalblock">
\r
1837 <div class="content">
\r
1838 <pre><tt>git-write-tree</tt></pre>
\r
1840 <p>that doesn't come with any options - it will just write out the
\r
1841 current index into the set of tree objects that describe that state,
\r
1842 and it will return the name of the resulting top-level tree. You can
\r
1843 use that tree to re-generate the index at any time by going in the
\r
1844 other direction:</p>
\r
1845 <h3>3) object database -> index</h3>
\r
1846 <p>You read a "tree" file from the object database, and use that to
\r
1847 populate (and overwrite - don't do this if your index contains any
\r
1848 unsaved state that you might want to restore later!) your current
\r
1849 index. Normal operation is just</p>
\r
1850 <div class="literalblock">
\r
1851 <div class="content">
\r
1852 <pre><tt>git-read-tree <sha1 of tree></tt></pre>
\r
1854 <p>and your index file will now be equivalent to the tree that you saved
\r
1855 earlier. However, that is only your <em>index</em> file: your working
\r
1856 directory contents have not been modified.</p>
\r
1857 <h3>4) index -> working directory</h3>
\r
1858 <p>You update your working directory from the index by "checking out"
\r
1859 files. This is not a very common operation, since normally you'd just
\r
1860 keep your files updated, and rather than write to your working
\r
1861 directory, you'd tell the index files about the changes in your
\r
1862 working directory (i.e. <tt>git-update-index</tt>).</p>
\r
1863 <p>However, if you decide to jump to a new version, or check out somebody
\r
1864 else's version, or just restore a previous tree, you'd populate your
\r
1865 index file with read-tree, and then you need to check out the result
\r
1867 <div class="literalblock">
\r
1868 <div class="content">
\r
1869 <pre><tt>git-checkout-index filename</tt></pre>
\r
1871 <p>or, if you want to check out all of the index, use <tt>-a</tt>.</p>
\r
1872 <p>NOTE! git-checkout-index normally refuses to overwrite old files, so
\r
1873 if you have an old version of the tree already checked out, you will
\r
1874 need to use the "-f" flag (<em>before</em> the "-a" flag or the filename) to
\r
1875 <em>force</em> the checkout.</p>
\r
1876 <p>Finally, there are a few odds and ends which are not purely moving
\r
1877 from one representation to the other:</p>
\r
1878 <h3>5) Tying it all together</h3>
\r
1879 <p>To commit a tree you have instantiated with "git-write-tree", you'd
\r
1880 create a "commit" object that refers to that tree and the history
\r
1881 behind it - most notably the "parent" commits that preceded it in
\r
1883 <p>Normally a "commit" has one parent: the previous state of the tree
\r
1884 before a certain change was made. However, sometimes it can have two
\r
1885 or more parent commits, in which case we call it a "merge", due to the
\r
1886 fact that such a commit brings together ("merges") two or more
\r
1887 previous states represented by other commits.</p>
\r
1888 <p>In other words, while a "tree" represents a particular directory state
\r
1889 of a working directory, a "commit" represents that state in "time",
\r
1890 and explains how we got there.</p>
\r
1891 <p>You create a commit object by giving it the tree that describes the
\r
1892 state at the time of the commit, and a list of parents:</p>
\r
1893 <div class="literalblock">
\r
1894 <div class="content">
\r
1895 <pre><tt>git-commit-tree <tree> -p <parent> [-p <parent2> ..]</tt></pre>
\r
1897 <p>and then giving the reason for the commit on stdin (either through
\r
1898 redirection from a pipe or file, or by just typing it at the tty).</p>
\r
1899 <p>git-commit-tree will return the name of the object that represents
\r
1900 that commit, and you should save it away for later use. Normally,
\r
1901 you'd commit a new <tt>HEAD</tt> state, and while git doesn't care where you
\r
1902 save the note about that state, in practice we tend to just write the
\r
1903 result to the file pointed at by <tt>.git/HEAD</tt>, so that we can always see
\r
1904 what the last committed state was.</p>
\r
1905 <p>Here is an ASCII art by Jon Loeliger that illustrates how
\r
1906 various pieces fit together.</p>
\r
1907 <div class="listingblock">
\r
1908 <div class="content">
\r
1934 checkout-index -u | | checkout-index
\r
1943 <h3>6) Examining the data</h3>
\r
1944 <p>You can examine the data represented in the object database and the
\r
1945 index with various helper tools. For every object, you can use
\r
1946 <a href="git-cat-file.html">git-cat-file(1)</a> to examine details about the
\r
1948 <div class="literalblock">
\r
1949 <div class="content">
\r
1950 <pre><tt>git-cat-file -t <objectname></tt></pre>
\r
1952 <p>shows the type of the object, and once you have the type (which is
\r
1953 usually implicit in where you find the object), you can use</p>
\r
1954 <div class="literalblock">
\r
1955 <div class="content">
\r
1956 <pre><tt>git-cat-file blob|tree|commit|tag <objectname></tt></pre>
\r
1958 <p>to show its contents. NOTE! Trees have binary content, and as a result
\r
1959 there is a special helper for showing that content, called
\r
1960 <tt>git-ls-tree</tt>, which turns the binary content into a more easily
\r
1961 readable form.</p>
\r
1962 <p>It's especially instructive to look at "commit" objects, since those
\r
1963 tend to be small and fairly self-explanatory. In particular, if you
\r
1964 follow the convention of having the top commit name in <tt>.git/HEAD</tt>,
\r
1966 <div class="literalblock">
\r
1967 <div class="content">
\r
1968 <pre><tt>git-cat-file commit HEAD</tt></pre>
\r
1970 <p>to see what the top commit was.</p>
\r
1971 <h3>7) Merging multiple trees</h3>
\r
1972 <p>Git helps you do a three-way merge, which you can expand to n-way by
\r
1973 repeating the merge procedure arbitrary times until you finally
\r
1974 "commit" the state. The normal situation is that you'd only do one
\r
1975 three-way merge (two parents), and commit it, but if you like to, you
\r
1976 can do multiple parents in one go.</p>
\r
1977 <p>To do a three-way merge, you need the two sets of "commit" objects
\r
1978 that you want to merge, use those to find the closest common parent (a
\r
1979 third "commit" object), and then use those commit objects to find the
\r
1980 state of the directory ("tree" object) at these points.</p>
\r
1981 <p>To get the "base" for the merge, you first look up the common parent
\r
1982 of two commits with</p>
\r
1983 <div class="literalblock">
\r
1984 <div class="content">
\r
1985 <pre><tt>git-merge-base <commit1> <commit2></tt></pre>
\r
1987 <p>which will return you the commit they are both based on. You should
\r
1988 now look up the "tree" objects of those commits, which you can easily
\r
1989 do with (for example)</p>
\r
1990 <div class="literalblock">
\r
1991 <div class="content">
\r
1992 <pre><tt>git-cat-file commit <commitname> | head -1</tt></pre>
\r
1994 <p>since the tree object information is always the first line in a commit
\r
1996 <p>Once you know the three trees you are going to merge (the one
\r
1997 "original" tree, aka the common case, and the two "result" trees, aka
\r
1998 the branches you want to merge), you do a "merge" read into the
\r
1999 index. This will complain if it has to throw away your old index contents, so you should
\r
2000 make sure that you've committed those - in fact you would normally
\r
2001 always do a merge against your last commit (which should thus match
\r
2002 what you have in your current index anyway).</p>
\r
2003 <p>To do the merge, do</p>
\r
2004 <div class="literalblock">
\r
2005 <div class="content">
\r
2006 <pre><tt>git-read-tree -m -u <origtree> <yourtree> <targettree></tt></pre>
\r
2008 <p>which will do all trivial merge operations for you directly in the
\r
2009 index file, and you can just write the result out with
\r
2010 <tt>git-write-tree</tt>.</p>
\r
2011 <p>Historical note. We did not have <tt>-u</tt> facility when this
\r
2012 section was first written, so we used to warn that
\r
2013 the merge is done in the index file, not in your
\r
2014 working tree, and your working tree will not match your
\r
2015 index after this step.
\r
2016 This is no longer true. The above command, thanks to <tt>-u</tt>
\r
2017 option, updates your working tree with the merge results for
\r
2018 paths that have been trivially merged.</p>
\r
2019 <h3>8) Merging multiple trees, continued</h3>
\r
2020 <p>Sadly, many merges aren't trivial. If there are files that have
\r
2021 been added.moved or removed, or if both branches have modified the
\r
2022 same file, you will be left with an index tree that contains "merge
\r
2023 entries" in it. Such an index tree can <em>NOT</em> be written out to a tree
\r
2024 object, and you will have to resolve any such merge clashes using
\r
2025 other tools before you can write out the result.</p>
\r
2026 <p>You can examine such index state with <tt>git-ls-files --unmerged</tt>
\r
2027 command. An example:</p>
\r
2028 <div class="listingblock">
\r
2029 <div class="content">
\r
2030 <pre><tt>$ git-read-tree -m $orig HEAD $target
\r
2031 $ git-ls-files --unmerged
\r
2032 100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
\r
2033 100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
\r
2034 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c</tt></pre>
\r
2036 <p>Each line of the <tt>git-ls-files --unmerged</tt> output begins with
\r
2037 the blob mode bits, blob SHA1, <em>stage number</em>, and the
\r
2038 filename. The <em>stage number</em> is git's way to say which tree it
\r
2039 came from: stage 1 corresponds to <tt>$orig</tt> tree, stage 2 <tt>HEAD</tt>
\r
2040 tree, and stage3 <tt>$target</tt> tree.</p>
\r
2041 <p>Earlier we said that trivial merges are done inside
\r
2042 <tt>git-read-tree -m</tt>. For example, if the file did not change
\r
2043 from <tt>$orig</tt> to <tt>HEAD</tt> nor <tt>$target</tt>, or if the file changed
\r
2044 from <tt>$orig</tt> to <tt>HEAD</tt> and <tt>$orig</tt> to <tt>$target</tt> the same way,
\r
2045 obviously the final outcome is what is in <tt>HEAD</tt>. What the
\r
2046 above example shows is that file <tt>hello.c</tt> was changed from
\r
2047 <tt>$orig</tt> to <tt>HEAD</tt> and <tt>$orig</tt> to <tt>$target</tt> in a different way.
\r
2048 You could resolve this by running your favorite 3-way merge
\r
2049 program, e.g. <tt>diff3</tt> or <tt>merge</tt>, on the blob objects from
\r
2050 these three stages yourself, like this:</p>
\r
2051 <div class="listingblock">
\r
2052 <div class="content">
\r
2053 <pre><tt>$ git-cat-file blob 263414f... >hello.c~1
\r
2054 $ git-cat-file blob 06fa6a2... >hello.c~2
\r
2055 $ git-cat-file blob cc44c73... >hello.c~3
\r
2056 $ merge hello.c~2 hello.c~1 hello.c~3</tt></pre>
\r
2058 <p>This would leave the merge result in <tt>hello.c~2</tt> file, along
\r
2059 with conflict markers if there are conflicts. After verifying
\r
2060 the merge result makes sense, you can tell git what the final
\r
2061 merge result for this file is by:</p>
\r
2062 <div class="literalblock">
\r
2063 <div class="content">
\r
2064 <pre><tt>mv -f hello.c~2 hello.c
\r
2065 git-update-index hello.c</tt></pre>
\r
2067 <p>When a path is in unmerged state, running <tt>git-update-index</tt> for
\r
2068 that path tells git to mark the path resolved.</p>
\r
2069 <p>The above is the description of a git merge at the lowest level,
\r
2070 to help you understand what conceptually happens under the hood.
\r
2071 In practice, nobody, not even git itself, uses three <tt>git-cat-file</tt>
\r
2072 for this. There is <tt>git-merge-index</tt> program that extracts the
\r
2073 stages to temporary files and calls a "merge" script on it:</p>
\r
2074 <div class="literalblock">
\r
2075 <div class="content">
\r
2076 <pre><tt>git-merge-index git-merge-one-file hello.c</tt></pre>
\r
2078 <p>and that is what higher level <tt>git resolve</tt> is implemented with.</p>
\r
2081 <div class="sectionbody">
\r
2085 git's founding father is Linus Torvalds <torvalds@osdl.org>.
\r
2090 The current git nurse is Junio C Hamano <junkio@cox.net>.
\r
2095 The git potty was written by Andres Ericsson <ae@op5.se>.
\r
2100 General upbringing is handled by the git-list <git@vger.kernel.org>.
\r
2105 <h2>Documentation</h2>
\r
2106 <div class="sectionbody">
\r
2107 <p>The documentation for git suite was started by David Greaves
\r
2108 <david@dgreaves.com>, and later enhanced greatly by the
\r
2109 contributors on the git-list <git@vger.kernel.org>.</p>
\r
2112 <div class="sectionbody">
\r
2113 <p>Part of the <a href="git.html">git(7)</a> suite</p>
\r
2116 <div id="footer-text">
\r
2117 Last updated 07-Jun-2006 19:51:33 UTC
\r
projects / git.git / blob