Merge git://git.kernel.org/pub/scm/gitk/gitk
authorJunio C Hamano <junkio@cox.net>
Tue, 7 Feb 2006 09:19:49 +0000 (01:19 -0800)
committerJunio C Hamano <junkio@cox.net>
Tue, 7 Feb 2006 09:19:49 +0000 (01:19 -0800)
* git://git.kernel.org/pub/scm/gitk/gitk:
  gitk: Use git-diff-tree --cc for showing the diffs for merges
  gitk: Add braces around if expressions

431 files changed:
.gitignore [new file with mode: 0644]
COPYING [new file with mode: 0644]
Documentation/.gitignore [new file with mode: 0644]
Documentation/Makefile [new file with mode: 0644]
Documentation/SubmittingPatches [new file with mode: 0644]
Documentation/asciidoc.conf [new file with mode: 0644]
Documentation/build-docdep.perl [new file with mode: 0755]
Documentation/core-tutorial.txt [new file with mode: 0644]
Documentation/cvs-migration.txt [new file with mode: 0644]
Documentation/diff-format.txt [new file with mode: 0644]
Documentation/diff-options.txt [new file with mode: 0644]
Documentation/diffcore.txt [new file with mode: 0644]
Documentation/everyday.txt [new file with mode: 0644]
Documentation/fetch-options.txt [new file with mode: 0644]
Documentation/git-add.txt [new file with mode: 0644]
Documentation/git-am.txt [new file with mode: 0644]
Documentation/git-apply.txt [new file with mode: 0644]
Documentation/git-applymbox.txt [new file with mode: 0644]
Documentation/git-applypatch.txt [new file with mode: 0644]
Documentation/git-archimport.txt [new file with mode: 0644]
Documentation/git-bisect.txt [new file with mode: 0644]
Documentation/git-branch.txt [new file with mode: 0644]
Documentation/git-cat-file.txt [new file with mode: 0644]
Documentation/git-check-ref-format.txt [new file with mode: 0644]
Documentation/git-checkout-index.txt [new file with mode: 0644]
Documentation/git-checkout.txt [new file with mode: 0644]
Documentation/git-cherry-pick.txt [new file with mode: 0644]
Documentation/git-cherry.txt [new file with mode: 0644]
Documentation/git-clone-pack.txt [new file with mode: 0644]
Documentation/git-clone.txt [new file with mode: 0644]
Documentation/git-commit-tree.txt [new file with mode: 0644]
Documentation/git-commit.txt [new file with mode: 0644]
Documentation/git-convert-objects.txt [new file with mode: 0644]
Documentation/git-count-objects.txt [new file with mode: 0644]
Documentation/git-cvsexportcommit.txt [new file with mode: 0644]
Documentation/git-cvsimport.txt [new file with mode: 0644]
Documentation/git-daemon.txt [new file with mode: 0644]
Documentation/git-describe.txt [new file with mode: 0644]
Documentation/git-diff-files.txt [new file with mode: 0644]
Documentation/git-diff-index.txt [new file with mode: 0644]
Documentation/git-diff-stages.txt [new file with mode: 0644]
Documentation/git-diff-tree.txt [new file with mode: 0644]
Documentation/git-diff.txt [new file with mode: 0644]
Documentation/git-fetch-pack.txt [new file with mode: 0644]
Documentation/git-fetch.txt [new file with mode: 0644]
Documentation/git-fmt-merge-msg.txt [new file with mode: 0644]
Documentation/git-format-patch.txt [new file with mode: 0644]
Documentation/git-fsck-objects.txt [new file with mode: 0644]
Documentation/git-get-tar-commit-id.txt [new file with mode: 0644]
Documentation/git-grep.txt [new file with mode: 0644]
Documentation/git-hash-object.txt [new file with mode: 0644]
Documentation/git-http-fetch.txt [new file with mode: 0644]
Documentation/git-http-push.txt [new file with mode: 0644]
Documentation/git-index-pack.txt [new file with mode: 0644]
Documentation/git-init-db.txt [new file with mode: 0644]
Documentation/git-local-fetch.txt [new file with mode: 0644]
Documentation/git-log.txt [new file with mode: 0644]
Documentation/git-lost-found.txt [new file with mode: 0644]
Documentation/git-ls-files.txt [new file with mode: 0644]
Documentation/git-ls-remote.txt [new file with mode: 0644]
Documentation/git-ls-tree.txt [new file with mode: 0644]
Documentation/git-mailinfo.txt [new file with mode: 0644]
Documentation/git-mailsplit.txt [new file with mode: 0644]
Documentation/git-merge-base.txt [new file with mode: 0644]
Documentation/git-merge-index.txt [new file with mode: 0644]
Documentation/git-merge-one-file.txt [new file with mode: 0644]
Documentation/git-merge.txt [new file with mode: 0644]
Documentation/git-mktag.txt [new file with mode: 0644]
Documentation/git-mv.txt [new file with mode: 0644]
Documentation/git-name-rev.txt [new file with mode: 0644]
Documentation/git-pack-objects.txt [new file with mode: 0644]
Documentation/git-pack-redundant.txt [new file with mode: 0644]
Documentation/git-parse-remote.txt [new file with mode: 0644]
Documentation/git-patch-id.txt [new file with mode: 0644]
Documentation/git-peek-remote.txt [new file with mode: 0644]
Documentation/git-prune-packed.txt [new file with mode: 0644]
Documentation/git-prune.txt [new file with mode: 0644]
Documentation/git-pull.txt [new file with mode: 0644]
Documentation/git-push.txt [new file with mode: 0644]
Documentation/git-read-tree.txt [new file with mode: 0644]
Documentation/git-rebase.txt [new file with mode: 0644]
Documentation/git-receive-pack.txt [new file with mode: 0644]
Documentation/git-relink.txt [new file with mode: 0644]
Documentation/git-repack.txt [new file with mode: 0644]
Documentation/git-repo-config.txt [new file with mode: 0644]
Documentation/git-request-pull.txt [new file with mode: 0644]
Documentation/git-rerere.txt [new file with mode: 0644]
Documentation/git-reset.txt [new file with mode: 0644]
Documentation/git-resolve.txt [new file with mode: 0644]
Documentation/git-rev-list.txt [new file with mode: 0644]
Documentation/git-rev-parse.txt [new file with mode: 0644]
Documentation/git-revert.txt [new file with mode: 0644]
Documentation/git-send-email.txt [new file with mode: 0644]
Documentation/git-send-pack.txt [new file with mode: 0644]
Documentation/git-sh-setup.txt [new file with mode: 0644]
Documentation/git-shell.txt [new file with mode: 0644]
Documentation/git-shortlog.txt [new file with mode: 0644]
Documentation/git-show-branch.txt [new file with mode: 0644]
Documentation/git-show-index.txt [new file with mode: 0644]
Documentation/git-ssh-fetch.txt [new file with mode: 0644]
Documentation/git-ssh-upload.txt [new file with mode: 0644]
Documentation/git-status.txt [new file with mode: 0644]
Documentation/git-stripspace.txt [new file with mode: 0644]
Documentation/git-svnimport.txt [new file with mode: 0644]
Documentation/git-symbolic-ref.txt [new file with mode: 0644]
Documentation/git-tag.txt [new file with mode: 0644]
Documentation/git-tar-tree.txt [new file with mode: 0644]
Documentation/git-unpack-file.txt [new file with mode: 0644]
Documentation/git-unpack-objects.txt [new file with mode: 0644]
Documentation/git-update-index.txt [new file with mode: 0644]
Documentation/git-update-ref.txt [new file with mode: 0644]
Documentation/git-update-server-info.txt [new file with mode: 0644]
Documentation/git-upload-pack.txt [new file with mode: 0644]
Documentation/git-var.txt [new file with mode: 0644]
Documentation/git-verify-pack.txt [new file with mode: 0644]
Documentation/git-verify-tag.txt [new file with mode: 0644]
Documentation/git-whatchanged.txt [new file with mode: 0644]
Documentation/git-write-tree.txt [new file with mode: 0644]
Documentation/git.txt [new file with mode: 0644]
Documentation/gitk.txt [new file with mode: 0644]
Documentation/glossary.txt [new file with mode: 0644]
Documentation/hooks.txt [new file with mode: 0644]
Documentation/howto-index.sh [new file with mode: 0755]
Documentation/howto/isolate-bugs-with-bisect.txt [new file with mode: 0644]
Documentation/howto/make-dist.txt [new file with mode: 0644]
Documentation/howto/rebase-and-edit.txt [new file with mode: 0644]
Documentation/howto/rebase-from-internal-branch.txt [new file with mode: 0644]
Documentation/howto/rebuild-from-update-hook.txt [new file with mode: 0644]
Documentation/howto/revert-branch-rebase.txt [new file with mode: 0644]
Documentation/howto/update-hook-example.txt [new file with mode: 0644]
Documentation/howto/using-topic-branches.txt [new file with mode: 0644]
Documentation/install-webdoc.sh [new file with mode: 0755]
Documentation/merge-options.txt [new file with mode: 0644]
Documentation/merge-strategies.txt [new file with mode: 0644]
Documentation/pull-fetch-param.txt [new file with mode: 0644]
Documentation/repository-layout.txt [new file with mode: 0644]
Documentation/sort_glossary.pl [new file with mode: 0644]
Documentation/technical/pack-protocol.txt [new file with mode: 0644]
Documentation/technical/trivial-merge.txt [new file with mode: 0644]
Documentation/tutorial.txt [new file with mode: 0644]
Documentation/urls.txt [new file with mode: 0644]
GIT-VERSION-GEN [new file with mode: 0755]
INSTALL [new file with mode: 0644]
Makefile [new file with mode: 0644]
README [new file with mode: 0644]
apply.c [new file with mode: 0644]
arm/sha1.c [new file with mode: 0644]
arm/sha1.h [new file with mode: 0644]
arm/sha1_arm.S [new file with mode: 0644]
blob.c [new file with mode: 0644]
blob.h [new file with mode: 0644]
cache.h [new file with mode: 0644]
cat-file.c [new file with mode: 0644]
check-ref-format.c [new file with mode: 0644]
checkout-index.c [new file with mode: 0644]
clone-pack.c [new file with mode: 0644]
combine-diff.c [new file with mode: 0644]
commit-tree.c [new file with mode: 0644]
commit.c [new file with mode: 0644]
commit.h [new file with mode: 0644]
compat/mmap.c [new file with mode: 0644]
compat/setenv.c [new file with mode: 0644]
compat/strcasestr.c [new file with mode: 0644]
compat/subprocess.py [new file with mode: 0644]
compat/unsetenv.c [new file with mode: 0644]
config.c [new file with mode: 0644]
connect.c [new file with mode: 0644]
convert-objects.c [new file with mode: 0644]
copy.c [new file with mode: 0644]
count-delta.c [new file with mode: 0644]
count-delta.h [new file with mode: 0644]
csum-file.c [new file with mode: 0644]
csum-file.h [new file with mode: 0644]
ctype.c [new file with mode: 0644]
daemon.c [new file with mode: 0644]
date.c [new file with mode: 0644]
delta.h [new file with mode: 0644]
describe.c [new file with mode: 0644]
diff-delta.c [new file with mode: 0644]
diff-files.c [new file with mode: 0644]
diff-index.c [new file with mode: 0644]
diff-stages.c [new file with mode: 0644]
diff-tree.c [new file with mode: 0644]
diff.c [new file with mode: 0644]
diff.h [new file with mode: 0644]
diffcore-break.c [new file with mode: 0644]
diffcore-order.c [new file with mode: 0644]
diffcore-pathspec.c [new file with mode: 0644]
diffcore-pickaxe.c [new file with mode: 0644]
diffcore-rename.c [new file with mode: 0644]
diffcore.h [new file with mode: 0644]
entry.c [new file with mode: 0644]
environment.c [new file with mode: 0644]
epoch.c [new file with mode: 0644]
epoch.h [new file with mode: 0644]
exec_cmd.c [new file with mode: 0644]
exec_cmd.h [new file with mode: 0644]
fetch-clone.c [new file with mode: 0644]
fetch-pack.c [new file with mode: 0644]
fetch.c [new file with mode: 0644]
fetch.h [new file with mode: 0644]
fsck-objects.c [new file with mode: 0644]
get-tar-commit-id.c [new file with mode: 0644]
git-add.sh [new file with mode: 0755]
git-am.sh [new file with mode: 0755]
git-applymbox.sh [new file with mode: 0755]
git-applypatch.sh [new file with mode: 0755]
git-archimport.perl [new file with mode: 0755]
git-bisect.sh [new file with mode: 0755]
git-branch.sh [new file with mode: 0755]
git-checkout.sh [new file with mode: 0755]
git-cherry.sh [new file with mode: 0755]
git-clone.sh [new file with mode: 0755]
git-commit.sh [new file with mode: 0755]
git-compat-util.h [new file with mode: 0644]
git-count-objects.sh [new file with mode: 0755]
git-cvsexportcommit.perl [new file with mode: 0755]
git-cvsimport.perl [new file with mode: 0755]
git-diff.sh [new file with mode: 0755]
git-fetch.sh [new file with mode: 0755]
git-fmt-merge-msg.perl [new file with mode: 0755]
git-format-patch.sh [new file with mode: 0755]
git-grep.sh [new file with mode: 0755]
git-log.sh [new file with mode: 0755]
git-lost-found.sh [new file with mode: 0755]
git-ls-remote.sh [new file with mode: 0755]
git-merge-octopus.sh [new file with mode: 0755]
git-merge-one-file.sh [new file with mode: 0755]
git-merge-ours.sh [new file with mode: 0755]
git-merge-recursive.py [new file with mode: 0755]
git-merge-resolve.sh [new file with mode: 0755]
git-merge-stupid.sh [new file with mode: 0755]
git-merge.sh [new file with mode: 0755]
git-mv.perl [new file with mode: 0755]
git-parse-remote.sh [new file with mode: 0755]
git-prune.sh [new file with mode: 0755]
git-pull.sh [new file with mode: 0755]
git-push.sh [new file with mode: 0755]
git-rebase.sh [new file with mode: 0755]
git-relink.perl [new file with mode: 0755]
git-repack.sh [new file with mode: 0755]
git-request-pull.sh [new file with mode: 0755]
git-rerere.perl [new file with mode: 0755]
git-reset.sh [new file with mode: 0755]
git-resolve.sh [new file with mode: 0755]
git-revert.sh [new file with mode: 0755]
git-send-email.perl [new file with mode: 0755]
git-sh-setup.sh [new file with mode: 0755]
git-shortlog.perl [new file with mode: 0755]
git-status.sh [new file with mode: 0755]
git-svnimport.perl [new file with mode: 0755]
git-tag.sh [new file with mode: 0755]
git-verify-tag.sh [new file with mode: 0755]
git-whatchanged.sh [new file with mode: 0755]
git.c [new file with mode: 0644]
git.spec.in [new file with mode: 0644]
gitMergeCommon.py [new file with mode: 0644]
hash-object.c [new file with mode: 0644]
http-fetch.c [new file with mode: 0644]
http-push.c [new file with mode: 0644]
http.c [new file with mode: 0644]
http.h [new file with mode: 0644]
ident.c [new file with mode: 0644]
index-pack.c [new file with mode: 0644]
index.c [new file with mode: 0644]
init-db.c [new file with mode: 0644]
local-fetch.c [new file with mode: 0644]
ls-files.c [new file with mode: 0644]
ls-tree.c [new file with mode: 0644]
mailinfo.c [new file with mode: 0644]
mailsplit.c [new file with mode: 0644]
merge-base.c [new file with mode: 0644]
merge-index.c [new file with mode: 0644]
mktag.c [new file with mode: 0644]
mozilla-sha1/sha1.c [new file with mode: 0644]
mozilla-sha1/sha1.h [new file with mode: 0644]
name-rev.c [new file with mode: 0644]
object.c [new file with mode: 0644]
object.h [new file with mode: 0644]
pack-check.c [new file with mode: 0644]
pack-objects.c [new file with mode: 0644]
pack-redundant.c [new file with mode: 0644]
pack.h [new file with mode: 0644]
patch-delta.c [new file with mode: 0644]
patch-id.c [new file with mode: 0644]
path.c [new file with mode: 0644]
peek-remote.c [new file with mode: 0644]
pkt-line.c [new file with mode: 0644]
pkt-line.h [new file with mode: 0644]
ppc/sha1.c [new file with mode: 0644]
ppc/sha1.h [new file with mode: 0644]
ppc/sha1ppc.S [new file with mode: 0644]
prune-packed.c [new file with mode: 0644]
quote.c [new file with mode: 0644]
quote.h [new file with mode: 0644]
read-cache.c [new file with mode: 0644]
read-tree.c [new file with mode: 0644]
receive-pack.c [new file with mode: 0644]
refs.c [new file with mode: 0644]
refs.h [new file with mode: 0644]
repo-config.c [new file with mode: 0644]
rev-list.c [new file with mode: 0644]
rev-parse.c [new file with mode: 0644]
rsh.c [new file with mode: 0644]
rsh.h [new file with mode: 0644]
run-command.c [new file with mode: 0644]
run-command.h [new file with mode: 0644]
send-pack.c [new file with mode: 0644]
server-info.c [new file with mode: 0644]
setup.c [new file with mode: 0644]
sha1_file.c [new file with mode: 0644]
sha1_name.c [new file with mode: 0644]
shell.c [new file with mode: 0644]
show-branch.c [new file with mode: 0644]
show-index.c [new file with mode: 0644]
ssh-fetch.c [new file with mode: 0644]
ssh-pull.c [new file with mode: 0644]
ssh-push.c [new file with mode: 0644]
ssh-upload.c [new file with mode: 0644]
strbuf.c [new file with mode: 0644]
strbuf.h [new file with mode: 0644]
stripspace.c [new file with mode: 0644]
symbolic-ref.c [new file with mode: 0644]
t/Makefile [new file with mode: 0644]
t/README [new file with mode: 0644]
t/diff-lib.sh [new file with mode: 0755]
t/lib-read-tree-m-3way.sh [new file with mode: 0755]
t/t0000-basic.sh [new file with mode: 0755]
t/t0010-racy-git.sh [new file with mode: 0755]
t/t1000-read-tree-m-3way.sh [new file with mode: 0755]
t/t1001-read-tree-m-2way.sh [new file with mode: 0755]
t/t1002-read-tree-m-u-2way.sh [new file with mode: 0755]
t/t1100-commit-tree-options.sh [new file with mode: 0755]
t/t1200-tutorial.sh [new file with mode: 0755]
t/t1300-repo-config.sh [new file with mode: 0755]
t/t2000-checkout-cache-clash.sh [new file with mode: 0755]
t/t2001-checkout-cache-clash.sh [new file with mode: 0755]
t/t2002-checkout-cache-u.sh [new file with mode: 0755]
t/t2003-checkout-cache-mkdir.sh [new file with mode: 0755]
t/t2100-update-cache-badpath.sh [new file with mode: 0755]
t/t3000-ls-files-others.sh [new file with mode: 0755]
t/t3001-ls-files-others-exclude.sh [new file with mode: 0755]
t/t3002-ls-files-dashpath.sh [new file with mode: 0755]
t/t3010-ls-files-killed-modified.sh [new file with mode: 0755]
t/t3100-ls-tree-restrict.sh [new file with mode: 0755]
t/t3101-ls-tree-dirname.sh [new file with mode: 0755]
t/t3200-branch.sh [new file with mode: 0755]
t/t3300-funny-names.sh [new file with mode: 0755]
t/t3400-rebase.sh [new file with mode: 0755]
t/t3401-rebase-partial.sh [new file with mode: 0755]
t/t3500-cherry.sh [new file with mode: 0755]
t/t4000-diff-format.sh [new file with mode: 0755]
t/t4001-diff-rename.sh [new file with mode: 0755]
t/t4002-diff-basic.sh [new file with mode: 0755]
t/t4003-diff-rename-1.sh [new file with mode: 0755]
t/t4004-diff-rename-symlink.sh [new file with mode: 0755]
t/t4005-diff-rename-2.sh [new file with mode: 0755]
t/t4006-diff-mode.sh [new file with mode: 0755]
t/t4007-rename-3.sh [new file with mode: 0755]
t/t4008-diff-break-rewrite.sh [new file with mode: 0755]
t/t4009-diff-rename-4.sh [new file with mode: 0755]
t/t4010-diff-pathspec.sh [new file with mode: 0755]
t/t4011-diff-symlink.sh [new file with mode: 0755]
t/t4100-apply-stat.sh [new file with mode: 0755]
t/t4100/t-apply-1.expect [new file with mode: 0644]
t/t4100/t-apply-1.patch [new file with mode: 0644]
t/t4100/t-apply-2.expect [new file with mode: 0644]
t/t4100/t-apply-2.patch [new file with mode: 0644]
t/t4100/t-apply-3.expect [new file with mode: 0644]
t/t4100/t-apply-3.patch [new file with mode: 0644]
t/t4100/t-apply-4.expect [new file with mode: 0644]
t/t4100/t-apply-4.patch [new file with mode: 0644]
t/t4100/t-apply-5.expect [new file with mode: 0644]
t/t4100/t-apply-5.patch [new file with mode: 0644]
t/t4100/t-apply-6.expect [new file with mode: 0644]
t/t4100/t-apply-6.patch [new file with mode: 0644]
t/t4100/t-apply-7.expect [new file with mode: 0644]
t/t4100/t-apply-7.patch [new file with mode: 0644]
t/t4101-apply-nonl.sh [new file with mode: 0755]
t/t4102-apply-rename.sh [new file with mode: 0755]
t/t4103-apply-binary.sh [new file with mode: 0755]
t/t4109-apply-multifrag.sh [new file with mode: 0755]
t/t4110-apply-scan.sh [new file with mode: 0755]
t/t4112-apply-renames.sh [new file with mode: 0755]
t/t5000-tar-tree.sh [new file with mode: 0755]
t/t5300-pack-object.sh [new file with mode: 0755]
t/t5400-send-pack.sh [new file with mode: 0755]
t/t5500-fetch-pack.sh [new file with mode: 0755]
t/t5501-old-fetch-and-upload.sh [new file with mode: 0755]
t/t6000lib.sh [new file with mode: 0755]
t/t6001-rev-list-merge-order.sh [new file with mode: 0755]
t/t6002-rev-list-bisect.sh [new file with mode: 0755]
t/t6003-rev-list-topo-order.sh [new file with mode: 0755]
t/t6010-merge-base.sh [new file with mode: 0755]
t/t6020-merge-df.sh [new file with mode: 0755]
t/t6021-merge-criss-cross.sh [new file with mode: 0755]
t/t6022-merge-rename.sh [new file with mode: 0755]
t/t6101-rev-parse-parents.sh [new file with mode: 0755]
t/t7001-mv.sh [new file with mode: 0755]
t/test-lib.sh [new file with mode: 0755]
tag.c [new file with mode: 0644]
tag.h [new file with mode: 0644]
tar-tree.c [new file with mode: 0644]
templates/.gitignore [new file with mode: 0644]
templates/Makefile [new file with mode: 0644]
templates/branches-- [new file with mode: 0644]
templates/hooks--applypatch-msg [new file with mode: 0644]
templates/hooks--commit-msg [new file with mode: 0644]
templates/hooks--post-commit [new file with mode: 0644]
templates/hooks--post-update [new file with mode: 0644]
templates/hooks--pre-applypatch [new file with mode: 0644]
templates/hooks--pre-commit [new file with mode: 0644]
templates/hooks--update [new file with mode: 0644]
templates/info--exclude [new file with mode: 0644]
templates/remotes-- [new file with mode: 0644]
templates/this--description [new file with mode: 0644]
test-date.c [new file with mode: 0644]
test-delta.c [new file with mode: 0644]
tree-diff.c [new file with mode: 0644]
tree.c [new file with mode: 0644]
tree.h [new file with mode: 0644]
unpack-file.c [new file with mode: 0644]
unpack-objects.c [new file with mode: 0644]
update-index.c [new file with mode: 0644]
update-ref.c [new file with mode: 0644]
update-server-info.c [new file with mode: 0644]
upload-pack.c [new file with mode: 0644]
usage.c [new file with mode: 0644]
var.c [new file with mode: 0644]
verify-pack.c [new file with mode: 0644]
write-tree.c [new file with mode: 0644]

diff --git a/.gitignore b/.gitignore
new file mode 100644 (file)
index 0000000..513f22e
--- /dev/null
@@ -0,0 +1,125 @@
+GIT-VERSION-FILE
+git
+git-add
+git-am
+git-apply
+git-applymbox
+git-applypatch
+git-archimport
+git-bisect
+git-branch
+git-cat-file
+git-check-ref-format
+git-checkout
+git-checkout-index
+git-cherry
+git-cherry-pick
+git-clone
+git-clone-pack
+git-commit
+git-commit-tree
+git-convert-objects
+git-count-objects
+git-cvsexportcommit
+git-cvsimport
+git-daemon
+git-diff
+git-diff-files
+git-diff-index
+git-diff-stages
+git-diff-tree
+git-describe
+git-fetch
+git-fetch-pack
+git-findtags
+git-fmt-merge-msg
+git-format-patch
+git-fsck-objects
+git-get-tar-commit-id
+git-grep
+git-hash-object
+git-http-fetch
+git-http-push
+git-index-pack
+git-init-db
+git-local-fetch
+git-log
+git-lost-found
+git-ls-files
+git-ls-remote
+git-ls-tree
+git-mailinfo
+git-mailsplit
+git-merge
+git-merge-base
+git-merge-index
+git-merge-octopus
+git-merge-one-file
+git-merge-ours
+git-merge-recursive
+git-merge-resolve
+git-merge-stupid
+git-mktag
+git-name-rev
+git-mv
+git-pack-redundant
+git-pack-objects
+git-parse-remote
+git-patch-id
+git-peek-remote
+git-prune
+git-prune-packed
+git-pull
+git-push
+git-read-tree
+git-rebase
+git-receive-pack
+git-relink
+git-repack
+git-repo-config
+git-request-pull
+git-reset
+git-resolve
+git-rev-list
+git-rev-parse
+git-revert
+git-send-email
+git-send-pack
+git-sh-setup
+git-shell
+git-shortlog
+git-show
+git-show-branch
+git-show-index
+git-ssh-fetch
+git-ssh-pull
+git-ssh-push
+git-ssh-upload
+git-status
+git-stripspace
+git-svnimport
+git-symbolic-ref
+git-tag
+git-tar-tree
+git-unpack-file
+git-unpack-objects
+git-update-index
+git-update-ref
+git-update-server-info
+git-upload-pack
+git-var
+git-verify-pack
+git-verify-tag
+git-whatchanged
+git-write-tree
+git-core-*/?*
+test-date
+test-delta
+*.tar.gz
+*.dsc
+*.deb
+git-core.spec
+*.exe
+libgit.a
+*.o
+*.py[co]
diff --git a/COPYING b/COPYING
new file mode 100644 (file)
index 0000000..6ff87c4
--- /dev/null
+++ b/COPYING
@@ -0,0 +1,361 @@
+
+ Note that the only valid version of the GPL as far as this project
+ is concerned is _this_ particular version of the license (ie v2, not
+ v2.2 or v3.x or whatever), unless explicitly otherwise stated.
+
+ HOWEVER, in order to allow a migration to GPLv3 if that seems like
+ a good idea, I also ask that people involved with the project make
+ their preferences known. In particular, if you trust me to make that
+ decision, you might note so in your copyright message, ie something
+ like
+
+       This file is licensed under the GPL v2, or a later version
+       at the discretion of Linus.
+
+  might avoid issues. But we can also just decide to synchronize and
+  contact all copyright holders on record if/when the occasion arises.
+
+                       Linus Torvalds
+
+----------------------------------------
+
+                   GNU GENERAL PUBLIC LICENSE
+                      Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+                       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                           Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+\f
+                   GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+\f
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+\f
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+\f
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                           NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                    END OF TERMS AND CONDITIONS
+\f
+           How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644 (file)
index 0000000..c87c61a
--- /dev/null
@@ -0,0 +1,7 @@
+*.xml
+*.html
+*.1
+*.7
+howto-index.txt
+doc.dep
+README
diff --git a/Documentation/Makefile b/Documentation/Makefile
new file mode 100644 (file)
index 0000000..a3bca86
--- /dev/null
@@ -0,0 +1,106 @@
+MAN1_TXT=$(wildcard git-*.txt) gitk.txt
+MAN7_TXT=git.txt
+
+DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))
+
+ARTICLES = tutorial
+ARTICLES += core-tutorial
+ARTICLES += cvs-migration
+ARTICLES += diffcore
+ARTICLES += howto-index
+ARTICLES += repository-layout
+ARTICLES += hooks
+ARTICLES += everyday
+# with their own formatting rules.
+SP_ARTICLES = glossary howto/revert-branch-rebase
+
+DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
+
+DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))
+DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))
+
+prefix?=$(HOME)
+bin=$(prefix)/bin
+mandir=$(prefix)/man
+man1=$(mandir)/man1
+man7=$(mandir)/man7
+# DESTDIR=
+
+INSTALL?=install
+
+#
+# Please note that there is a minor bug in asciidoc.
+# The version after 6.0.3 _will_ include the patch found here:
+#   http://marc.theaimsgroup.com/?l=git&m=111558757202243&w=2
+#
+# Until that version is released you may have to apply the patch
+# yourself - yes, all 6 characters of it!
+#
+
+all: html man
+
+html: $(DOC_HTML)
+
+
+man: man1 man7
+man1: $(DOC_MAN1)
+man7: $(DOC_MAN7)
+
+install: man
+       $(INSTALL) -d -m755 $(DESTDIR)/$(man1) $(DESTDIR)/$(man7)
+       $(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1)
+       $(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7)
+
+
+#
+# Determine "include::" file references in asciidoc files.
+#
+doc.dep : $(wildcard *.txt) build-docdep.perl
+       rm -f $@+ $@
+       perl ./build-docdep.perl >$@+
+       mv $@+ $@
+
+-include doc.dep
+
+git.7: README
+
+README: ../README
+       cp $< $@
+
+
+clean:
+       rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep README
+
+%.html : %.txt
+       asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
+
+%.1 %.7 : %.xml
+       xmlto man $<
+
+%.xml : %.txt
+       asciidoc -b docbook -d manpage -f asciidoc.conf $<
+
+git.html: git.txt README
+
+glossary.html : glossary.txt sort_glossary.pl
+       cat $< | \
+       perl sort_glossary.pl | \
+       asciidoc -b xhtml11 - > glossary.html
+
+howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
+       rm -f $@+ $@
+       sh ./howto-index.sh $(wildcard howto/*.txt) >$@+
+       mv $@+ $@
+
+$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
+       asciidoc -b xhtml11 $*.txt
+
+WEBDOC_DEST = /pub/software/scm/git/docs
+
+$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
+       rm -f $@+ $@
+       sed -e '1,/^$$/d' $? | asciidoc -b xhtml11 - >$@+
+       mv $@+ $@
+
+install-webdoc : html
+       sh ./install-webdoc.sh $(WEBDOC_DEST)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
new file mode 100644 (file)
index 0000000..9ccb8f7
--- /dev/null
@@ -0,0 +1,298 @@
+I started reading over the SubmittingPatches document for Linux
+kernel, primarily because I wanted to have a document similar to
+it for the core GIT to make sure people understand what they are
+doing when they write "Signed-off-by" line.
+
+But the patch submission requirements are a lot more relaxed
+here, because the core GIT is thousand times smaller ;-).  So
+here is only the relevant bits.
+
+
+(1) Make separate commits for logically separate changes.
+
+Unless your patch is really trivial, you should not be sending
+out a patch that was generated between your working tree and
+your commit head.  Instead, always make a commit with complete
+commit message and generate a series of patches from your
+repository.  It is a good discipline.
+
+Describe the technical detail of the change(s).
+
+If your description starts to get long, that's a sign that you
+probably need to split up your commit to finer grained pieces.
+
+
+(2) Generate your patch using git/cogito out of your commits.
+
+git diff tools generate unidiff which is the preferred format.
+You do not have to be afraid to use -M option to "git diff" or
+"git format-patch", if your patch involves file renames.  The
+receiving end can handle them just fine.
+
+Please make sure your patch does not include any extra files
+which do not belong in a patch submission.  Make sure to review
+your patch after generating it, to ensure accuracy.  Before
+sending out, please make sure it cleanly applies to the "master"
+branch head.
+
+
+(3) Sending your patches.
+
+People on the git mailing list needs to be able to read and
+comment on the changes you are submitting.  It is important for
+a developer to be able to "quote" your changes, using standard
+e-mail tools, so that they may comment on specific portions of
+your code.  For this reason, all patches should be submitting
+e-mail "inline".  WARNING: Be wary of your MUAs word-wrap
+corrupting your patch.  Do not cut-n-paste your patch.
+
+It is common convention to prefix your subject line with
+[PATCH].  This lets people easily distinguish patches from other
+e-mail discussions.
+
+"git format-patch" command follows the best current practice to
+format the body of an e-mail message.  At the beginning of the
+patch should come your commit message, ending with the
+Signed-off-by: lines, and a line that consists of three dashes,
+followed by the diffstat information and the patch itself.  If
+you are forwarding a patch from somebody else, optionally, at
+the beginning of the e-mail message just before the commit
+message starts, you can put a "From: " line to name that person.
+
+You often want to add additional explanation about the patch,
+other than the commit message itself.  Place such "cover letter"
+material between the three dash lines and the diffstat.
+
+Do not attach the patch as a MIME attachment, compressed or not.
+Do not let your e-mail client send quoted-printable.  Many
+popular e-mail applications will not always transmit a MIME
+attachment as plain text, making it impossible to comment on
+your code.  A MIME attachment also takes a bit more time to
+process.  This does not decrease the likelihood of your
+MIME-attached change being accepted, but it makes it more likely
+that it will be postponed.
+
+Exception:  If your mailer is mangling patches then someone may ask
+you to re-send them using MIME, that is OK.
+
+Do not PGP sign your patch, at least for now.  Most likely, your
+maintainer or other people on the list would not have your PGP
+key and would not bother obtaining it anyway.  Your patch is not
+judged by who you are; a good patch from an unknown origin has a
+far better chance of being accepted than a patch from a known,
+respected origin that is done poorly or does incorrect things.
+
+If you really really really really want to do a PGP signed
+patch, format it as "multipart/signed", not a text/plain message
+that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
+not a text/plain, it's something else.
+
+Note that your maintainer does not necessarily read everything
+on the git mailing list.  If your patch is for discussion first,
+send it "To:" the mailing list, and optionally "cc:" him.  If it
+is trivially correct or after the list reached a consensus, send
+it "To:" the maintainer and optionally "cc:" the list.
+
+
+(6) Sign your work
+
+To improve tracking of who did what, we've borrowed the
+"sign-off" procedure from the Linux kernel project on patches
+that are being emailed around.  Although core GIT is a lot
+smaller project it is a good discipline to follow it.
+
+The sign-off is a simple line at the end of the explanation for
+the patch, which certifies that you wrote it or otherwise have
+the right to pass it on as a open-source patch.  The rules are
+pretty simple: if you can certify the below:
+
+        Developer's Certificate of Origin 1.1
+
+        By making a contribution to this project, I certify that:
+
+        (a) The contribution was created in whole or in part by me and I
+            have the right to submit it under the open source license
+            indicated in the file; or
+
+        (b) The contribution is based upon previous work that, to the best
+            of my knowledge, is covered under an appropriate open source
+            license and I have the right under that license to submit that
+            work with modifications, whether created in whole or in part
+            by me, under the same open source license (unless I am
+            permitted to submit under a different license), as indicated
+            in the file; or
+
+        (c) The contribution was provided directly to me by some other
+            person who certified (a), (b) or (c) and I have not modified
+            it.
+
+       (d) I understand and agree that this project and the contribution
+           are public and that a record of the contribution (including all
+           personal information I submit with it, including my sign-off) is
+           maintained indefinitely and may be redistributed consistent with
+           this project or the open source license(s) involved.
+
+then you just add a line saying
+
+       Signed-off-by: Random J Developer <random@developer.example.org>
+
+Some people also put extra tags at the end.  They'll just be ignored for
+now, but you can do this to mark internal company procedures or just
+point out some special detail about the sign-off.
+
+
+------------------------------------------------
+MUA specific hints
+
+Some of patches I receive or pick up from the list share common
+patterns of breakage.  Please make sure your MUA is set up
+properly not to corrupt whitespaces.  Here are two common ones
+I have seen:
+
+* Empty context lines that do not have _any_ whitespace.
+
+* Non empty context lines that have one extra whitespace at the
+  beginning.
+
+One test you could do yourself if your MUA is set up correctly is:
+
+* Send the patch to yourself, exactly the way you would, except
+  To: and Cc: lines, which would not contain the list and
+  maintainer address.
+
+* Save that patch to a file in UNIX mailbox format.  Call it say
+  a.patch.
+
+* Try to apply to the tip of the "master" branch from the
+  git.git public repository:
+
+    $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
+    $ git checkout test-apply
+    $ git reset --hard
+    $ git applymbox a.patch
+
+If it does not apply correctly, there can be various reasons.
+
+* Your patch itself does not apply cleanly.  That is _bad_ but
+  does not have much to do with your MUA.  Please rebase the
+  patch appropriately.
+
+* Your MUA corrupted your patch; applymbox would complain that
+  the patch does not apply.  Look at .dotest/ subdirectory and
+  see what 'patch' file contains and check for the common
+  corruption patterns mentioned above.
+
+* While you are at it, check what are in 'info' and
+  'final-commit' files as well.  If what is in 'final-commit' is
+  not exactly what you would want to see in the commit log
+  message, it is very likely that your maintainer would end up
+  hand editing the log message when he applies your patch.
+  Things like "Hi, this is my first patch.\n", if you really
+  want to put in the patch e-mail, should come after the
+  three-dash line that signals the end of the commit message.
+
+
+Pine
+----
+
+(Johannes Schindelin)
+
+I don't know how many people still use pine, but for those poor
+souls it may be good to mention that the quell-flowed-text is
+needed for recent versions.
+
+... the "no-strip-whitespace-before-send" option, too. AFAIK it
+was introduced in 4.60.
+
+(Linus Torvalds)
+
+And 4.58 needs at least this.
+
+---
+diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
+Author: Linus Torvalds <torvalds@g5.osdl.org>
+Date:   Mon Aug 15 17:23:51 2005 -0700
+
+    Fix pine whitespace-corruption bug
+
+    There's no excuse for unconditionally removing whitespace from
+    the pico buffers on close.
+
+diff --git a/pico/pico.c b/pico/pico.c
+--- a/pico/pico.c
++++ b/pico/pico.c
+@@ -219,7 +219,9 @@ PICO *pm;
+           switch(pico_all_done){      /* prepare for/handle final events */
+             case COMP_EXIT :          /* already confirmed */
+               packheader();
++#if 0
+               stripwhitespace();
++#endif
+               c |= COMP_EXIT;
+               break;
+
+(Daniel Barkalow)
+
+> A patch to SubmittingPatches, MUA specific help section for
+> users of Pine 4.63 would be very much appreciated.
+
+Ah, it looks like a recent version changed the default behavior to do the
+right thing, and inverted the sense of the configuration option. (Either
+that or Gentoo did it.) So you need to set the
+"no-strip-whitespace-before-send" option, unless the option you have is
+"strip-whitespace-before-send", in which case you should avoid checking
+it.
+
+
+Thunderbird
+-----------
+
+(A Large Angry SCM)
+
+Here are some hints on how to successfully submit patches inline using
+Thunderbird.
+
+This recipe appears to work with the current [*1*] Thunderbird from Suse.
+
+The following Thunderbird extensions are needed:
+       AboutConfig 0.5
+               http://aboutconfig.mozdev.org/
+       External Editor 0.5.4
+               http://extensionroom.mozdev.org/more-info/exteditor
+
+1) Prepare the patch as a text file using your method of choice.
+
+2) Before opening a compose window, use Edit->Account Settings to
+uncheck the "Compose messages in HTML format" setting in the
+"Composition & Addressing" panel of the account to be used to send the
+patch. [*2*]
+
+3) In the main Thunderbird window, _before_ you open the compose window
+for the patch, use Tools->about:config to set the following to the
+indicated values:
+       mailnews.send_plaintext_flowed  => false
+       mailnews.wraplength             => 0
+
+4) Open a compose window and click the external editor icon.
+
+5) In the external editor window, read in the patch file and exit the
+editor normally.
+
+6) Back in the compose window: Add whatever other text you wish to the
+message, complete the addressing and subject fields, and press send.
+
+7) Optionally, undo the about:config/account settings changes made in
+steps 2 & 3.
+
+
+[Footnotes]
+*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
+9.3 professional updates.
+
+*2* It may be possible to do this with about:config and the following
+settings but I haven't tried, yet.
+       mail.html_compose                       => false
+       mail.identity.default.compose_html      => false
+       mail.identity.id?.compose_html          => false
+
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
new file mode 100644 (file)
index 0000000..fa0877d
--- /dev/null
@@ -0,0 +1,26 @@
+## gitlink: macro
+#
+# Usage: gitlink:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show GIT link as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[attributes]
+caret=^
+
+ifdef::backend-docbook[]
+[gitlink-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[gitlink-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
+
+
diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl
new file mode 100755 (executable)
index 0000000..489389c
--- /dev/null
@@ -0,0 +1,50 @@
+#!/usr/bin/perl
+
+my %include = ();
+my %included = ();
+
+for my $text (<*.txt>) {
+    open I, '<', $text || die "cannot read: $text";
+    while (<I>) {
+       if (/^include::/) {
+           chomp;
+           s/^include::\s*//;
+           s/\[\]//;
+           $include{$text}{$_} = 1;
+           $included{$_} = 1;
+       }
+    }
+    close I;
+}
+
+# Do we care about chained includes???
+my $changed = 1;
+while ($changed) {
+    $changed = 0;
+    while (my ($text, $included) = each %include) {
+       for my $i (keys %$included) {
+           # $text has include::$i; if $i includes $j
+           # $text indirectly includes $j.
+           if (exists $include{$i}) {
+               for my $j (keys %{$include{$i}}) {
+                   if (!exists $include{$text}{$j}) {
+                       $include{$text}{$j} = 1;
+                       $included{$j} = 1;
+                       $changed = 1;
+                   }
+               }
+           }
+       }
+    }
+}
+
+while (my ($text, $included) = each %include) {
+    if (! exists $included{$text} &&
+       (my $base = $text) =~ s/\.txt$//) {
+       my ($suffix) = '1';
+       if ($base eq 'git') {
+           $suffix = '7'; # yuck...
+       }
+       print "$base.html $base.$suffix : ", join(" ", keys %$included), "\n";
+    }
+}
diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt
new file mode 100644 (file)
index 0000000..4211c81
--- /dev/null
@@ -0,0 +1,1722 @@
+A short git tutorial
+====================
+
+Introduction
+------------
+
+This is trying to be a short tutorial on setting up and using a git
+repository, mainly because being hands-on and using explicit examples is
+often the best way of explaining what is going on.
+
+In normal life, most people wouldn't use the "core" git programs
+directly, but rather script around them to make them more palatable. 
+Understanding the core git stuff may help some people get those scripts
+done, though, and it may also be instructive in helping people
+understand what it is that the higher-level helper scripts are actually
+doing. 
+
+The core git is often called "plumbing", with the prettier user
+interfaces on top of it called "porcelain". You may not want to use the
+plumbing directly very often, but it can be good to know what the
+plumbing does for when the porcelain isn't flushing.
+
+The material presented here often goes deep describing how things
+work internally.  If you are mostly interested in using git as a
+SCM, you can skip them during your first pass.
+
+[NOTE]
+And those "too deep" descriptions are often marked as Note.
+
+[NOTE]
+If you are already familiar with another version control system,
+like CVS, you may want to take a look at
+link:everyday.html[Everyday GIT in 20 commands or so] first
+before reading this.
+
+
+Creating a git repository
+-------------------------
+
+Creating a new git repository couldn't be easier: all git repositories start
+out empty, and the only thing you need to do is find yourself a
+subdirectory that you want to use as a working tree - either an empty
+one for a totally new project, or an existing working tree that you want
+to import into git. 
+
+For our first example, we're going to start a totally new repository from
+scratch, with no pre-existing files, and we'll call it `git-tutorial`.
+To start up, create a subdirectory for it, change into that
+subdirectory, and initialize the git infrastructure with `git-init-db`:
+
+------------------------------------------------
+$ mkdir git-tutorial
+$ cd git-tutorial
+$ git-init-db
+------------------------------------------------
+
+to which git will reply
+
+----------------
+defaulting to local storage area
+----------------
+
+which is just git's way of saying that you haven't been doing anything
+strange, and that it will have created a local `.git` directory setup for
+your new project. You will now have a `.git` directory, and you can
+inspect that with `ls`. For your new empty project, it should show you
+three entries, among other things:
+
+ - a file called `HEAD`, that has `ref: refs/heads/master` in it.
+   This is similar to a symbolic link and points at
+   `refs/heads/master` relative to the `HEAD` file.
++
+Don't worry about the fact that the file that the `HEAD` link points to
+doesn't even exist yet -- you haven't created the commit that will
+start your `HEAD` development branch yet.
+
+ - a subdirectory called `objects`, which will contain all the
+   objects of your project. You should never have any real reason to
+   look at the objects directly, but you might want to know that these
+   objects are what contains all the real 'data' in your repository.
+
+ - a subdirectory called `refs`, which contains references to objects.
+
+In particular, the `refs` subdirectory will contain two other
+subdirectories, named `heads` and `tags` respectively. They do
+exactly what their names imply: they contain references to any number
+of different 'heads' of development (aka 'branches'), and to any
+'tags' that you have created to name specific versions in your
+repository.
+
+One note: the special `master` head is the default branch, which is
+why the `.git/HEAD` file was created points to it even if it
+doesn't yet exist. Basically, the `HEAD` link is supposed to always
+point to the branch you are working on right now, and you always
+start out expecting to work on the `master` branch.
+
+However, this is only a convention, and you can name your branches
+anything you want, and don't have to ever even 'have' a `master`
+branch. A number of the git tools will assume that `.git/HEAD` is
+valid, though.
+
+[NOTE]
+An 'object' is identified by its 160-bit SHA1 hash, aka 'object name',
+and a reference to an object is always the 40-byte hex
+representation of that SHA1 name. The files in the `refs`
+subdirectory are expected to contain these hex references
+(usually with a final `\'\n\'` at the end), and you should thus
+expect to see a number of 41-byte files containing these
+references in these `refs` subdirectories when you actually start
+populating your tree.
+
+[NOTE]
+An advanced user may want to take a look at the
+link:repository-layout.html[repository layout] document
+after finishing this tutorial.
+
+You have now created your first git repository. Of course, since it's
+empty, that's not very useful, so let's start populating it with data.
+
+
+Populating a git repository
+---------------------------
+
+We'll keep this simple and stupid, so we'll start off with populating a
+few trivial files just to get a feel for it.
+
+Start off with just creating any random files that you want to maintain
+in your git repository. We'll start off with a few bad examples, just to
+get a feel for how this works:
+
+------------------------------------------------
+$ echo "Hello World" >hello
+$ echo "Silly example" >example
+------------------------------------------------
+
+you have now created two files in your working tree (aka 'working directory'),
+but to actually check in your hard work, you will have to go through two steps:
+
+ - fill in the 'index' file (aka 'cache') with the information about your
+   working tree state.
+
+ - commit that index file as an object.
+
+The first step is trivial: when you want to tell git about any changes
+to your working tree, you use the `git-update-index` program. That
+program normally just takes a list of filenames you want to update, but
+to avoid trivial mistakes, it refuses to add new entries to the index
+(or remove existing ones) unless you explicitly tell it that you're
+adding a new entry with the `\--add` flag (or removing an entry with the
+`\--remove`) flag.
+
+So to populate the index with the two files you just created, you can do
+
+------------------------------------------------
+$ git-update-index --add hello example
+------------------------------------------------
+
+and you have now told git to track those two files.
+
+In fact, as you did that, if you now look into your object directory,
+you'll notice that git will have added two new objects to the object
+database. If you did exactly the steps above, you should now be able to do
+
+
+----------------
+$ ls .git/objects/??/*
+----------------
+
+and see two files:
+
+----------------
+.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238 
+.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
+----------------
+
+which correspond with the objects with names of `557db...` and
+`f24c7...` respectively.
+
+If you want to, you can use `git-cat-file` to look at those objects, but
+you'll have to use the object name, not the filename of the object:
+
+----------------
+$ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238
+----------------
+
+where the `-t` tells `git-cat-file` to tell you what the "type" of the
+object is. git will tell you that you have a "blob" object (ie just a
+regular file), and you can see the contents with
+
+----------------
+$ git-cat-file "blob" 557db03
+----------------
+
+which will print out "Hello World". The object `557db03` is nothing
+more than the contents of your file `hello`.
+
+[NOTE]
+Don't confuse that object with the file `hello` itself. The
+object is literally just those specific *contents* of the file, and
+however much you later change the contents in file `hello`, the object
+we just looked at will never change. Objects are immutable.
+
+[NOTE]
+The second example demonstrates that you can
+abbreviate the object name to only the first several
+hexadecimal digits in most places.
+
+Anyway, as we mentioned previously, you normally never actually take a
+look at the objects themselves, and typing long 40-character hex
+names is not something you'd normally want to do. The above digression
+was just to show that `git-update-index` did something magical, and
+actually saved away the contents of your files into the git object
+database.
+
+Updating the index did something else too: it created a `.git/index`
+file. This is the index that describes your current working tree, and
+something you should be very aware of. Again, you normally never worry
+about the index file itself, but you should be aware of the fact that
+you have not actually really "checked in" your files into git so far,
+you've only *told* git about them.
+
+However, since git knows about them, you can now start using some of the
+most basic git commands to manipulate the files or look at their status. 
+
+In particular, let's not even check in the two files into git yet, we'll
+start off by adding another line to `hello` first:
+
+------------------------------------------------
+$ echo "It's a new day for git" >>hello
+------------------------------------------------
+
+and you can now, since you told git about the previous state of `hello`, ask
+git what has changed in the tree compared to your old index, using the
+`git-diff-files` command:
+
+------------
+$ git-diff-files
+------------
+
+Oops. That wasn't very readable. It just spit out its own internal
+version of a `diff`, but that internal version really just tells you
+that it has noticed that "hello" has been modified, and that the old object
+contents it had have been replaced with something else.
+
+To make it readable, we can tell git-diff-files to output the
+differences as a patch, using the `-p` flag:
+
+------------
+$ git-diff-files -p
+diff --git a/hello b/hello
+index 557db03..263414f 100644
+--- a/hello
++++ b/hello
+@@ -1 +1,2 @@
+ Hello World
++It's a new day for git
+----
+
+i.e. the diff of the change we caused by adding another line to `hello`.
+
+In other words, `git-diff-files` always shows us the difference between
+what is recorded in the index, and what is currently in the working
+tree. That's very useful.
+
+A common shorthand for `git-diff-files -p` is to just write `git
+diff`, which will do the same thing.
+
+------------
+$ git diff
+diff --git a/hello b/hello
+index 557db03..263414f 100644
+--- a/hello
++++ b/hello
+@@ -1 +1,2 @@
+ Hello World
++It's a new day for git
+------------
+
+
+Committing git state
+--------------------
+
+Now, we want to go to the next stage in git, which is to take the files
+that git knows about in the index, and commit them as a real tree. We do
+that in two phases: creating a 'tree' object, and committing that 'tree'
+object as a 'commit' object together with an explanation of what the
+tree was all about, along with information of how we came to that state.
+
+Creating a tree object is trivial, and is done with `git-write-tree`.
+There are no options or other input: git-write-tree will take the
+current index state, and write an object that describes that whole
+index. In other words, we're now tying together all the different
+filenames with their contents (and their permissions), and we're
+creating the equivalent of a git "directory" object:
+
+------------------------------------------------
+$ git-write-tree
+------------------------------------------------
+
+and this will just output the name of the resulting tree, in this case
+(if you have done exactly as I've described) it should be
+
+----------------
+8988da15d077d4829fc51d8544c097def6644dbb
+----------------
+
+which is another incomprehensible object name. Again, if you want to,
+you can use `git-cat-file -t 8988d\...` to see that this time the object
+is not a "blob" object, but a "tree" object (you can also use
+`git-cat-file` to actually output the raw object contents, but you'll see
+mainly a binary mess, so that's less interesting).
+
+However -- normally you'd never use `git-write-tree` on its own, because
+normally you always commit a tree into a commit object using the
+`git-commit-tree` command. In fact, it's easier to not actually use
+`git-write-tree` on its own at all, but to just pass its result in as an
+argument to `git-commit-tree`.
+
+`git-commit-tree` normally takes several arguments -- it wants to know
+what the 'parent' of a commit was, but since this is the first commit
+ever in this new repository, and it has no parents, we only need to pass in
+the object name of the tree. However, `git-commit-tree`
+also wants to get a commit message
+on its standard input, and it will write out the resulting object name for the
+commit to its standard output.
+
+And this is where we create the `.git/refs/heads/master` file
+which is pointed at by `HEAD`. This file is supposed to contain
+the reference to the top-of-tree of the master branch, and since
+that's exactly what `git-commit-tree` spits out, we can do this
+all with a sequence of simple shell commands:
+
+------------------------------------------------
+$ tree=$(git-write-tree)
+$ commit=$(echo 'Initial commit' | git-commit-tree $tree)
+$ git-update-ref HEAD $commit
+------------------------------------------------
+
+which will say:
+
+----------------
+Committing initial tree 8988da15d077d4829fc51d8544c097def6644dbb
+----------------
+
+just to warn you about the fact that it created a totally new commit
+that is not related to anything else. Normally you do this only *once*
+for a project ever, and all later commits will be parented on top of an
+earlier commit, and you'll never see this "Committing initial tree"
+message ever again.
+
+Again, normally you'd never actually do this by hand. There is a
+helpful script called `git commit` that will do all of this for you. So
+you could have just written `git commit`
+instead, and it would have done the above magic scripting for you.
+
+
+Making a change
+---------------
+
+Remember how we did the `git-update-index` on file `hello` and then we
+changed `hello` afterward, and could compare the new state of `hello` with the
+state we saved in the index file? 
+
+Further, remember how I said that `git-write-tree` writes the contents
+of the *index* file to the tree, and thus what we just committed was in
+fact the *original* contents of the file `hello`, not the new ones. We did
+that on purpose, to show the difference between the index state, and the
+state in the working tree, and how they don't have to match, even
+when we commit things.
+
+As before, if we do `git-diff-files -p` in our git-tutorial project,
+we'll still see the same difference we saw last time: the index file
+hasn't changed by the act of committing anything. However, now that we
+have committed something, we can also learn to use a new command:
+`git-diff-index`.
+
+Unlike `git-diff-files`, which showed the difference between the index
+file and the working tree, `git-diff-index` shows the differences
+between a committed *tree* and either the index file or the working
+tree. In other words, `git-diff-index` wants a tree to be diffed
+against, and before we did the commit, we couldn't do that, because we
+didn't have anything to diff against. 
+
+But now we can do
+
+----------------
+$ git-diff-index -p HEAD
+----------------
+
+(where `-p` has the same meaning as it did in `git-diff-files`), and it
+will show us the same difference, but for a totally different reason. 
+Now we're comparing the working tree not against the index file,
+but against the tree we just wrote. It just so happens that those two
+are obviously the same, so we get the same result.
+
+Again, because this is a common operation, you can also just shorthand
+it with
+
+----------------
+$ git diff HEAD
+----------------
+
+which ends up doing the above for you.
+
+In other words, `git-diff-index` normally compares a tree against the
+working tree, but when given the `\--cached` flag, it is told to
+instead compare against just the index cache contents, and ignore the
+current working tree state entirely. Since we just wrote the index
+file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return
+an empty set of differences, and that's exactly what it does. 
+
+[NOTE]
+================
+`git-diff-index` really always uses the index for its
+comparisons, and saying that it compares a tree against the working
+tree is thus not strictly accurate. In particular, the list of
+files to compare (the "meta-data") *always* comes from the index file,
+regardless of whether the `\--cached` flag is used or not. The `\--cached`
+flag really only determines whether the file *contents* to be compared
+come from the working tree or not.
+
+This is not hard to understand, as soon as you realize that git simply
+never knows (or cares) about files that it is not told about
+explicitly. git will never go *looking* for files to compare, it
+expects you to tell it what the files are, and that's what the index
+is there for.
+================
+
+However, our next step is to commit the *change* we did, and again, to
+understand what's going on, keep in mind the difference between "working
+tree contents", "index file" and "committed tree". We have changes
+in the working tree that we want to commit, and we always have to
+work through the index file, so the first thing we need to do is to
+update the index cache:
+
+------------------------------------------------
+$ git-update-index hello
+------------------------------------------------
+
+(note how we didn't need the `\--add` flag this time, since git knew
+about the file already).
+
+Note what happens to the different `git-diff-\*` versions here. After
+we've updated `hello` in the index, `git-diff-files -p` now shows no
+differences, but `git-diff-index -p HEAD` still *does* show that the
+current state is different from the state we committed. In fact, now
+`git-diff-index` shows the same difference whether we use the `--cached`
+flag or not, since now the index is coherent with the working tree.
+
+Now, since we've updated `hello` in the index, we can commit the new
+version. We could do it by writing the tree by hand again, and
+committing the tree (this time we'd have to use the `-p HEAD` flag to
+tell commit that the HEAD was the *parent* of the new commit, and that
+this wasn't an initial commit any more), but you've done that once
+already, so let's just use the helpful script this time:
+
+------------------------------------------------
+$ git commit
+------------------------------------------------
+
+which starts an editor for you to write the commit message and tells you
+a bit about what you have done.
+
+Write whatever message you want, and all the lines that start with '#'
+will be pruned out, and the rest will be used as the commit message for
+the change. If you decide you don't want to commit anything after all at
+this point (you can continue to edit things and update the index), you
+can just leave an empty message. Otherwise `git commit` will commit
+the change for you.
+
+You've now made your first real git commit. And if you're interested in
+looking at what `git commit` really does, feel free to investigate:
+it's a few very simple shell scripts to generate the helpful (?) commit
+message headers, and a few one-liners that actually do the
+commit itself (`git-commit`).
+
+
+Inspecting Changes
+------------------
+
+While creating changes is useful, it's even more useful if you can tell
+later what changed. The most useful command for this is another of the
+`diff` family, namely `git-diff-tree`.
+
+`git-diff-tree` can be given two arbitrary trees, and it will tell you the
+differences between them. Perhaps even more commonly, though, you can
+give it just a single commit object, and it will figure out the parent
+of that commit itself, and show the difference directly. Thus, to get
+the same diff that we've already seen several times, we can now do
+
+----------------
+$ git-diff-tree -p HEAD
+----------------
+
+(again, `-p` means to show the difference as a human-readable patch),
+and it will show what the last commit (in `HEAD`) actually changed.
+
+[NOTE]
+============
+Here is an ASCII art by Jon Loeliger that illustrates how
+various diff-\* commands compare things.
+
+                      diff-tree
+                       +----+
+                       |    |
+                       |    |
+                       V    V
+                    +-----------+
+                    | Object DB |
+                    |  Backing  |
+                    |   Store   |
+                    +-----------+
+                      ^    ^
+                      |    |
+                      |    |  diff-index --cached
+                      |    |
+          diff-index  |    V
+                      |  +-----------+
+                      |  |   Index   |
+                      |  |  "cache"  |
+                      |  +-----------+
+                      |    ^
+                      |    |
+                      |    |  diff-files
+                      |    |
+                      V    V
+                    +-----------+
+                    |  Working  |
+                    | Directory |
+                    +-----------+
+============
+
+More interestingly, you can also give `git-diff-tree` the `--pretty` flag,
+which tells it to also show the commit message and author and date of the
+commit, and you can tell it to show a whole series of diffs.
+Alternatively, you can tell it to be "silent", and not show the diffs at
+all, but just show the actual commit message.
+
+In fact, together with the `git-rev-list` program (which generates a
+list of revisions), `git-diff-tree` ends up being a veritable fount of
+changes. A trivial (but very useful) script called `git-whatchanged` is
+included with git which does exactly this, and shows a log of recent
+activities.
+
+To see the whole history of our pitiful little git-tutorial project, you
+can do
+
+----------------
+$ git log
+----------------
+
+which shows just the log messages, or if we want to see the log together
+with the associated patches use the more complex (and much more
+powerful)
+
+----------------
+$ git-whatchanged -p --root
+----------------
+
+and you will see exactly what has changed in the repository over its
+short history. 
+
+[NOTE]
+The `\--root` flag is a flag to `git-diff-tree` to tell it to
+show the initial aka 'root' commit too. Normally you'd probably not
+want to see the initial import diff, but since the tutorial project
+was started from scratch and is so small, we use it to make the result
+a bit more interesting.
+
+With that, you should now be having some inkling of what git does, and
+can explore on your own.
+
+[NOTE]
+Most likely, you are not directly using the core
+git Plumbing commands, but using Porcelain like Cogito on top
+of it. Cogito works a bit differently and you usually do not
+have to run `git-update-index` yourself for changed files (you
+do tell underlying git about additions and removals via
+`cg-add` and `cg-rm` commands). Just before you make a commit
+with `cg-commit`, Cogito figures out which files you modified,
+and runs `git-update-index` on them for you.
+
+
+Tagging a version
+-----------------
+
+In git, there are two kinds of tags, a "light" one, and an "annotated tag".
+
+A "light" tag is technically nothing more than a branch, except we put
+it in the `.git/refs/tags/` subdirectory instead of calling it a `head`.
+So the simplest form of tag involves nothing more than
+
+------------------------------------------------
+$ git tag my-first-tag
+------------------------------------------------
+
+which just writes the current `HEAD` into the `.git/refs/tags/my-first-tag`
+file, after which point you can then use this symbolic name for that
+particular state. You can, for example, do
+
+----------------
+$ git diff my-first-tag
+----------------
+
+to diff your current state against that tag (which at this point will
+obviously be an empty diff, but if you continue to develop and commit
+stuff, you can use your tag as an "anchor-point" to see what has changed
+since you tagged it.
+
+An "annotated tag" is actually a real git object, and contains not only a
+pointer to the state you want to tag, but also a small tag name and
+message, along with optionally a PGP signature that says that yes,
+you really did
+that tag. You create these annotated tags with either the `-a` or
+`-s` flag to `git tag`:
+
+----------------
+$ git tag -s <tagname>
+----------------
+
+which will sign the current `HEAD` (but you can also give it another
+argument that specifies the thing to tag, ie you could have tagged the
+current `mybranch` point by using `git tag <tagname> mybranch`).
+
+You normally only do signed tags for major releases or things
+like that, while the light-weight tags are useful for any marking you
+want to do -- any time you decide that you want to remember a certain
+point, just create a private tag for it, and you have a nice symbolic
+name for the state at that point.
+
+
+Copying repositories
+--------------------
+
+git repositories are normally totally self-sufficient and relocatable
+Unlike CVS, for example, there is no separate notion of
+"repository" and "working tree". A git repository normally *is* the
+working tree, with the local git information hidden in the `.git`
+subdirectory. There is nothing else. What you see is what you got.
+
+[NOTE]
+You can tell git to split the git internal information from
+the directory that it tracks, but we'll ignore that for now: it's not
+how normal projects work, and it's really only meant for special uses.
+So the mental model of "the git information is always tied directly to
+the working tree that it describes" may not be technically 100%
+accurate, but it's a good model for all normal use.
+
+This has two implications: 
+
+ - if you grow bored with the tutorial repository you created (or you've
+   made a mistake and want to start all over), you can just do simple
++
+----------------
+$ rm -rf git-tutorial
+----------------
++
+and it will be gone. There's no external repository, and there's no
+history outside the project you created.
+
+ - if you want to move or duplicate a git repository, you can do so. There
+   is `git clone` command, but if all you want to do is just to
+   create a copy of your repository (with all the full history that
+   went along with it), you can do so with a regular
+   `cp -a git-tutorial new-git-tutorial`.
++
+Note that when you've moved or copied a git repository, your git index
+file (which caches various information, notably some of the "stat"
+information for the files involved) will likely need to be refreshed.
+So after you do a `cp -a` to create a new copy, you'll want to do
++
+----------------
+$ git-update-index --refresh
+----------------
++
+in the new repository to make sure that the index file is up-to-date.
+
+Note that the second point is true even across machines. You can
+duplicate a remote git repository with *any* regular copy mechanism, be it
+`scp`, `rsync` or `wget`.
+
+When copying a remote repository, you'll want to at a minimum update the
+index cache when you do this, and especially with other peoples'
+repositories you often want to make sure that the index cache is in some
+known state (you don't know *what* they've done and not yet checked in),
+so usually you'll precede the `git-update-index` with a
+
+----------------
+$ git-read-tree --reset HEAD
+$ git-update-index --refresh
+----------------
+
+which will force a total index re-build from the tree pointed to by `HEAD`.
+It resets the index contents to `HEAD`, and then the `git-update-index`
+makes sure to match up all index entries with the checked-out files.
+If the original repository had uncommitted changes in its
+working tree, `git-update-index --refresh` notices them and
+tells you they need to be updated.
+
+The above can also be written as simply
+
+----------------
+$ git reset
+----------------
+
+and in fact a lot of the common git command combinations can be scripted
+with the `git xyz` interfaces.  You can learn things by just looking
+at what the various git scripts do.  For example, `git reset` is the
+above two lines implemented in `git-reset`, but some things like
+`git status` and `git commit` are slightly more complex scripts around
+the basic git commands.
+
+Many (most?) public remote repositories will not contain any of
+the checked out files or even an index file, and will *only* contain the
+actual core git files. Such a repository usually doesn't even have the
+`.git` subdirectory, but has all the git files directly in the
+repository. 
+
+To create your own local live copy of such a "raw" git repository, you'd
+first create your own subdirectory for the project, and then copy the
+raw repository contents into the `.git` directory. For example, to
+create your own copy of the git repository, you'd do the following
+
+----------------
+$ mkdir my-git
+$ cd my-git
+$ rsync -rL rsync://rsync.kernel.org/pub/scm/git/git.git/ .git
+----------------
+
+followed by 
+
+----------------
+$ git-read-tree HEAD
+----------------
+
+to populate the index. However, now you have populated the index, and
+you have all the git internal files, but you will notice that you don't
+actually have any of the working tree files to work on. To get
+those, you'd check them out with
+
+----------------
+$ git-checkout-index -u -a
+----------------
+
+where the `-u` flag means that you want the checkout to keep the index
+up-to-date (so that you don't have to refresh it afterward), and the
+`-a` flag means "check out all files" (if you have a stale copy or an
+older version of a checked out tree you may also need to add the `-f`
+flag first, to tell git-checkout-index to *force* overwriting of any old
+files). 
+
+Again, this can all be simplified with
+
+----------------
+$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git
+$ cd my-git
+$ git checkout
+----------------
+
+which will end up doing all of the above for you.
+
+You have now successfully copied somebody else's (mine) remote
+repository, and checked it out. 
+
+
+Creating a new branch
+---------------------
+
+Branches in git are really nothing more than pointers into the git
+object database from within the `.git/refs/` subdirectory, and as we
+already discussed, the `HEAD` branch is nothing but a symlink to one of
+these object pointers. 
+
+You can at any time create a new branch by just picking an arbitrary
+point in the project history, and just writing the SHA1 name of that
+object into a file under `.git/refs/heads/`. You can use any filename you
+want (and indeed, subdirectories), but the convention is that the
+"normal" branch is called `master`. That's just a convention, though,
+and nothing enforces it. 
+
+To show that as an example, let's go back to the git-tutorial repository we
+used earlier, and create a branch in it. You do that by simply just
+saying that you want to check out a new branch:
+
+------------
+$ git checkout -b mybranch
+------------
+
+will create a new branch based at the current `HEAD` position, and switch
+to it. 
+
+[NOTE]
+================================================
+If you make the decision to start your new branch at some
+other point in the history than the current `HEAD`, you can do so by
+just telling `git checkout` what the base of the checkout would be.
+In other words, if you have an earlier tag or branch, you'd just do
+
+------------
+$ git checkout -b mybranch earlier-commit
+------------
+
+and it would create the new branch `mybranch` at the earlier commit,
+and check out the state at that time.
+================================================
+
+You can always just jump back to your original `master` branch by doing
+
+------------
+$ git checkout master
+------------
+
+(or any other branch-name, for that matter) and if you forget which
+branch you happen to be on, a simple
+
+------------
+$ cat .git/HEAD
+------------
+
+will tell you where it's pointing.  To get the list of branches
+you have, you can say
+
+------------
+$ git branch
+------------
+
+which is nothing more than a simple script around `ls .git/refs/heads`.
+There will be asterisk in front of the branch you are currently on.
+
+Sometimes you may wish to create a new branch _without_ actually
+checking it out and switching to it. If so, just use the command
+
+------------
+$ git branch <branchname> [startingpoint]
+------------
+
+which will simply _create_ the branch, but will not do anything further. 
+You can then later -- once you decide that you want to actually develop
+on that branch -- switch to that branch with a regular `git checkout`
+with the branchname as the argument.
+
+
+Merging two branches
+--------------------
+
+One of the ideas of having a branch is that you do some (possibly
+experimental) work in it, and eventually merge it back to the main
+branch. So assuming you created the above `mybranch` that started out
+being the same as the original `master` branch, let's make sure we're in
+that branch, and do some work there.
+
+------------------------------------------------
+$ git checkout mybranch
+$ echo "Work, work, work" >>hello
+$ git commit -m 'Some work.' -i hello
+------------------------------------------------
+
+Here, we just added another line to `hello`, and we used a shorthand for
+doing both `git-update-index hello` and `git commit` by just giving the
+filename directly to `git commit`, with an `-i` flag (it tells
+git to 'include' that file in addition to what you have done to
+the index file so far when making the commit).  The `-m` flag is to give the
+commit log message from the command line.
+
+Now, to make it a bit more interesting, let's assume that somebody else
+does some work in the original branch, and simulate that by going back
+to the master branch, and editing the same file differently there:
+
+------------
+$ git checkout master
+------------
+
+Here, take a moment to look at the contents of `hello`, and notice how they
+don't contain the work we just did in `mybranch` -- because that work
+hasn't happened in the `master` branch at all. Then do
+
+------------
+$ echo "Play, play, play" >>hello
+$ echo "Lots of fun" >>example
+$ git commit -m 'Some fun.' -i hello example
+------------
+
+since the master branch is obviously in a much better mood.
+
+Now, you've got two branches, and you decide that you want to merge the
+work done. Before we do that, let's introduce a cool graphical tool that
+helps you view what's going on:
+
+----------------
+$ gitk --all
+----------------
+
+will show you graphically both of your branches (that's what the `\--all`
+means: normally it will just show you your current `HEAD`) and their
+histories. You can also see exactly how they came to be from a common
+source. 
+
+Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want
+to merge the work we did on the `mybranch` branch into the `master`
+branch (which is currently our `HEAD` too). To do that, there's a nice
+script called `git merge`, which wants to know which branches you want
+to resolve and what the merge is all about:
+
+------------
+$ git merge "Merge work in mybranch" HEAD mybranch
+------------
+
+where the first argument is going to be used as the commit message if
+the merge can be resolved automatically.
+
+Now, in this case we've intentionally created a situation where the
+merge will need to be fixed up by hand, though, so git will do as much
+of it as it can automatically (which in this case is just merge the `example`
+file, which had no differences in the `mybranch` branch), and say:
+
+----------------
+       Trying really trivial in-index merge...
+       fatal: Merge requires file-level merging
+       Nope.
+       ...
+       Auto-merging hello 
+       CONFLICT (content): Merge conflict in hello 
+       Automatic merge failed; fix up by hand
+----------------
+
+which is way too verbose, but it basically tells you that it failed the
+really trivial merge ("Simple merge") and did an "Automatic merge"
+instead, but that too failed due to conflicts in `hello`.
+
+Not to worry. It left the (trivial) conflict in `hello` in the same form you
+should already be well used to if you've ever used CVS, so let's just
+open `hello` in our editor (whatever that may be), and fix it up somehow.
+I'd suggest just making it so that `hello` contains all four lines:
+
+------------
+Hello World
+It's a new day for git
+Play, play, play
+Work, work, work
+------------
+
+and once you're happy with your manual merge, just do a
+
+------------
+$ git commit -i hello
+------------
+
+which will very loudly warn you that you're now committing a merge
+(which is correct, so never mind), and you can write a small merge
+message about your adventures in git-merge-land.
+
+After you're done, start up `gitk \--all` to see graphically what the
+history looks like. Notice that `mybranch` still exists, and you can
+switch to it, and continue to work with it if you want to. The
+`mybranch` branch will not contain the merge, but next time you merge it
+from the `master` branch, git will know how you merged it, so you'll not
+have to do _that_ merge again.
+
+Another useful tool, especially if you do not always work in X-Window
+environment, is `git show-branch`.
+
+------------------------------------------------
+$ git show-branch --topo-order master mybranch
+* [master] Merge work in mybranch
+ ! [mybranch] Some work.
+--
+-  [master] Merge work in mybranch
+*+ [mybranch] Some work.
+------------------------------------------------
+
+The first two lines indicate that it is showing the two branches
+and the first line of the commit log message from their
+top-of-the-tree commits, you are currently on `master` branch
+(notice the asterisk `*` character), and the first column for
+the later output lines is used to show commits contained in the
+`master` branch, and the second column for the `mybranch`
+branch. Three commits are shown along with their log messages.
+All of them have non blank characters in the first column (`*`
+shows an ordinary commit on the current branch, `.` is a merge commit), which
+means they are now part of the `master` branch. Only the "Some
+work" commit has the plus `+` character in the second column,
+because `mybranch` has not been merged to incorporate these
+commits from the master branch.  The string inside brackets
+before the commit log message is a short name you can use to
+name the commit.  In the above example, 'master' and 'mybranch'
+are branch heads.  'master~1' is the first parent of 'master'
+branch head.  Please see 'git-rev-parse' documentation if you
+see more complex cases.
+
+Now, let's pretend you are the one who did all the work in
+`mybranch`, and the fruit of your hard work has finally been merged
+to the `master` branch. Let's go back to `mybranch`, and run
+resolve to get the "upstream changes" back to your branch.
+
+------------
+$ git checkout mybranch
+$ git merge "Merge upstream changes." HEAD master
+------------
+
+This outputs something like this (the actual commit object names
+would be different)
+
+----------------
+Updating from ae3a2da... to a80b4aa....
+Fast forward
+ example |    1 +
+ hello   |    1 +
+ 2 files changed, 2 insertions(+), 0 deletions(-)
+----------------
+
+Because your branch did not contain anything more than what are
+already merged into the `master` branch, the resolve operation did
+not actually do a merge. Instead, it just updated the top of
+the tree of your branch to that of the `master` branch. This is
+often called 'fast forward' merge.
+
+You can run `gitk \--all` again to see how the commit ancestry
+looks like, or run `show-branch`, which tells you this.
+
+------------------------------------------------
+$ git show-branch master mybranch
+! [master] Merge work in mybranch
+ * [mybranch] Merge work in mybranch
+--
+-- [master] Merge work in mybranch
+------------------------------------------------
+
+
+Merging external work
+---------------------
+
+It's usually much more common that you merge with somebody else than
+merging with your own branches, so it's worth pointing out that git
+makes that very easy too, and in fact, it's not that different from
+doing a `git merge`. In fact, a remote merge ends up being nothing
+more than "fetch the work from a remote repository into a temporary tag"
+followed by a `git merge`.
+
+Fetching from a remote repository is done by, unsurprisingly,
+`git fetch`:
+
+----------------
+$ git fetch <remote-repository>
+----------------
+
+One of the following transports can be used to name the
+repository to download from:
+
+Rsync::
+       `rsync://remote.machine/path/to/repo.git/`
++
+Rsync transport is usable for both uploading and downloading,
+but is completely unaware of what git does, and can produce
+unexpected results when you download from the public repository
+while the repository owner is uploading into it via `rsync`
+transport.  Most notably, it could update the files under
+`refs/` which holds the object name of the topmost commits
+before uploading the files in `objects/` -- the downloader would
+obtain head commit object name while that object itself is still
+not available in the repository.  For this reason, it is
+considered deprecated.
+
+SSH::
+       `remote.machine:/path/to/repo.git/` or
++
+`ssh://remote.machine/path/to/repo.git/`
++
+This transport can be used for both uploading and downloading,
+and requires you to have a log-in privilege over `ssh` to the
+remote machine.  It finds out the set of objects the other side
+lacks by exchanging the head commits both ends have and
+transfers (close to) minimum set of objects.  It is by far the
+most efficient way to exchange git objects between repositories.
+
+Local directory::
+       `/path/to/repo.git/`
++
+This transport is the same as SSH transport but uses `sh` to run
+both ends on the local machine instead of running other end on
+the remote machine via `ssh`.
+
+git Native::
+       `git://remote.machine/path/to/repo.git/`
++
+This transport was designed for anonymous downloading.  Like SSH
+transport, it finds out the set of objects the downstream side
+lacks and transfers (close to) minimum set of objects.
+
+HTTP(S)::
+       `http://remote.machine/path/to/repo.git/`
++
+Downloader from http and https URL
+first obtains the topmost commit object name from the remote site
+by looking at the specified refname under `repo.git/refs/` directory,
+and then tries to obtain the
+commit object by downloading from `repo.git/objects/xx/xxx\...`
+using the object name of that commit object.  Then it reads the
+commit object to find out its parent commits and the associate
+tree object; it repeats this process until it gets all the
+necessary objects.  Because of this behaviour, they are
+sometimes also called 'commit walkers'.
++
+The 'commit walkers' are sometimes also called 'dumb
+transports', because they do not require any git aware smart
+server like git Native transport does.  Any stock HTTP server
+that does not even support directory index would suffice.  But
+you must prepare your repository with `git-update-server-info`
+to help dumb transport downloaders.
++
+There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload`
+programs, which are 'commit walkers'; they outlived their
+usefulness when git Native and SSH transports were introduced,
+and not used by `git pull` or `git push` scripts.
+
+Once you fetch from the remote repository, you `resolve` that
+with your current branch.
+
+However -- it's such a common thing to `fetch` and then
+immediately `resolve`, that it's called `git pull`, and you can
+simply do
+
+----------------
+$ git pull <remote-repository>
+----------------
+
+and optionally give a branch-name for the remote end as a second
+argument.
+
+[NOTE]
+You could do without using any branches at all, by
+keeping as many local repositories as you would like to have
+branches, and merging between them with `git pull`, just like
+you merge between branches. The advantage of this approach is
+that it lets you keep set of files for each `branch` checked
+out and you may find it easier to switch back and forth if you
+juggle multiple lines of development simultaneously. Of
+course, you will pay the price of more disk usage to hold
+multiple working trees, but disk space is cheap these days.
+
+[NOTE]
+You could even pull from your own repository by
+giving '.' as <remote-repository> parameter to `git pull`.  This
+is useful when you want to merge a local branch (or more, if you
+are making an Octopus) into the current branch.
+
+It is likely that you will be pulling from the same remote
+repository from time to time. As a short hand, you can store
+the remote repository URL in a file under .git/remotes/
+directory, like this:
+
+------------------------------------------------
+$ mkdir -p .git/remotes/
+$ cat >.git/remotes/linus <<\EOF
+URL: http://www.kernel.org/pub/scm/git/git.git/
+EOF
+------------------------------------------------
+
+and use the filename to `git pull` instead of the full URL.
+The URL specified in such file can even be a prefix
+of a full URL, like this:
+
+------------------------------------------------
+$ cat >.git/remotes/jgarzik <<\EOF
+URL: http://www.kernel.org/pub/scm/linux/git/jgarzik/
+EOF
+------------------------------------------------
+
+
+Examples.
+
+. `git pull linus`
+. `git pull linus tag v0.99.1`
+. `git pull jgarzik/netdev-2.6.git/ e100`
+
+the above are equivalent to:
+
+. `git pull http://www.kernel.org/pub/scm/git/git.git/ HEAD`
+. `git pull http://www.kernel.org/pub/scm/git/git.git/ tag v0.99.1`
+. `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
+
+
+How does the merge work?
+------------------------
+
+We said this tutorial shows what plumbing does to help you cope
+with the porcelain that isn't flushing, but we so far did not
+talk about how the merge really works.  If you are following
+this tutorial the first time, I'd suggest to skip to "Publishing
+your work" section and come back here later.
+
+OK, still with me?  To give us an example to look at, let's go
+back to the earlier repository with "hello" and "example" file,
+and bring ourselves back to the pre-merge state:
+
+------------
+$ git show-branch --more=3 master mybranch
+! [master] Merge work in mybranch
+ * [mybranch] Merge work in mybranch
+--
+-- [master] Merge work in mybranch
++* [master^2] Some work.
++* [master^] Some fun.
+------------
+
+Remember, before running `git merge`, our `master` head was at
+"Some fun." commit, while our `mybranch` head was at "Some
+work." commit.
+
+------------
+$ git checkout mybranch
+$ git reset --hard master^2
+$ git checkout master
+$ git reset --hard master^
+------------
+
+After rewinding, the commit structure should look like this:
+
+------------
+$ git show-branch
+* [master] Some fun.
+ ! [mybranch] Some work.
+--
+ + [mybranch] Some work.
+*  [master] Some fun.
+*+ [mybranch^] New day.
+------------
+
+Now we are ready to experiment with the merge by hand.
+
+`git merge` command, when merging two branches, uses 3-way merge
+algorithm.  First, it finds the common ancestor between them.
+The command it uses is `git-merge-base`:
+
+------------
+$ mb=$(git-merge-base HEAD mybranch)
+------------
+
+The command writes the commit object name of the common ancestor
+to the standard output, so we captured its output to a variable,
+because we will be using it in the next step.  BTW, the common
+ancestor commit is the "New day." commit in this case.  You can
+tell it by:
+
+------------
+$ git-name-rev $mb
+my-first-tag
+------------
+
+After finding out a common ancestor commit, the second step is
+this:
+
+------------
+$ git-read-tree -m -u $mb HEAD mybranch
+------------
+
+This is the same `git-read-tree` command we have already seen,
+but it takes three trees, unlike previous examples.  This reads
+the contents of each tree into different 'stage' in the index
+file (the first tree goes to stage 1, the second stage 2,
+etc.).  After reading three trees into three stages, the paths
+that are the same in all three stages are 'collapsed' into stage
+0.  Also paths that are the same in two of three stages are
+collapsed into stage 0, taking the SHA1 from either stage 2 or
+stage 3, whichever is different from stage 1 (i.e. only one side
+changed from the common ancestor).
+
+After 'collapsing' operation, paths that are different in three
+trees are left in non-zero stages.  At this point, you can
+inspect the index file with this command:
+
+------------
+$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0      example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1      hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2      hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3      hello
+------------
+
+In our example of only two files, we did not have unchanged
+files so only 'example' resulted in collapsing, but in real-life
+large projects, only small number of files change in one commit,
+and this 'collapsing' tends to trivially merge most of the paths
+fairly quickly, leaving only a handful the real changes in non-zero
+stages.
+
+To look at only non-zero stages, use `\--unmerged` flag:
+
+------------
+$ git-ls-files --unmerged
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1      hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2      hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3      hello
+------------
+
+The next step of merging is to merge these three versions of the
+file, using 3-way merge.  This is done by giving
+`git-merge-one-file` command as one of the arguments to
+`git-merge-index` command:
+
+------------
+$ git-merge-index git-merge-one-file hello
+Auto-merging hello.
+merge: warning: conflicts during merge
+ERROR: Merge conflict in hello.
+fatal: merge program failed
+------------
+
+`git-merge-one-file` script is called with parameters to
+describe those three versions, and is responsible to leave the
+merge results in the working tree.
+It is a fairly straightforward shell script, and
+eventually calls `merge` program from RCS suite to perform a
+file-level 3-way merge.  In this case, `merge` detects
+conflicts, and the merge result with conflict marks is left in
+the working tree..  This can be seen if you run `ls-files
+--stage` again at this point:
+
+------------
+$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0      example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1      hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2      hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3      hello
+------------
+
+This is the state of the index file and the working file after
+`git merge` returns control back to you, leaving the conflicting
+merge for you to resolve.  Notice that the path `hello` is still
+unmerged, and what you see with `git diff` at this point is
+differences since stage 2 (i.e. your version).
+
+
+Publishing your work
+--------------------
+
+So we can use somebody else's work from a remote repository; but
+how can *you* prepare a repository to let other people pull from
+it?
+
+Your do your real work in your working tree that has your
+primary repository hanging under it as its `.git` subdirectory.
+You *could* make that repository accessible remotely and ask
+people to pull from it, but in practice that is not the way
+things are usually done. A recommended way is to have a public
+repository, make it reachable by other people, and when the
+changes you made in your primary working tree are in good shape,
+update the public repository from it. This is often called
+'pushing'.
+
+[NOTE]
+This public repository could further be mirrored, and that is
+how git repositories at `kernel.org` are managed.
+
+Publishing the changes from your local (private) repository to
+your remote (public) repository requires a write privilege on
+the remote machine. You need to have an SSH account there to
+run a single command, `git-receive-pack`.
+
+First, you need to create an empty repository on the remote
+machine that will house your public repository. This empty
+repository will be populated and be kept up-to-date by pushing
+into it later. Obviously, this repository creation needs to be
+done only once.
+
+[NOTE]
+`git push` uses a pair of programs,
+`git-send-pack` on your local machine, and `git-receive-pack`
+on the remote machine. The communication between the two over
+the network internally uses an SSH connection.
+
+Your private repository's git directory is usually `.git`, but
+your public repository is often named after the project name,
+i.e. `<project>.git`. Let's create such a public repository for
+project `my-git`. After logging into the remote machine, create
+an empty directory:
+
+------------
+$ mkdir my-git.git
+------------
+
+Then, make that directory into a git repository by running
+`git init-db`, but this time, since its name is not the usual
+`.git`, we do things slightly differently:
+
+------------
+$ GIT_DIR=my-git.git git-init-db
+------------
+
+Make sure this directory is available for others you want your
+changes to be pulled by via the transport of your choice. Also
+you need to make sure that you have the `git-receive-pack`
+program on the `$PATH`.
+
+[NOTE]
+Many installations of sshd do not invoke your shell as the login
+shell when you directly run programs; what this means is that if
+your login shell is `bash`, only `.bashrc` is read and not
+`.bash_profile`. As a workaround, make sure `.bashrc` sets up
+`$PATH` so that you can run `git-receive-pack` program.
+
+[NOTE]
+If you plan to publish this repository to be accessed over http,
+you should do `chmod +x my-git.git/hooks/post-update` at this
+point.  This makes sure that every time you push into this
+repository, `git-update-server-info` is run.
+
+Your "public repository" is now ready to accept your changes.
+Come back to the machine you have your private repository. From
+there, run this command:
+
+------------
+$ git push <public-host>:/path/to/my-git.git master
+------------
+
+This synchronizes your public repository to match the named
+branch head (i.e. `master` in this case) and objects reachable
+from them in your current repository.
+
+As a real example, this is how I update my public git
+repository. Kernel.org mirror network takes care of the
+propagation to other publicly visible machines:
+
+------------
+$ git push master.kernel.org:/pub/scm/git/git.git/ 
+------------
+
+
+Packing your repository
+-----------------------
+
+Earlier, we saw that one file under `.git/objects/??/` directory
+is stored for each git object you create. This representation
+is efficient to create atomically and safely, but
+not so convenient to transport over the network. Since git objects are
+immutable once they are created, there is a way to optimize the
+storage by "packing them together". The command
+
+------------
+$ git repack
+------------
+
+will do it for you. If you followed the tutorial examples, you
+would have accumulated about 17 objects in `.git/objects/??/`
+directories by now. `git repack` tells you how many objects it
+packed, and stores the packed file in `.git/objects/pack`
+directory.
+
+[NOTE]
+You will see two files, `pack-\*.pack` and `pack-\*.idx`,
+in `.git/objects/pack` directory. They are closely related to
+each other, and if you ever copy them by hand to a different
+repository for whatever reason, you should make sure you copy
+them together. The former holds all the data from the objects
+in the pack, and the latter holds the index for random
+access.
+
+If you are paranoid, running `git-verify-pack` command would
+detect if you have a corrupt pack, but do not worry too much.
+Our programs are always perfect ;-).
+
+Once you have packed objects, you do not need to leave the
+unpacked objects that are contained in the pack file anymore.
+
+------------
+$ git prune-packed
+------------
+
+would remove them for you.
+
+You can try running `find .git/objects -type f` before and after
+you run `git prune-packed` if you are curious.  Also `git
+count-objects` would tell you how many unpacked objects are in
+your repository and how much space they are consuming.
+
+[NOTE]
+`git pull` is slightly cumbersome for HTTP transport, as a
+packed repository may contain relatively few objects in a
+relatively large pack. If you expect many HTTP pulls from your
+public repository you might want to repack & prune often, or
+never.
+
+If you run `git repack` again at this point, it will say
+"Nothing to pack". Once you continue your development and
+accumulate the changes, running `git repack` again will create a
+new pack, that contains objects created since you packed your
+repository the last time. We recommend that you pack your project
+soon after the initial import (unless you are starting your
+project from scratch), and then run `git repack` every once in a
+while, depending on how active your project is.
+
+When a repository is synchronized via `git push` and `git pull`
+objects packed in the source repository are usually stored
+unpacked in the destination, unless rsync transport is used.
+While this allows you to use different packing strategies on
+both ends, it also means you may need to repack both
+repositories every once in a while.
+
+
+Working with Others
+-------------------
+
+Although git is a truly distributed system, it is often
+convenient to organize your project with an informal hierarchy
+of developers. Linux kernel development is run this way. There
+is a nice illustration (page 17, "Merges to Mainline") in Randy
+Dunlap's presentation (`http://tinyurl.com/a2jdg`).
+
+It should be stressed that this hierarchy is purely *informal*.
+There is nothing fundamental in git that enforces the "chain of
+patch flow" this hierarchy implies. You do not have to pull
+from only one remote repository.
+
+A recommended workflow for a "project lead" goes like this:
+
+1. Prepare your primary repository on your local machine. Your
+   work is done there.
+
+2. Prepare a public repository accessible to others.
++
+If other people are pulling from your repository over dumb
+transport protocols (HTTP), you need to keep this repository
+'dumb transport friendly'.  After `git init-db`,
+`$GIT_DIR/hooks/post-update` copied from the standard templates
+would contain a call to `git-update-server-info` but the
+`post-update` hook itself is disabled by default -- enable it
+with `chmod +x post-update`.  This makes sure `git-update-server-info`
+keeps the necessary files up-to-date.
+
+3. Push into the public repository from your primary
+   repository.
+
+4. `git repack` the public repository. This establishes a big
+   pack that contains the initial set of objects as the
+   baseline, and possibly `git prune` if the transport
+   used for pulling from your repository supports packed
+   repositories.
+
+5. Keep working in your primary repository. Your changes
+   include modifications of your own, patches you receive via
+   e-mails, and merges resulting from pulling the "public"
+   repositories of your "subsystem maintainers".
++
+You can repack this private repository whenever you feel like.
+
+6. Push your changes to the public repository, and announce it
+   to the public.
+
+7. Every once in a while, "git repack" the public repository.
+   Go back to step 5. and continue working.
+
+
+A recommended work cycle for a "subsystem maintainer" who works
+on that project and has an own "public repository" goes like this:
+
+1. Prepare your work repository, by `git clone` the public
+   repository of the "project lead". The URL used for the
+   initial cloning is stored in `.git/remotes/origin`.
+
+2. Prepare a public repository accessible to others, just like
+   the "project lead" person does.
+
+3. Copy over the packed files from "project lead" public
+   repository to your public repository, unless the "project
+   lead" repository lives on the same machine as yours.  In the
+   latter case, you can use `objects/info/alternates` file to
+   point at the repository you are borrowing from.
+
+4. Push into the public repository from your primary
+   repository. Run `git repack`, and possibly `git prune` if the
+   transport used for pulling from your repository supports
+   packed repositories.
+
+5. Keep working in your primary repository. Your changes
+   include modifications of your own, patches you receive via
+   e-mails, and merges resulting from pulling the "public"
+   repositories of your "project lead" and possibly your
+   "sub-subsystem maintainers".
++
+You can repack this private repository whenever you feel
+like.
+
+6. Push your changes to your public repository, and ask your
+   "project lead" and possibly your "sub-subsystem
+   maintainers" to pull from it.
+
+7. Every once in a while, `git repack` the public repository.
+   Go back to step 5. and continue working.
+
+
+A recommended work cycle for an "individual developer" who does
+not have a "public" repository is somewhat different. It goes
+like this:
+
+1. Prepare your work repository, by `git clone` the public
+   repository of the "project lead" (or a "subsystem
+   maintainer", if you work on a subsystem). The URL used for
+   the initial cloning is stored in `.git/remotes/origin`.
+
+2. Do your work in your repository on 'master' branch.
+
+3. Run `git fetch origin` from the public repository of your
+   upstream every once in a while. This does only the first
+   half of `git pull` but does not merge. The head of the
+   public repository is stored in `.git/refs/heads/origin`.
+
+4. Use `git cherry origin` to see which ones of your patches
+   were accepted, and/or use `git rebase origin` to port your
+   unmerged changes forward to the updated upstream.
+
+5. Use `git format-patch origin` to prepare patches for e-mail
+   submission to your upstream and send it out. Go back to
+   step 2. and continue.
+
+
+Working with Others, Shared Repository Style
+--------------------------------------------
+
+If you are coming from CVS background, the style of cooperation
+suggested in the previous section may be new to you. You do not
+have to worry. git supports "shared public repository" style of
+cooperation you are probably more familiar with as well.
+
+See link:cvs-migration.txt[git for CVS users] for the details.
+
+Bundling your work together
+---------------------------
+
+It is likely that you will be working on more than one thing at
+a time.  It is easy to manage those more-or-less independent tasks
+using branches with git.
+
+We have already seen how branches work previously,
+with "fun and work" example using two branches.  The idea is the
+same if there are more than two branches.  Let's say you started
+out from "master" head, and have some new code in the "master"
+branch, and two independent fixes in the "commit-fix" and
+"diff-fix" branches:
+
+------------
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+  * [master] Release candidate #1
+---
+ +  [diff-fix] Fix rename detection.
+ +  [diff-fix~1] Better common substring algorithm.
++   [commit-fix] Fix commit message normalization.
+  * [master] Release candidate #1
+++* [diff-fix~2] Pretty-print messages.
+------------
+
+Both fixes are tested well, and at this point, you want to merge
+in both of them.  You could merge in 'diff-fix' first and then
+'commit-fix' next, like this:
+
+------------
+$ git merge 'Merge fix in diff-fix' master diff-fix
+$ git merge 'Merge fix in commit-fix' master commit-fix
+------------
+
+Which would result in:
+
+------------
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+  * [master] Merge fix in commit-fix
+---
+  - [master] Merge fix in commit-fix
++ * [commit-fix] Fix commit message normalization.
+  - [master~1] Merge fix in diff-fix
+ +* [diff-fix] Fix rename detection.
+ +* [diff-fix~1] Better common substring algorithm.
+  * [master~2] Release candidate #1
+++* [master~3] Pretty-print messages.
+------------
+
+However, there is no particular reason to merge in one branch
+first and the other next, when what you have are a set of truly
+independent changes (if the order mattered, then they are not
+independent by definition).  You could instead merge those two
+branches into the current branch at once.  First let's undo what
+we just did and start over.  We would want to get the master
+branch before these two merges by resetting it to 'master~2':
+
+------------
+$ git reset --hard master~2
+------------
+
+You can make sure 'git show-branch' matches the state before
+those two 'git merge' you just did.  Then, instead of running
+two 'git merge' commands in a row, you would pull these two
+branch heads (this is known as 'making an Octopus'):
+
+------------
+$ git pull . commit-fix diff-fix
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+  * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
+---
+  - [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
++ * [commit-fix] Fix commit message normalization.
+ +* [diff-fix] Fix rename detection.
+ +* [diff-fix~1] Better common substring algorithm.
+  * [master~1] Release candidate #1
+++* [master~2] Pretty-print messages.
+------------
+
+Note that you should not do Octopus because you can.  An octopus
+is a valid thing to do and often makes it easier to view the
+commit history if you are pulling more than two independent
+changes at the same time.  However, if you have merge conflicts
+with any of the branches you are merging in and need to hand
+resolve, that is an indication that the development happened in
+those branches were not independent after all, and you should
+merge two at a time, documenting how you resolved the conflicts,
+and the reason why you preferred changes made in one side over
+the other.  Otherwise it would make the project history harder
+to follow, not easier.
+
+[ to be continued.. cvsimports ]
diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
new file mode 100644 (file)
index 0000000..fa94efd
--- /dev/null
@@ -0,0 +1,304 @@
+git for CVS users
+=================
+
+So you're a CVS user. That's ok, it's a treatable condition.  The job of
+this document is to put you on the road to recovery, by helping you
+convert an existing cvs repository to git, and by showing you how to use a
+git repository in a cvs-like fashion.
+
+Some basic familiarity with git is required.  This
+link:tutorial.html[tutorial introduction to git] should be sufficient.
+
+First, note some ways that git differs from CVS:
+
+  * Commits are atomic and project-wide, not per-file as in CVS.
+
+  * Offline work is supported: you can make multiple commits locally,
+    then submit them when you're ready.
+
+  * Branching is fast and easy.
+
+  * Every working tree contains a repository with a full copy of the
+    project history, and no repository is inherently more important than
+    any other.  However, you can emulate the CVS model by designating a
+    single shared repository which people can synchronize with; see below
+    for details.
+
+Importing a CVS archive
+-----------------------
+
+First, install version 2.1 or higher of cvsps from
+link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make
+sure it is in your path.  The magic command line is then
+
+-------------------------------------------
+$ git cvsimport -v -d <cvsroot> -C <destination> <module>
+-------------------------------------------
+
+This puts a git archive of the named CVS module in the directory
+<destination>, which will be created if necessary.  The -v option makes
+the conversion script very chatty.
+
+The import checks out from CVS every revision of every file.  Reportedly
+cvsimport can average some twenty revisions per second, so for a
+medium-sized project this should not take more than a couple of minutes.
+Larger projects or remote repositories may take longer.
+
+The main trunk is stored in the git branch named `origin`, and additional
+CVS branches are stored in git branches with the same names.  The most
+recent version of the main trunk is also left checked out on the `master`
+branch, so you can start adding your own changes right away.
+
+The import is incremental, so if you call it again next month it will
+fetch any CVS updates that have been made in the meantime.  For this to
+work, you must not modify the imported branches; instead, create new
+branches for your own changes, and merge in the imported branches as
+necessary.
+
+Development Models
+------------------
+
+CVS users are accustomed to giving a group of developers commit access to
+a common repository.  In the next section we'll explain how to do this
+with git.  However, the distributed nature of git allows other development
+models, and you may want to first consider whether one of them might be a
+better fit for your project.
+
+For example, you can choose a single person to maintain the project's
+primary public repository.  Other developers then clone this repository
+and each work in their own clone.  When they have a series of changes that
+they're happy with, they ask the maintainer to pull from the branch
+containing the changes.  The maintainer reviews their changes and pulls
+them into the primary repository, which other developers pull from as
+necessary to stay coordinated.  The Linux kernel and other projects use
+variants of this model.
+
+With a small group, developers may just pull changes from each other's
+repositories without the need for a central maintainer.
+
+Emulating the CVS Development Model
+-----------------------------------
+
+Start with an ordinary git working directory containing the project, and
+remove the checked-out files, keeping just the bare .git directory:
+
+------------------------------------------------
+$ mv project/.git /pub/repo.git
+$ rm -r project/
+------------------------------------------------
+
+Next, give every team member read/write access to this repository.  One
+easy way to do this is to give all the team members ssh access to the
+machine where the repository is hosted.  If you don't want to give them a
+full shell on the machine, there is a restricted shell which only allows
+users to do git pushes and pulls; see gitlink:git-shell[1].
+
+Put all the committers should in the same group, and make the repository
+writable by that group:
+
+------------------------------------------------
+$ chgrp -R $group repo.git
+$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s
+$ GIT_DIR=repo.git git repo-config core.sharedrepository true
+------------------------------------------------
+
+Make sure committers have a umask of at most 027, so that the directories
+they create are writable and searchable by other group members.
+
+Suppose this repository is now set up in /pub/repo.git on the host
+foo.com.  Then as an individual commiter you can clone the shared
+repository:
+
+------------------------------------------------
+$ git clone foo.com:/pub/repo.git/ my-project
+$ cd my-project
+------------------------------------------------
+
+and hack away.  The equivalent of `cvs update` is
+
+------------------------------------------------
+$ git pull origin
+------------------------------------------------
+
+which merges in any work that others might have done since the clone
+operation.
+
+[NOTE]
+================================
+The first `git clone` places the following in the
+`my-project/.git/remotes/origin` file, and that's why the previous step
+and the next step both work.
+------------
+URL: foo.com:/pub/project.git/ my-project
+Pull: master:origin
+------------
+================================
+
+You can update the shared repository with your changes using:
+
+------------------------------------------------
+$ git push origin master
+------------------------------------------------
+
+If someone else has updated the repository more recently, `git push`, like
+`cvs commit`, will complain, in which case you must pull any changes
+before attempting the push again.
+
+In the `git push` command above we specify the name of the remote branch
+to update (`master`).  If we leave that out, `git push` tries to update
+any branches in the remote repository that have the same name as a branch
+in the local repository.  So the last `push` can be done with either of:
+
+------------
+$ git push origin
+$ git push repo.shared.xz:/pub/scm/project.git/
+------------
+
+as long as the shared repository does not have any branches
+other than `master`.
+
+[NOTE]
+============
+Because of this behaviour, if the shared repository and the developer's
+repository both have branches named `origin`, then a push like the above
+attempts to update the `origin` branch in the shared repository from the
+developer's `origin` branch.  The results may be unexpected, so it's
+usually best to remove any branch named `origin` from the shared
+repository.
+============
+
+Advanced Shared Repository Management
+-------------------------------------
+
+Git allows you to specify scripts called "hooks" to be run at certain
+points.  You can use these, for example, to send all commits to the shared
+repository to a mailing list.  See link:hooks.txt[Hooks used by git].
+
+You can enforce finer grained permissions using update hooks.  See
+link:howto/update-hook-example.txt[Controlling access to branches using
+update hooks].
+
+CVS annotate
+------------
+
+So, something has gone wrong, and you don't know whom to blame, and
+you're an ex-CVS user and used to do "cvs annotate" to see who caused
+the breakage. You're looking for the "git annotate", and it's just
+claiming not to find such a script. You're annoyed.
+
+Yes, that's right.  Core git doesn't do "annotate", although it's
+technically possible, and there are at least two specialized scripts out
+there that can be used to get equivalent information (see the git
+mailing list archives for details). 
+
+git has a couple of alternatives, though, that you may find sufficient
+or even superior depending on your use.  One is called "git-whatchanged"
+(for obvious reasons) and the other one is called "pickaxe" ("a tool for
+the software archaeologist"). 
+
+The "git-whatchanged" script is a truly trivial script that can give you
+a good overview of what has changed in a file or a directory (or an
+arbitrary list of files or directories).  The "pickaxe" support is an
+additional layer that can be used to further specify exactly what you're
+looking for, if you already know the specific area that changed.
+
+Let's step back a bit and think about the reason why you would
+want to do "cvs annotate a-file.c" to begin with.
+
+You would use "cvs annotate" on a file when you have trouble
+with a function (or even a single "if" statement in a function)
+that happens to be defined in the file, which does not do what
+you want it to do.  And you would want to find out why it was
+written that way, because you are about to modify it to suit
+your needs, and at the same time you do not want to break its
+current callers.  For that, you are trying to find out why the
+original author did things that way in the original context.
+
+Many times, it may be enough to see the commit log messages of
+commits that touch the file in question, possibly along with the
+patches themselves, like this:
+
+       $ git-whatchanged -p a-file.c
+
+This will show log messages and patches for each commit that
+touches a-file.
+
+This, however, may not be very useful when this file has many
+modifications that are not related to the piece of code you are
+interested in.  You would see many log messages and patches that
+do not have anything to do with the piece of code you are
+interested in.  As an example, assuming that you have this piece
+of code that you are interested in in the HEAD version:
+
+       if (frotz) {
+               nitfol();
+       }
+
+you would use git-rev-list and git-diff-tree like this:
+
+       $ git-rev-list HEAD |
+         git-diff-tree --stdin -v -p -S'if (frotz) {
+               nitfol();
+       }'
+
+We have already talked about the "\--stdin" form of git-diff-tree
+command that reads the list of commits and compares each commit
+with its parents (otherwise you should go back and read the tutorial).
+The git-whatchanged command internally runs
+the equivalent of the above command, and can be used like this:
+
+       $ git-whatchanged -p -S'if (frotz) {
+               nitfol();
+       }'
+
+When the -S option is used, git-diff-tree command outputs
+differences between two commits only if one tree has the
+specified string in a file and the corresponding file in the
+other tree does not.  The above example looks for a commit that
+has the "if" statement in it in a file, but its parent commit
+does not have it in the same shape in the corresponding file (or
+the other way around, where the parent has it and the commit
+does not), and the differences between them are shown, along
+with the commit message (thanks to the -v flag).  It does not
+show anything for commits that do not touch this "if" statement.
+
+Also, in the original context, the same statement might have
+appeared at first in a different file and later the file was
+renamed to "a-file.c".  CVS annotate would not help you to go
+back across such a rename, but git would still help you in such
+a situation.  For that, you can give the -C flag to
+git-diff-tree, like this:
+
+       $ git-whatchanged -p -C -S'if (frotz) {
+               nitfol();
+       }'
+
+When the -C flag is used, file renames and copies are followed.
+So if the "if" statement in question happens to be in "a-file.c"
+in the current HEAD commit, even if the file was originally
+called "o-file.c" and then renamed in an earlier commit, or if
+the file was created by copying an existing "o-file.c" in an
+earlier commit, you will not lose track.  If the "if" statement
+did not change across such a rename or copy, then the commit that
+does rename or copy would not show in the output, and if the
+"if" statement was modified while the file was still called
+"o-file.c", it would find the commit that changed the statement
+when it was in "o-file.c".
+
+NOTE: The current version of "git-diff-tree -C" is not eager
+  enough to find copies, and it will miss the fact that a-file.c
+  was created by copying o-file.c unless o-file.c was somehow
+  changed in the same commit.
+
+You can use the --pickaxe-all flag in addition to the -S flag.
+This causes the differences from all the files contained in
+those two commits, not just the differences between the files
+that contain this changed "if" statement:
+
+       $ git-whatchanged -p -C -S'if (frotz) {
+               nitfol();
+       }' --pickaxe-all
+
+NOTE: This option is called "--pickaxe-all" because -S
+  option is internally called "pickaxe", a tool for software
+  archaeologists.
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
new file mode 100644 (file)
index 0000000..617d8f5
--- /dev/null
@@ -0,0 +1,197 @@
+The output format from "git-diff-index", "git-diff-tree" and
+"git-diff-files" are very similar.
+
+These commands all compare two sets of things; what is 
+compared differs:
+
+git-diff-index <tree-ish>::
+        compares the <tree-ish> and the files on the filesystem.
+
+git-diff-index --cached <tree-ish>::
+        compares the <tree-ish> and the index.
+
+git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]::
+        compares the trees named by the two arguments.
+
+git-diff-files [<pattern>...]::
+        compares the index and the files on the filesystem.
+
+
+An output line is formatted this way:
+
+------------------------------------------------
+in-place edit  :100644 100644 bcd1234... 0123456... M file0
+copy-edit      :100644 100644 abcd123... 1234567... C68 file1 file2
+rename-edit    :100644 100644 abcd123... 1234567... R86 file1 file3
+create         :000000 100644 0000000... 1234567... A file4
+delete         :100644 000000 1234567... 0000000... D file5
+unmerged       :000000 000000 0000000... 0000000... U file6
+------------------------------------------------
+
+That is, from the left to the right:
+
+. a colon.
+. mode for "src"; 000000 if creation or unmerged.
+. a space.
+. mode for "dst"; 000000 if deletion or unmerged.
+. a space.
+. sha1 for "src"; 0\{40\} if creation or unmerged.
+. a space.
+. sha1 for "dst"; 0\{40\} if creation, unmerged or "look at work tree".
+. a space.
+. status, followed by optional "score" number.
+. a tab or a NUL when '-z' option is used.
+. path for "src"
+. a tab or a NUL when '-z' option is used; only exists for C or R.
+. path for "dst"; only exists for C or R.
+. an LF or a NUL when '-z' option is used, to terminate the record.
+
+<sha1> is shown as all 0's if a file is new on the filesystem
+and it is out of sync with the index.
+
+Example:
+
+------------------------------------------------
+:100644 100644 5be4a4...... 000000...... M file.c
+------------------------------------------------
+
+When `-z` option is not used, TAB, LF, and backslash characters
+in pathnames are represented as `\t`, `\n`, and `\\`,
+respectively.
+
+
+Generating patches with -p
+--------------------------
+
+When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
+with a '-p' option, they do not produce the output described above;
+instead they produce a patch file.
+
+The patch generation can be customized at two levels.
+
+1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set,
+   these commands internally invoke "diff" like this:
+
+      diff -L a/<path> -L b/<path> -pu <old> <new>
++
+For added files, `/dev/null` is used for <old>.  For removed
+files, `/dev/null` is used for <new>
++
+The "diff" formatting options can be customized via the
+environment variable 'GIT_DIFF_OPTS'.  For example, if you
+prefer context diff:
+
+      GIT_DIFF_OPTS=-c git-diff-index -p HEAD
+
+
+2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
+   program named by it is called, instead of the diff invocation
+   described above.
++
+For a path that is added, removed, or modified,
+'GIT_EXTERNAL_DIFF' is called with 7 parameters:
+
+     path old-file old-hex old-mode new-file new-hex new-mode
++
+where:
+
+     <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
+                     contents of <old|new>,
+     <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
+     <old|new>-mode:: are the octal representation of the file modes.
+
++ 
+The file parameters can point at the user's working file
+(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
+when a new file is added), or a temporary file (e.g. `old-file` in the
+index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
+temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
+
+For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
+parameter, <path>.
+
+
+git specific extension to diff format
+-------------------------------------
+
+What -p option produces is slightly different from the
+traditional diff format.
+
+1.   It is preceded with a "git diff" header, that looks like
+     this:
+
+     diff --git a/file1 b/file2
++
+The `a/` and `b/` filenames are the same unless rename/copy is
+involved.  Especially, even for a creation or a deletion,
+`/dev/null` is _not_ used in place of `a/` or `b/` filenames.
++
+When rename/copy is involved, `file1` and `file2` show the
+name of the source file of the rename/copy and the name of
+the file that rename/copy produces, respectively.
+
+2.   It is followed by one or more extended header lines:
+
+       old mode <mode>
+       new mode <mode>
+       deleted file mode <mode>
+       new file mode <mode>
+       copy from <path>
+       copy to <path>
+       rename from <path>
+       rename to <path>
+       similarity index <number>
+       dissimilarity index <number>
+       index <hash>..<hash> <mode>
+
+3.  TAB, LF, and backslash characters in pathnames are
+    represented as `\t`, `\n`, and `\\`, respectively.
+
+
+combined diff format
+--------------------
+
+git-diff-tree and git-diff-files can take '-c' or '--cc' option
+to produce 'combined diff', which looks like this:
+
+------------
+diff --combined describe.c
+@@@ +98,7 @@@
+   return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+  }
+
+- static void describe(char *arg)
+ -static void describe(struct commit *cmit, int last_one)
+++static void describe(char *arg, int last_one)
+  {
+ +     unsigned char sha1[20];
+ +     struct commit *cmit;
+------------
+
+Unlike the traditional 'unified' diff format, which shows two
+files A and B with a single column that has `-` (minus --
+appears in A but removed in B), `+` (plus -- missing in A but
+added to B), or ` ` (space -- unchanged) prefix, this format
+compares two or more files file1, file2,... with one file X, and
+shows how X differs from each of fileN.  One column for each of
+fileN is prepended to the output line to note how X's line is
+different from it.
+
+A `-` character in the column N means that the line appears in
+fileN but it does not appear in the last file.  A `+` character
+in the column N means that the line appears in the last file,
+and fileN does not have that line.
+
+In the above example output, the function signature was changed
+from both files (hence two `-` removals from both file1 and
+file2, plus `++` to mean one line that was added does not appear
+in either file1 nor file2).  Also two other lines are the same
+from file1 but do not appear in file2 (hence prefixed with ` +`).
+
+When shown by `git diff-tree -c`, it compares the parents of a
+merge commit with the merge result (i.e. file1..fileN are the
+parents).  When shown by `git diff-files -c`, it compares the
+two unresolved merge parents with the working tree file
+(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka
+"their version").
+
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
new file mode 100644 (file)
index 0000000..5c85167
--- /dev/null
@@ -0,0 +1,70 @@
+-p::
+       Generate patch (see section on generating patches)
+
+-u::
+       Synonym for "-p".
+
+-z::
+       \0 line termination on output
+
+--name-only::
+       Show only names of changed files.
+
+--name-status::
+       Show only names and status of changed files.
+
+--full-index::
+       Instead of the first handful characters, show full
+       object name of pre- and post-image blob on the "index"
+       line when generating a patch format output.     
+
+--abbrev[=<n>]::
+       Instead of showing the full 40-byte hexadecimal object
+       name in diff-raw format output and diff-tree header
+       lines, show only handful hexdigits prefix.  This is
+       independent of --full-index option above, which controls
+       the diff-patch output format.  Non default number of
+       digits can be specified with --abbrev=<n>.
+
+-B::
+       Break complete rewrite changes into pairs of delete and create.
+
+-M::
+       Detect renames.
+
+-C::
+       Detect copies as well as renames.
+
+--find-copies-harder::
+       For performance reasons, by default, -C option finds copies only 
+       if the original file of the copy was modified in the same 
+       changeset.  This flag makes the command
+       inspect unmodified files as candidates for the source of
+       copy.  This is a very expensive operation for large
+       projects, so use it with caution.
+
+-l<num>::
+       -M and -C options require O(n^2) processing time where n
+       is the number of potential rename/copy targets.  This
+       option prevents rename/copy detection from running if
+       the number of rename/copy targets exceeds the specified
+       number.
+
+-S<string>::
+       Look for differences that contain the change in <string>.
+
+--pickaxe-all::
+       When -S finds a change, show all the changes in that
+       changeset, not just the files that contain the change
+       in <string>.
+
+-O<orderfile>::
+       Output the patch in the order specified in the
+       <orderfile>, which has one shell glob pattern per line.
+
+-R::
+       Swap two inputs; that is, show differences from index or
+       on-disk file to tree contents.
+
+For more detailed explanation on these common options, see also
+link:diffcore.html[diffcore documentation].
diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt
new file mode 100644 (file)
index 0000000..cb4e562
--- /dev/null
@@ -0,0 +1,275 @@
+Tweaking diff output
+====================
+June 2005
+
+
+Introduction
+------------
+
+The diff commands git-diff-index, git-diff-files, git-diff-tree, and
+git-diff-stages can be told to manipulate differences they find in
+unconventional ways before showing diff(1) output.  The manipulation
+is collectively called "diffcore transformation".  This short note
+describes what they are and how to use them to produce diff outputs
+that are easier to understand than the conventional kind.
+
+
+The chain of operation
+----------------------
+
+The git-diff-* family works by first comparing two sets of
+files:
+
+ - git-diff-index compares contents of a "tree" object and the
+   working directory (when '\--cached' flag is not used) or a
+   "tree" object and the index file (when '\--cached' flag is
+   used);
+
+ - git-diff-files compares contents of the index file and the
+   working directory;
+
+ - git-diff-tree compares contents of two "tree" objects;
+
+ - git-diff-stages compares contents of blobs at two stages in an
+   unmerged index file.
+
+In all of these cases, the commands themselves compare
+corresponding paths in the two sets of files.  The result of
+comparison is passed from these commands to what is internally
+called "diffcore", in a format similar to what is output when
+the -p option is not used.  E.g.
+
+------------------------------------------------
+in-place edit  :100644 100644 bcd1234... 0123456... M file0
+create         :000000 100644 0000000... 1234567... A file4
+delete         :100644 000000 1234567... 0000000... D file5
+unmerged       :000000 000000 0000000... 0000000... U file6
+------------------------------------------------
+
+The diffcore mechanism is fed a list of such comparison results
+(each of which is called "filepair", although at this point each
+of them talks about a single file), and transforms such a list
+into another list.  There are currently 6 such transformations:
+
+- diffcore-pathspec
+- diffcore-break
+- diffcore-rename
+- diffcore-merge-broken
+- diffcore-pickaxe
+- diffcore-order
+
+These are applied in sequence.  The set of filepairs git-diff-\*
+commands find are used as the input to diffcore-pathspec, and
+the output from diffcore-pathspec is used as the input to the
+next transformation.  The final result is then passed to the
+output routine and generates either diff-raw format (see Output
+format sections of the manual for git-diff-\* commands) or
+diff-patch format.
+
+
+diffcore-pathspec: For Ignoring Files Outside Our Consideration
+---------------------------------------------------------------
+
+The first transformation in the chain is diffcore-pathspec, and
+is controlled by giving the pathname parameters to the
+git-diff-* commands on the command line.  The pathspec is used
+to limit the world diff operates in.  It removes the filepairs
+outside the specified set of pathnames.  E.g. If the input set 
+of filepairs included:
+
+------------------------------------------------
+:100644 100644 bcd1234... 0123456... M junkfile
+------------------------------------------------
+
+but the command invocation was "git-diff-files myfile", then the
+junkfile entry would be removed from the list because only "myfile"
+is under consideration.
+
+Implementation note.  For performance reasons, git-diff-tree
+uses the pathname parameters on the command line to cull set of
+filepairs it feeds the diffcore mechanism itself, and does not
+use diffcore-pathspec, but the end result is the same.
+
+
+diffcore-break: For Splitting Up "Complete Rewrites"
+----------------------------------------------------
+
+The second transformation in the chain is diffcore-break, and is
+controlled by the -B option to the git-diff-* commands.  This is
+used to detect a filepair that represents "complete rewrite" and
+break such filepair into two filepairs that represent delete and
+create.  E.g.  If the input contained this filepair:
+
+------------------------------------------------
+:100644 100644 bcd1234... 0123456... M file0
+------------------------------------------------
+
+and if it detects that the file "file0" is completely rewritten,
+it changes it to:
+
+------------------------------------------------
+:100644 000000 bcd1234... 0000000... D file0
+:000000 100644 0000000... 0123456... A file0
+------------------------------------------------
+
+For the purpose of breaking a filepair, diffcore-break examines
+the extent of changes between the contents of the files before
+and after modification (i.e. the contents that have "bcd1234..."
+and "0123456..." as their SHA1 content ID, in the above
+example).  The amount of deletion of original contents and
+insertion of new material are added together, and if it exceeds
+the "break score", the filepair is broken into two.  The break
+score defaults to 50% of the size of the smaller of the original
+and the result (i.e. if the edit shrinks the file, the size of
+the result is used; if the edit lengthens the file, the size of
+the original is used), and can be customized by giving a number
+after "-B" option (e.g. "-B75" to tell it to use 75%).
+
+
+diffcore-rename: For Detection Renames and Copies
+-------------------------------------------------
+
+This transformation is used to detect renames and copies, and is
+controlled by the -M option (to detect renames) and the -C option
+(to detect copies as well) to the git-diff-* commands.  If the
+input contained these filepairs:
+
+------------------------------------------------
+:100644 000000 0123456... 0000000... D fileX
+:000000 100644 0000000... 0123456... A file0
+------------------------------------------------
+
+and the contents of the deleted file fileX is similar enough to
+the contents of the created file file0, then rename detection
+merges these filepairs and creates:
+
+------------------------------------------------
+:100644 100644 0123456... 0123456... R100 fileX file0
+------------------------------------------------
+
+When the "-C" option is used, the original contents of modified files,
+and deleted files (and also unmodified files, if the
+"\--find-copies-harder" option is used) are considered as candidates
+of the source files in rename/copy operation.  If the input were like
+these filepairs, that talk about a modified file fileY and a newly
+created file file0:
+
+------------------------------------------------
+:100644 100644 0123456... 1234567... M fileY
+:000000 100644 0000000... bcd3456... A file0
+------------------------------------------------
+
+the original contents of fileY and the resulting contents of
+file0 are compared, and if they are similar enough, they are
+changed to:
+
+------------------------------------------------
+:100644 100644 0123456... 1234567... M fileY
+:100644 100644 0123456... bcd3456... C100 fileY file0
+------------------------------------------------
+
+In both rename and copy detection, the same "extent of changes"
+algorithm used in diffcore-break is used to determine if two
+files are "similar enough", and can be customized to use
+a similarity score different from the default of 50% by giving a
+number after the "-M" or "-C" option (e.g. "-M8" to tell it to use
+8/10 = 80%).
+
+Note.  When the "-C" option is used with `\--find-copies-harder`
+option, git-diff-\* commands feed unmodified filepairs to
+diffcore mechanism as well as modified ones.  This lets the copy
+detector consider unmodified files as copy source candidates at
+the expense of making it slower.  Without `\--find-copies-harder`,
+git-diff-\* commands can detect copies only if the file that was
+copied happened to have been modified in the same changeset.
+
+
+diffcore-merge-broken: For Putting "Complete Rewrites" Back Together
+--------------------------------------------------------------------
+
+This transformation is used to merge filepairs broken by
+diffcore-break, and not transformed into rename/copy by
+diffcore-rename, back into a single modification.  This always
+runs when diffcore-break is used.
+
+For the purpose of merging broken filepairs back, it uses a
+different "extent of changes" computation from the ones used by
+diffcore-break and diffcore-rename.  It counts only the deletion
+from the original, and does not count insertion.  If you removed
+only 10 lines from a 100-line document, even if you added 910
+new lines to make a new 1000-line document, you did not do a
+complete rewrite.  diffcore-break breaks such a case in order to
+help diffcore-rename to consider such filepairs as candidate of
+rename/copy detection, but if filepairs broken that way were not
+matched with other filepairs to create rename/copy, then this
+transformation merges them back into the original
+"modification".
+
+The "extent of changes" parameter can be tweaked from the
+default 80% (that is, unless more than 80% of the original
+material is deleted, the broken pairs are merged back into a
+single modification) by giving a second number to -B option,
+like these:
+
+* -B50/60 (give 50% "break score" to diffcore-break, use 60%
+  for diffcore-merge-broken).
+
+* -B/60 (the same as above, since diffcore-break defaults to 50%).
+
+Note that earlier implementation left a broken pair as a separate
+creation and deletion patches.  This was an unnecessary hack and
+the latest implementation always merges all the broken pairs
+back into modifications, but the resulting patch output is
+formatted differently for easier review in case of such
+a complete rewrite by showing the entire contents of old version
+prefixed with '-', followed by the entire contents of new
+version prefixed with '+'.
+
+
+diffcore-pickaxe: For Detecting Addition/Deletion of Specified String
+---------------------------------------------------------------------
+
+This transformation is used to find filepairs that represent
+changes that touch a specified string, and is controlled by the
+-S option and the `\--pickaxe-all` option to the git-diff-*
+commands.
+
+When diffcore-pickaxe is in use, it checks if there are
+filepairs whose "original" side has the specified string and
+whose "result" side does not.  Such a filepair represents "the
+string appeared in this changeset".  It also checks for the
+opposite case that loses the specified string.
+
+When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves
+only such filepairs that touch the specified string in its
+output.  When `\--pickaxe-all` is used, diffcore-pickaxe leaves all
+filepairs intact if there is such a filepair, or makes the
+output empty otherwise.  The latter behaviour is designed to
+make reviewing of the changes in the context of the whole
+changeset easier.
+
+
+diffcore-order: For Sorting the Output Based on Filenames
+---------------------------------------------------------
+
+This is used to reorder the filepairs according to the user's
+(or project's) taste, and is controlled by the -O option to the
+git-diff-* commands.
+
+This takes a text file each of whose lines is a shell glob
+pattern.  Filepairs that match a glob pattern on an earlier line
+in the file are output before ones that match a later line, and
+filepairs that do not match any glob pattern are output last.
+
+As an example, a typical orderfile for the core git probably
+would look like this:
+
+------------------------------------------------
+README
+Makefile
+Documentation
+*.h
+*.c
+t
+------------------------------------------------
+
diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
new file mode 100644 (file)
index 0000000..3ab9b91
--- /dev/null
@@ -0,0 +1,441 @@
+Everyday GIT With 20 Commands Or So
+===================================
+
+GIT suite has over 100 commands, and the manual page for each of
+them discusses what the command does and how it is used in
+detail, but until you know what command should be used in order
+to achieve what you want to do, you cannot tell which manual
+page to look at, and if you know that already you do not need
+the manual.
+
+Does that mean you need to know all of them before you can use
+git?  Not at all.  Depending on the role you play, the set of
+commands you need to know is slightly different, but in any case
+what you need to learn is far smaller than the full set of
+commands to carry out your day-to-day work.  This document is to
+serve as a cheat-sheet and a set of pointers for people playing
+various roles.
+
+<<Basic Repository>> commands are needed by people who has a
+repository --- that is everybody, because every working tree of
+git is a repository.
+
+In addition, <<Individual Developer (Standalone)>> commands are
+essential for anybody who makes a commit, even for somebody who
+works alone.
+
+If you work with other people, you will need commands listed in
+<<Individual Developer (Participant)>> section as well.
+
+People who play <<Integrator>> role need to learn some more
+commands in addition to the above.
+
+<<Repository Administration>> commands are for system
+administrators who are responsible to care and feed git
+repositories to support developers.
+
+
+Basic Repository[[Basic Repository]]
+------------------------------------
+
+Everybody uses these commands to feed and care git repositories.
+
+  * gitlink:git-init-db[1] or gitlink:git-clone[1] to create a
+    new repository.
+
+  * gitlink:git-fsck-objects[1] to validate the repository.
+
+  * gitlink:git-prune[1] to garbage collect crufts in the
+    repository.
+
+  * gitlink:git-repack[1] to pack loose objects for efficiency.
+
+Examples
+~~~~~~~~
+
+Check health and remove cruft.::
++
+------------
+$ git fsck-objects <1>
+$ git prune
+$ git count-objects <2>
+$ git repack <3>
+$ git prune <4>
+
+<1> running without "--full" is usually cheap and assures the
+repository health reasonably well.
+<2> check how many loose objects there are and how much
+diskspace is wasted by not repacking.
+<3> without "-a" repacks incrementally.  repacking every 4-5MB
+of loose objects accumulation may be a good rule of thumb.
+<4> after repack, prune removes the duplicate loose objects.
+------------
+
+Repack a small project into single pack.::
++
+------------
+$ git repack -a -d <1>
+$ git prune
+
+<1> pack all the objects reachable from the refs into one pack
+and remove unneeded other packs
+------------
+
+
+Individual Developer (Standalone)[[Individual Developer (Standalone)]]
+----------------------------------------------------------------------
+
+A standalone individual developer does not exchange patches with
+other poeple, and works alone in a single repository, using the
+following commands.
+
+  * gitlink:git-show-branch[1] to see where you are.
+
+  * gitlink:git-log[1] to see what happened.
+
+  * gitlink:git-whatchanged[1] to find out where things have
+    come from.
+
+  * gitlink:git-checkout[1] and gitlink:git-branch[1] to switch
+    branches.
+
+  * gitlink:git-add[1] and gitlink:git-update-index[1] to manage
+    the index file.
+
+  * gitlink:git-diff[1] and gitlink:git-status[1] to see what
+    you are in the middle of doing.
+
+  * gitlink:git-commit[1] to advance the current branch.
+
+  * gitlink:git-reset[1] and gitlink:git-checkout[1] (with
+    pathname parameters) to undo changes.
+
+  * gitlink:git-pull[1] with "." as the remote to merge between
+    local branches.
+
+  * gitlink:git-rebase[1] to maintain topic branches.
+
+  * gitlink:git-tag[1] to mark known point.
+
+Examples
+~~~~~~~~
+
+Extract a tarball and create a working tree and a new repository to keep track of it.::
++
+------------
+$ tar zxf frotz.tar.gz
+$ cd frotz
+$ git-init-db
+$ git add . <1>
+$ git commit -m 'import of frotz source tree.'
+$ git tag v2.43 <2>
+
+<1> add everything under the current directory.
+<2> make a lightweight, unannotated tag.
+------------
+
+Create a topic branch and develop.::
++
+------------
+$ git checkout -b alsa-audio <1>
+$ edit/compile/test
+$ git checkout -- curses/ux_audio_oss.c <2>
+$ git add curses/ux_audio_alsa.c <3>
+$ edit/compile/test
+$ git diff <4>
+$ git commit -a -s <5>
+$ edit/compile/test
+$ git reset --soft HEAD^ <6>
+$ edit/compile/test
+$ git diff ORIG_HEAD <7>
+$ git commit -a -c ORIG_HEAD <8>
+$ git checkout master <9>
+$ git pull . alsa-audio <10>
+$ git log --since='3 days ago' <11>
+$ git log v2.43.. curses/ <12>
+
+<1> create a new topic branch.
+<2> revert your botched changes in "curses/ux_audio_oss.c".
+<3> you need to tell git if you added a new file; removal and
+modification will be caught if you do "commit -a" later.
+<4> to see what changes you are committing.
+<5> commit everything as you have tested, with your sign-off.
+<6> take the last commit back, keeping what is in the working tree.
+<7> look at the changes since the premature commit we took back.
+<8> redo the commit undone in the previous step, using the message
+you originally wrote.
+<9> switch to the master branch.
+<10> merge a topic branch into your master branch
+<11> review commit logs; other forms to limit output can be
+combined and include --max-count=10 (show 10 commits), --until='2005-12-10'.
+<12> view only the changes that touch what's in curses/
+directory, since v2.43 tag.
+------------
+
+
+Individual Developer (Participant)[[Individual Developer (Participant)]]
+------------------------------------------------------------------------
+
+A developer working as a participant in a group project needs to
+learn how to communicate with others, and uses these commands in
+addition to the ones needed by a standalone developer.
+
+  * gitlink:git-clone[1] from the upstream to prime your local
+    repository.
+
+  * gitlink:git-pull[1] and gitlink:git-fetch[1] from "origin"
+    to keep up-to-date with the upstream.
+
+  * gitlink:git-push[1] to shared repository, if you adopt CVS
+    style shared repository workflow.
+
+  * gitlink:git-format-patch[1] to prepare e-mail submission, if
+    you adopt Linux kernel-style public forum workflow.
+
+Examples
+~~~~~~~~
+
+Clone the upstream and work on it.  Feed changes to upstream.::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
+$ cd my2.6
+$ edit/compile/test; git commit -a -s <1>
+$ git format-patch origin <2>
+$ git pull <3>
+$ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
+$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
+$ git reset --hard ORIG_HEAD <6>
+$ git prune <7>
+$ git fetch --tags <8>
+
+<1> repeat as needed.
+<2> extract patches from your branch for e-mail submission.
+<3> "pull" fetches from "origin" by default and merges into the
+current branch.
+<4> immediately after pulling, look at the changes done upstream
+since last time we checked, only in the
+area we are interested in.
+<5> fetch from a specific branch from a specific repository and merge.
+<6> revert the pull.
+<7> garbage collect leftover objects from reverted pull.
+<8> from time to time, obtain official tags from the "origin"
+and store them under .git/refs/tags/.
+------------
+
+
+Push into another repository.::
++
+------------
+satellite$ git clone mothership:frotz/.git frotz <1>
+satellite$ cd frotz
+satellite$ cat .git/remotes/origin <2>
+URL: mothership:frotz/.git
+Pull: master:origin
+satellite$ echo 'Push: master:satellite' >>.git/remotes/origin <3>
+satellite$ edit/compile/test/commit
+satellite$ git push origin <4>
+
+mothership$ cd frotz
+mothership$ git checkout master
+mothership$ git pull . satellite <5>
+
+<1> mothership machine has a frotz repository under your home
+directory; clone from it to start a repository on the satellite
+machine.
+<2> clone creates this file by default.  It arranges "git pull"
+to fetch and store the master branch head of mothership machine
+to local "origin" branch.
+<3> arrange "git push" to push local "master" branch to
+"satellite" branch of the mothership machine.
+<4> push will stash our work away on "satellite" branch on the
+mothership machine.  You could use this as a back-up method.
+<5> on mothership machine, merge the work done on the satellite
+machine into the master branch.
+------------
+
+Branch off of a specific tag.::
++
+------------
+$ git checkout -b private2.6.14 v2.6.14 <1>
+$ edit/compile/test; git commit -a
+$ git checkout master
+$ git format-patch -k -m --stdout v2.6.14..private2.6.14 |
+  git am -3 -k <2>
+
+<1> create a private branch based on a well known (but somewhat behind)
+tag.
+<2> forward port all changes in private2.6.14 branch to master branch
+without a formal "merging".
+------------
+
+
+Integrator[[Integrator]]
+------------------------
+
+A fairly central person acting as the integrator in a group
+project receives changes made by others, reviews and integrates
+them and publishes the result for others to use, using these
+commands in addition to the ones needed by participants.
+
+  * gitlink:git-am[1] to apply patches e-mailed in from your
+    contributors.
+
+  * gitlink:git-pull[1] to merge from your trusted lieutenants.
+
+  * gitlink:git-format-patch[1] to prepare and send suggested
+    alternative to contributors.
+
+  * gitlink:git-revert[1] to undo botched commits.
+
+  * gitlink:git-push[1] to publish the bleeding edge.
+
+
+Examples
+~~~~~~~~
+
+My typical GIT day.::
++
+------------
+$ git status <1>
+$ git show-branch <2>
+$ mailx <3>
+& s 2 3 4 5 ./+to-apply
+& s 7 8 ./+hold-linus
+& q
+$ git checkout master
+$ git am -3 -i -s -u ./+to-apply <4>
+$ compile/test
+$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>
+$ git checkout topic/one && git rebase master <6>
+$ git checkout pu && git reset --hard master <7>
+$ git pull . topic/one topic/two && git pull . hold/linus <8>
+$ git checkout maint
+$ git cherry-pick master~4 <9>
+$ compile/test
+$ git tag -s -m 'GIT 0.99.9x' v0.99.9x <10>
+$ git fetch ko && git show-branch master maint 'tags/ko-*' <11>
+$ git push ko <12>
+$ git push ko v0.99.9x <13>
+
+<1> see what I was in the middle of doing, if any.
+<2> see what topic branches I have and think about how ready
+they are.
+<3> read mails, save ones that are applicable, and save others
+that are not quite ready.
+<4> apply them, interactively, with my sign-offs.
+<5> create topic branch as needed and apply, again with my
+sign-offs. 
+<6> rebase internal topic branch that has not been merged to the
+master, nor exposed as a part of a stable branch.
+<7> restart "pu" every time from the master.
+<8> and bundle topic branches still cooking.
+<9> backport a critical fix.
+<10> create a signed tag.
+<11> make sure I did not accidentally rewind master beyond what I
+already pushed out.  "ko" shorthand points at the repository I have
+at kernel.org, and looks like this:
+    $ cat .git/remotes/ko
+    URL: kernel.org:/pub/scm/git/git.git
+    Pull: master:refs/tags/ko-master
+    Pull: maint:refs/tags/ko-maint
+    Push: master
+    Push: +pu
+    Push: maint
+In the output from "git show-branch", "master" should have
+everything "ko-master" has.
+<12> push out the bleeding edge.
+<13> push the tag out, too.
+------------
+
+
+Repository Administration[[Repository Administration]]
+------------------------------------------------------
+
+A repository administrator uses the following tools to set up
+and maintain access to the repository by developers.
+
+  * gitlink:git-daemon[1] to allow anonymous download from
+    repository.
+
+  * gitlink:git-shell[1] can be used as a 'restricted login shell'
+    for shared central repository users.
+
+link:howto/update-hook-example.txt[update hook howto] has a good
+example of managing a shared central repository.
+
+
+Examples
+~~~~~~~~
+
+Run git-daemon to serve /pub/scm from inetd.::
++
+------------
+$ grep git /etc/inet.conf
+git    stream  tcp     nowait  nobody \
+  /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm
+------------
++
+The actual configuration line should be on one line.
+
+Give push/pull only access to developers.::
++
+------------
+$ grep git /etc/passwd <1>
+alice:x:1000:1000::/home/alice:/usr/bin/git-shell
+bob:x:1001:1001::/home/bob:/usr/bin/git-shell
+cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
+david:x:1003:1003::/home/david:/usr/bin/git-shell
+$ grep git /etc/shells <2>
+/usr/bin/git-shell
+
+<1> log-in shell is set to /usr/bin/git-shell, which does not
+allow anything but "git push" and "git pull".  The users should
+get an ssh access to the machine.
+<2> in many distributions /etc/shells needs to list what is used
+as the login shell.
+------------
+
+CVS-style shared repository.::
++
+------------
+$ grep git /etc/group <1>
+git:x:9418:alice,bob,cindy,david
+$ cd /home/devo.git
+$ ls -l <2>
+  lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -> refs/heads/master
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches
+  -rw-rw-r--   1 david git    84 Dec  4 22:40 config
+  -rw-rw-r--   1 david git    58 Dec  4 22:40 description
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks
+  -rw-rw-r--   1 david git 37504 Dec  4 22:40 index
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 info
+  drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects
+  drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs
+  drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes
+$ ls -l hooks/update <3>
+  -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update
+$ cat info/allowed-users <4>
+refs/heads/master      alice\|cindy
+refs/heads/doc-update  bob
+refs/tags/v[0-9]*      david
+
+<1> place the developers into the same git group.
+<2> and make the shared repository writable by the group.
+<3> use update-hook example by Carl from Documentation/howto/
+for branch policy control.
+<4> alice and cindy can push into master, only bob can push into doc-update.
+david is the release manager and is the only person who can
+create and push version tags.
+------------
+
+HTTP server to support dumb protocol transfer.::
++
+------------
+dev$ git update-server-info <1>
+dev$ ftp user@isp.example.com <2>
+ftp> cp -r .git /home/user/myproject.git
+
+<1> make sure your info/refs and objects/info/packs are up-to-date
+<2> upload to public HTTP server hosted by your ISP.
+------------
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
new file mode 100644 (file)
index 0000000..13f34d3
--- /dev/null
@@ -0,0 +1,41 @@
+-a, \--append::
+       Append ref names and object names of fetched refs to the
+       existing contents of `.git/FETCH_HEAD`.  Without this
+       option old data in `.git/FETCH_HEAD` will be overwritten.
+
+\--upload-pack <upload-pack>::
+        When given, and the repository to fetch from is handled
+        by 'git-fetch-pack', '--exec=<upload-pack>' is passed to
+        the command to specify non-default path for the command
+        run on the other end.
+
+-f, \--force::
+       When `git-fetch` is used with `<rbranch>:<lbranch>`
+       refspec, it refuses to update the local branch
+       `<lbranch>` unless the remote branch `<rbranch>` it
+       fetches is a descendant of `<lbranch>`.  This option
+       overrides that check.
+
+\--no-tags::
+       By default, `git-fetch` fetches tags that point at
+       objects that are downloaded from the remote repository
+       and stores them locally.  This option disables this
+       automatic tag following.
+
+-t, \--tags::
+       Most of the tags are fetched automatically as branch
+       heads are downloaded, but tags that do not point at
+       objects reachable from the branch heads that are being
+       tracked will not be fetched by this mechanism.  This
+       flag lets all tags and their associated objects be
+       downloaded.
+
+-k, \--keep::
+       Keep downloaded pack.
+
+-u, \--update-head-ok::
+       By default `git-fetch` refuses to update the head which
+       corresponds to the current branch.  This flag disables the
+       check.  Note that fetching into the current branch will not
+       update the index and working directory, so use it with care.
+
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
new file mode 100644 (file)
index 0000000..89e4614
--- /dev/null
@@ -0,0 +1,75 @@
+git-add(1)
+==========
+
+NAME
+----
+git-add - Add files to the index file.
+
+SYNOPSIS
+--------
+'git-add' [-n] [-v] <file>...
+
+DESCRIPTION
+-----------
+A simple wrapper for git-update-index to add files to the index,
+for people used to do "cvs add".
+
+
+OPTIONS
+-------
+<file>...::
+       Files to add to the index.
+
+-n::
+        Don't actually add the file(s), just show if they exist.
+
+-v::
+        Be verbose.
+
+
+DISCUSSION
+----------
+
+The list of <file> given to the command is fed to `git-ls-files`
+command to list files that are not registered in the index and
+are not ignored/excluded by `$GIT_DIR/info/exclude` file or
+`.gitignore` file in each directory.  This means two things:
+
+. You can put the name of a directory on the command line, and
+  the command will add all files in it and its subdirectories;
+
+. Giving the name of a file that is already in index does not
+  run `git-update-index` on that path.
+
+
+EXAMPLES
+--------
+git-add Documentation/\\*.txt::
+
+       Adds all `\*.txt` files that are not in the index under
+       `Documentation` directory and its subdirectories.
++
+Note that the asterisk `\*` is quoted from the shell in this
+example; this lets the command to include the files from
+subdirectories of `Documentation/` directory.
+
+git-add git-*.sh::
+
+       Adds all git-*.sh scripts that are not in the index.
+       Because this example lets shell expand the asterisk
+       (i.e. you are listing the files explicitly), it does not
+       add `subdir/git-foo.sh` to the index.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
new file mode 100644 (file)
index 0000000..02cabc9
--- /dev/null
@@ -0,0 +1,97 @@
+git-am(1)
+=========
+
+NAME
+----
+git-am - Apply a series of patches in a mailbox
+
+
+SYNOPSIS
+--------
+[verse]
+'git-am' [--signoff] [--dotest=<dir>] [--utf8] [--binary] [--3way] <mbox>...
+'git-am' [--skip | --resolved]
+
+DESCRIPTION
+-----------
+Splits mail messages in a mailbox into commit log message,
+authorship information and patches, and applies them to the
+current branch.
+
+OPTIONS
+-------
+--signoff::
+       Add `Signed-off-by:` line to the commit message, using
+       the committer identity of yourself.
+
+--dotest=<dir>::
+       Instead of `.dotest` directory, use <dir> as a working
+       area to store extracted patches.
+
+--utf8, --keep::
+       Pass `-u` and `-k` flags to `git-mailinfo` (see
+       gitlink:git-mailinfo[1]).
+
+--binary::
+       Pass `--allow-binary-replacement` flag to `git-apply`
+       (see gitlink:git-apply[1]).
+
+--3way::
+       When the patch does not apply cleanly, fall back on
+       3-way merge, if the patch records the identity of blobs
+       it is supposed to apply to, and we have those blobs
+       locally.
+
+--skip::
+       Skip the current patch.  This is only meaningful when
+       restarting an aborted patch.
+
+--interactive::
+       Run interactively, just like git-applymbox.
+
+--resolved::
+       After a patch failure (e.g. attempting to apply
+       conflicting patch), the user has applied it by hand and
+       the index file stores the result of the application.
+       Make a commit using the authorship and commit log
+       extracted from the e-mail message and the current index
+       file, and continue.
+
+DISCUSSION
+----------
+
+When initially invoking it, you give it names of the mailboxes
+to crunch.  Upon seeing the first patch that does not apply, it
+aborts in the middle, just like 'git-applymbox' does.  You can
+recover from this in one of two ways:
+
+. skip the current one by re-running the command with '--skip'
+  option.
+
+. hand resolve the conflict in the working directory, and update
+  the index file to bring it in a state that the patch should
+  have produced.  Then run the command with '--resolved' option.
+
+The command refuses to process new mailboxes while `.dotest`
+directory exists, so if you decide to start over from scratch,
+run `rm -f .dotest` before running the command with mailbox
+names.
+
+
+SEE ALSO
+--------
+gitlink:git-applymbox[1], gitlink:git-applypatch[1].
+
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
new file mode 100644 (file)
index 0000000..75076b6
--- /dev/null
@@ -0,0 +1,111 @@
+git-apply(1)
+============
+
+NAME
+----
+git-apply - Apply patch on a git index file and a work tree
+
+
+SYNOPSIS
+--------
+[verse]
+'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply]
+         [--no-add] [--index-info] [--allow-binary-replacement] [-z] [-pNUM]
+         [<patch>...]
+
+DESCRIPTION
+-----------
+Reads supplied diff output and applies it on a git index file
+and a work tree.
+
+OPTIONS
+-------
+<patch>...::
+       The files to read patch from.  '-' can be used to read
+       from the standard input.
+
+--stat::
+       Instead of applying the patch, output diffstat for the
+       input.  Turns off "apply".
+
+--numstat::
+       Similar to \--stat, but shows number of added and
+       deleted lines in decimal notation and pathname without
+       abbreviation, to make it more machine friendly.  Turns
+       off "apply".
+
+--summary::
+       Instead of applying the patch, output a condensed
+       summary of information obtained from git diff extended
+       headers, such as creations, renames and mode changes.
+       Turns off "apply".
+
+--check::
+       Instead of applying the patch, see if the patch is
+       applicable to the current work tree and/or the index
+       file and detects errors.  Turns off "apply".
+
+--index::
+       When --check is in effect, or when applying the patch
+       (which is the default when none of the options that
+       disables it is in effect), make sure the patch is
+       applicable to what the current index file records.  If
+       the file to be patched in the work tree is not
+       up-to-date, it is flagged as an error.  This flag also
+       causes the index file to be updated.
+
+--index-info::
+       Newer git-diff output has embedded 'index information'
+       for each blob to help identify the original version that
+       the patch applies to.  When this flag is given, and if
+       the original version of the blob is available locally,
+       outputs information about them to the standard output.
+
+-z::
+       When showing the index information, do not munge paths,
+       but use NUL terminated machine readable format.  Without
+       this flag, the pathnames output will have TAB, LF, and
+       backslash characters replaced with `\t`, `\n`, and `\\`,
+       respectively.
+
+-p<n>::
+       Remove <n> leading slashes from traditional diff paths. The
+       default is 1.
+
+--apply::
+       If you use any of the options marked ``Turns off
+       "apply"'' above, git-apply reads and outputs the
+       information you asked without actually applying the
+       patch.  Give this flag after those flags to also apply
+       the patch.
+
+--no-add::
+       When applying a patch, ignore additions made by the
+       patch.  This can be used to extract common part between
+       two files by first running `diff` on them and applying
+       the result with this option, which would apply the
+       deletion part but not addition part.
+
+--allow-binary-replacement::
+       When applying a patch, which is a git-enhanced patch
+       that was prepared to record the pre- and post-image object
+       name in full, and the path being patched exactly matches
+       the object the patch applies to (i.e. "index" line's
+       pre-image object name is what is in the working tree),
+       and the post-image object is available in the object
+       database, use the post-image object as the patch
+       result.  This allows binary files to be patched in a
+       very limited way.
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt
new file mode 100644 (file)
index 0000000..f74c6a4
--- /dev/null
@@ -0,0 +1,92 @@
+git-applymbox(1)
+================
+
+NAME
+----
+git-applymbox - Apply a series of patches in a mailbox
+
+
+SYNOPSIS
+--------
+'git-applymbox' [-u] [-k] [-q] [-m] ( -c .dotest/<num> | <mbox> ) [ <signoff> ]
+
+DESCRIPTION
+-----------
+Splits mail messages in a mailbox into commit log message,
+authorship information and patches, and applies them to the
+current branch.
+
+
+OPTIONS
+-------
+-q::
+       Apply patches interactively.  The user will be given
+       opportunity to edit the log message and the patch before
+       attempting to apply it.
+
+-k::
+       Usually the program 'cleans up' the Subject: header line
+       to extract the title line for the commit log message,
+       among which (1) remove 'Re:' or 're:', (2) leading
+       whitespaces, (3) '[' up to ']', typically '[PATCH]', and
+       then prepends "[PATCH] ".  This flag forbids this
+       munging, and is most useful when used to read back 'git
+       format-patch --mbox' output.
+
+-m::
+       Patches are applied with `git-apply` command, and unless
+       it cleanly applies without fuzz, the processing fails.
+       With this flag, if a tree that the patch applies cleanly
+       is found in a repository, the patch is applied to the
+       tree and then a 3-way merge between the resulting tree
+       and the current tree.
+
+-u::
+       By default, the commit log message, author name and
+       author email are taken from the e-mail without any
+       charset conversion, after minimally decoding MIME
+       transfer encoding.  This flag causes the resulting
+       commit to be encoded in utf-8 by transliterating them.
+       Note that the patch is always used as is without charset
+       conversion, even with this flag.
+
+-c .dotest/<num>::
+       When the patch contained in an e-mail does not cleanly
+       apply, the command exits with an error message. The
+       patch and extracted message are found in .dotest/, and
+       you could re-run 'git applymbox' with '-c .dotest/<num>'
+       flag to restart the process after inspecting and fixing
+       them.
+
+<mbox>::
+       The name of the file that contains the e-mail messages
+       with patches.  This file should be in the UNIX mailbox
+       format.  See 'SubmittingPatches' document to learn about
+       the formatting convention for e-mail submission.
+
+<signoff>::
+       The name of the file that contains your "Signed-off-by"
+       line.  See 'SubmittingPatches' document to learn what
+       "Signed-off-by" line means.  You can also just say
+       'yes', 'true', 'me', or 'please' to use an automatically
+       generated "Signed-off-by" line based on your committer
+       identity.
+
+
+SEE ALSO
+--------
+gitlink:git-am[1], gitlink:git-applypatch[1].
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-applypatch.txt b/Documentation/git-applypatch.txt
new file mode 100644 (file)
index 0000000..5b9037d
--- /dev/null
@@ -0,0 +1,50 @@
+git-applypatch(1)
+=================
+
+NAME
+----
+git-applypatch - Apply one patch extracted from an e-mail.
+
+
+SYNOPSIS
+--------
+'git-applypatch' <msg> <patch> <info> [<signoff>]
+
+DESCRIPTION
+-----------
+Takes three files <msg>, <patch>, and <info> prepared from an
+e-mail message by 'git-mailinfo', and creates a commit.  It is
+usually not necessary to use this command directly.
+
+This command can run `applypatch-msg`, `pre-applypatch`, and
+`post-applypatch` hooks.  See link:hooks.html[hooks] for more
+information.
+
+
+OPTIONS
+-------
+<msg>::
+       Commit log message (sans the first line, which comes
+       from e-mail Subject stored in <info>).
+
+<patch>::
+       The patch to apply.
+
+<info>::
+       Author and subject information extracted from e-mail,
+       used on "author" line and as the first line of the
+       commit log message.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt
new file mode 100644 (file)
index 0000000..023d3ae
--- /dev/null
@@ -0,0 +1,106 @@
+git-archimport(1)
+=================
+
+NAME
+----
+git-archimport - Import an Arch repository into git
+
+
+SYNOPSIS
+--------
+[verse]
+`git-archimport` [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]
+               <archive/branch> [ <archive/branch> ]
+
+DESCRIPTION
+-----------
+Imports a project from one or more Arch repositories. It will follow branches
+and repositories within the namespaces defined by the <archive/branch>
+parameters supplied. If it cannot find the remote branch a merge comes from
+it will just import it as a regular commit. If it can find it, it will mark it 
+as a merge whenever possible (see discussion below). 
+
+The script expects you to provide the key roots where it can start the import 
+from an 'initial import' or 'tag' type of Arch commit. It will follow and 
+import new branches within the provided roots. 
+
+It expects to be dealing with one project only. If it sees 
+branches that have different roots, it will refuse to run. In that case, 
+edit your <archive/branch> parameters to define clearly the scope of the 
+import. 
+
+`git-archimport` uses `tla` extensively in the background to access the 
+Arch repository.
+Make sure you have a recent version of `tla` available in the path. `tla` must
+know about the repositories you pass to `git-archimport`. 
+
+For the initial import `git-archimport` expects to find itself in an empty 
+directory. To follow the development of a project that uses Arch, rerun 
+`git-archimport` with the same parameters as the initial import to perform 
+incremental imports.
+
+MERGES
+------
+Patch merge data from Arch is used to mark merges in git as well. git 
+does not care much about tracking patches, and only considers a merge when a
+branch incorporates all the commits since the point they forked. The end result
+is that git will have a good idea of how far branches have diverged. So the 
+import process does lose some patch-trading metadata.
+
+Fortunately, when you try and merge branches imported from Arch, 
+git will find a good merge base, and it has a good chance of identifying 
+patches that have been traded out-of-sequence between the branches. 
+
+OPTIONS
+-------
+
+-h::
+       Display usage.
+
+-v::
+       Verbose output. 
+
+-T::
+       Many tags. Will create a tag for every commit, reflecting the commit 
+       name in the Arch repository.
+
+-f::
+       Use the fast patchset import strategy.  This can be significantly
+       faster for large trees, but cannot handle directory renames or
+       permissions changes.  The default strategy is slow and safe.
+
+-o::
+       Use this for compatibility with old-style branch names used by
+       earlier versions of git-archimport.  Old-style branch names
+       were category--branch, whereas new-style branch names are
+       archive,category--branch--version.
+
+-D <depth>::
+       Follow merge ancestry and attempt to import trees that have been
+       merged from.  Specify a depth greater than 1 if patch logs have been
+       pruned.
+
+-a::
+       Attempt to auto-register archives at http://mirrors.sourcecontrol.net
+       This is particularly useful with the -D option.
+
+-t <tmpdir>::
+       Override the default tempdir.
+
+
+<archive/branch>::
+       Archive/branch identifier in a format that `tla log` understands. 
+
+
+Author
+------
+Written by Martin Langhoff <martin@catalyst.net.nz>.
+
+Documentation
+--------------
+Documentation by Junio C Hamano, Martin Langhoff and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
new file mode 100644 (file)
index 0000000..ac4b496
--- /dev/null
@@ -0,0 +1,136 @@
+git-bisect(1)
+=============
+
+NAME
+----
+git-bisect - Find the change that introduced a bug
+
+
+SYNOPSIS
+--------
+'git bisect' <subcommand> <options> 
+
+DESCRIPTION
+-----------
+The command takes various subcommands, and different options
+depending on the subcommand:
+
+ git bisect start [<paths>...]
+ git bisect bad <rev>
+ git bisect good <rev>
+ git bisect reset [<branch>]
+ git bisect visualize
+ git bisect replay <logfile>
+ git bisect log
+
+This command uses 'git-rev-list --bisect' option to help drive
+the binary search process to find which change introduced a bug,
+given an old "good" commit object name and a later "bad" commit
+object name.
+
+The way you use it is:
+
+------------------------------------------------
+$ git bisect start
+$ git bisect bad                       # Current version is bad
+$ git bisect good v2.6.13-rc2          # v2.6.13-rc2 was the last version
+                                       # tested that was good
+------------------------------------------------
+
+When you give at least one bad and one good versions, it will
+bisect the revision tree and say something like:
+
+------------------------------------------------
+Bisecting: 675 revisions left to test after this
+------------------------------------------------
+
+and check out the state in the middle. Now, compile that kernel, and boot
+it. Now, let's say that this booted kernel works fine, then just do
+
+------------------------------------------------
+$ git bisect good                      # this one is good
+------------------------------------------------
+
+which will now say
+
+------------------------------------------------
+Bisecting: 337 revisions left to test after this
+------------------------------------------------
+
+and you continue along, compiling that one, testing it, and depending on
+whether it is good or bad, you say "git bisect good" or "git bisect bad",
+and ask for the next bisection.
+
+Until you have no more left, and you'll have been left with the first bad
+kernel rev in "refs/bisect/bad".
+
+Oh, and then after you want to reset to the original head, do a
+
+------------------------------------------------
+$ git bisect reset
+------------------------------------------------
+
+to get back to the master branch, instead of being in one of the bisection
+branches ("git bisect start" will do that for you too, actually: it will
+reset the bisection state, and before it does that it checks that you're
+not using some old bisection branch).
+
+During the bisection process, you can say
+
+------------
+$ git bisect visualize
+------------
+
+to see the currently remaining suspects in `gitk`.
+
+The good/bad input is logged, and `git bisect
+log` shows what you have done so far.  You can truncate its
+output somewhere and save it in a file, and run
+
+------------
+$ git bisect replay that-file
+------------
+
+if you find later you made a mistake telling good/bad about a
+revision.
+
+If in a middle of bisect session, you know what the bisect
+suggested to try next is not a good one to test (e.g. the change
+the commit introduces is known not to work in your environment
+and you know it does not have anything to do with the bug you
+are chasing), you may want to find a near-by commit and try that
+instead.  It goes something like this:
+
+------------
+$ git bisect good/bad                  # previous round was good/bad.
+Bisecting: 337 revisions left to test after this
+$ git bisect visualize                 # oops, that is uninteresting.
+$ git reset --hard HEAD~3              # try 3 revs before what
+                                       # was suggested
+------------
+
+Then compile and test the one you chose to try.  After that,
+tell bisect what the result was as usual.
+
+You can further cut down the number of trials if you know what
+part of the tree is involved in the problem you are tracking
+down, by giving paths parameters when you say `bisect start`,
+like this:
+
+------------
+$ git bisect start arch/i386 include/asm-i386
+------------
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+-------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
new file mode 100644 (file)
index 0000000..b1bc827
--- /dev/null
@@ -0,0 +1,75 @@
+git-branch(1)
+=============
+
+NAME
+----
+git-branch - Create a new branch, or remove an old one.
+
+SYNOPSIS
+--------
+'git-branch' [(-d | -D) <branchname>] | [[-f] <branchname> [<start-point>]]
+
+DESCRIPTION
+-----------
+If no argument is provided, show available branches and mark current
+branch with star. Otherwise, create a new branch of name <branchname>.
+
+If a starting point is also specified, that will be where the branch is
+created, otherwise it will be created at the current HEAD.
+
+OPTIONS
+-------
+-d::
+       Delete a branch. The branch must be fully merged.
+
+-D::
+       Delete a branch irrespective of its index status.
+
+-f::
+       Force a reset of <branchname> to <start-point> (or current head).
+
+<branchname>::
+       The name of the branch to create or delete.
+
+<start-point>::
+       Where to create the branch; defaults to HEAD. This
+       option has no meaning with -d and -D.
+
+
+Examples
+~~~~~~~~
+
+Start development off of a know tag::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
+$ cd my2.6
+$ git branch my2.6.14 v2.6.14 <1>
+$ git checkout my2.6.14
+
+<1> These two steps are the same as "checkout -b my2.6.14 v2.6.14".
+------------
+
+Delete unneeded branch::
++
+------------
+$ git clone git://git.kernel.org/.../git.git my.git
+$ cd my.git
+$ git branch -D todo <1>
+
+<1> delete todo branch even if the "master" branch does not have all
+commits from todo branch.
+------------
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
new file mode 100644 (file)
index 0000000..504eb1b
--- /dev/null
@@ -0,0 +1,67 @@
+git-cat-file(1)
+===============
+
+NAME
+----
+git-cat-file - Provide content or type information for repository objects
+
+
+SYNOPSIS
+--------
+'git-cat-file' [-t | -s | -e | <type>] <object>
+
+DESCRIPTION
+-----------
+Provides content or type of objects in the repository. The type
+is required unless '-t' is used to find the object type,
+or '-s' is used to find the object size.
+
+OPTIONS
+-------
+<object>::
+       The sha1 identifier of the object.
+
+-t::
+       Instead of the content, show the object type identified by
+       <object>.
+
+-s::
+       Instead of the content, show the object size identified by
+       <object>.
+
+-e::
+       Suppress all output; instead exit with zero status if <object>
+       exists and is a valid object.
+
+<type>::
+       Typically this matches the real type of <object> but asking
+       for a type that can trivially be dereferenced from the given
+       <object> is also permitted.  An example is to ask for a
+       "tree" with <object> being a commit object that contains it,
+       or to ask for a "blob" with <object> being a tag object that
+       points at it.
+
+OUTPUT
+------
+If '-t' is specified, one of the <type>.
+
+If '-s' is specified, the size of the <object> in bytes.
+
+If '-e' is specified, no output.
+
+Otherwise the raw (though uncompressed) contents of the <object> will
+be returned.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
new file mode 100644 (file)
index 0000000..f7f84c6
--- /dev/null
@@ -0,0 +1,52 @@
+git-check-ref-format(1)
+=======================
+
+NAME
+----
+git-check-ref-format - Make sure ref name is well formed.
+
+SYNOPSIS
+--------
+'git-check-ref-format' <refname>
+
+DESCRIPTION
+-----------
+Checks if a given 'refname' is acceptable, and exits non-zero if
+it is not.
+
+A reference is used in git to specify branches and tags.  A
+branch head is stored under `$GIT_DIR/refs/heads` directory, and
+a tag is stored under `$GIT_DIR/refs/tags` directory.  git
+imposes the following rules on how refs are named:
+
+. It could be named hierarchically (i.e. separated with slash
+  `/`), but each of its component cannot begin with a dot `.`;
+
+. It cannot have two consecutive dots `..` anywhere;
+
+. It cannot have ASCII control character (i.e. bytes whose
+  values are lower than \040, or \177 `DEL`), space, tilde `~`,
+  caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`,
+  or open bracket `[` anywhere;
+
+. It cannot end with a slash `/`.
+
+These rules makes it easy for shell script based tools to parse
+refnames, pathname expansion by the shell when a refname is used
+unquoted (by mistake), and also avoids ambiguities in certain
+refname expressions (see gitlink:git-rev-parse[1]).  Namely:
+
+. double-dot `..` are often used as in `ref1..ref2`, and in some
+  context this notation means `{caret}ref1 ref2` (i.e. not in
+  ref1 and in ref2).
+
+. tilde `~` and caret `{caret}` are used to introduce postfix
+  'nth parent' and 'peel onion' operation.
+
+. colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
+  value and store it in dstref" in fetch and push operations.
+
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
new file mode 100644 (file)
index 0000000..2a1e526
--- /dev/null
@@ -0,0 +1,122 @@
+git-checkout-index(1)
+=====================
+
+NAME
+----
+git-checkout-index - Copy files from the index to the working directory
+
+
+SYNOPSIS
+--------
+[verse]
+'git-checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>]
+                  [--stage=<number>] [--] <file>...
+
+DESCRIPTION
+-----------
+Will copy all files listed from the index to the working directory
+(not overwriting existing files).
+
+OPTIONS
+-------
+-u|--index::
+       update stat information for the checked out entries in
+       the index file.
+
+-q|--quiet::
+       be quiet if files exist or are not in the index
+
+-f|--force::
+       forces overwrite of existing files
+
+-a|--all::
+       checks out all files in the index.  Cannot be used
+       together with explicit filenames.
+
+-n|--no-create::
+       Don't checkout new files, only refresh files already checked
+       out.
+
+--prefix=<string>::
+       When creating files, prepend <string> (usually a directory
+       including a trailing /)
+
+--stage=<number>::
+       Instead of checking out unmerged entries, copy out the
+       files from named stage.  <number> must be between 1 and 3.
+
+--::
+       Do not interpret any more arguments as options.
+
+The order of the flags used to matter, but not anymore.
+
+Just doing `git-checkout-index` does nothing. You probably meant
+`git-checkout-index -a`. And if you want to force it, you want
+`git-checkout-index -f -a`.
+
+Intuitiveness is not the goal here. Repeatability is. The reason for
+the "no arguments means no work" behavior is that from scripts you are
+supposed to be able to do:
+
+----------------
+$ find . -name '*.h' -print0 | xargs -0 git-checkout-index -f --
+----------------
+
+which will force all existing `*.h` files to be replaced with their
+cached copies. If an empty command line implied "all", then this would
+force-refresh everything in the index, which was not the point.
+
+The `--` is just a good idea when you know the rest will be filenames;
+it will prevent problems with a filename of, for example,  `-a`.
+Using `--` is probably a good policy in scripts.
+
+
+EXAMPLES
+--------
+To update and refresh only the files already checked out::
++
+----------------
+$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+----------------
+
+Using `git-checkout-index` to "export an entire tree"::
+       The prefix ability basically makes it trivial to use
+       `git-checkout-index` as an "export as tree" function.
+       Just read the desired tree into the index, and do:
++
+----------------
+$ git-checkout-index --prefix=git-export-dir/ -a
+----------------
++
+`git-checkout-index` will "export" the index into the specified
+directory.
++
+The final "/" is important. The exported name is literally just
+prefixed with the specified string.  Contrast this with the
+following example.
+
+Export files with a prefix::
++
+----------------
+$ git-checkout-index --prefix=.merged- Makefile
+----------------
++
+This will check out the currently cached copy of `Makefile`
+into the file `.merged-Makefile`.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+
+Documentation
+--------------
+Documentation by David Greaves,
+Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
new file mode 100644 (file)
index 0000000..df9a618
--- /dev/null
@@ -0,0 +1,145 @@
+git-checkout(1)
+===============
+
+NAME
+----
+git-checkout - Checkout and switch to a branch.
+
+SYNOPSIS
+--------
+'git-checkout' [-f] [-b <new_branch>] [-m] [<branch>] [<paths>...]
+
+DESCRIPTION
+-----------
+
+When <paths> are not given, this command switches branches, by
+updating the index and working tree to reflect the specified
+branch, <branch>, and updating HEAD to be <branch> or, if
+specified, <new_branch>.
+
+When <paths> are given, this command does *not* switch
+branches.  It updates the named paths in the working tree from
+the index file (i.e. it runs `git-checkout-index -f -u`).  In
+this case, `-f` and `-b` options are meaningless and giving
+either of them results in an error.  <branch> argument can be
+used to specify a specific tree-ish to update the index for the
+given paths before updating the working tree.
+
+
+OPTIONS
+-------
+-f::
+       Force an re-read of everything.
+
+-b::
+       Create a new branch and start it at <branch>.
+
+-m::
+       If you have local modifications to a file that is
+       different between the current branch and the branch you
+       are switching to, the command refuses to switch
+       branches, to preserve your modifications in context.
+       With this option, a three-way merge between the current
+       branch, your working tree contents, and the new branch
+       is done, and you will be on the new branch.
++
+When a merge conflict happens, the index entries for conflicting
+paths are left unmerged, and you need to resolve the conflicts
+and mark the resolved paths with `git update-index`.
+
+<new_branch>::
+       Name for the new branch.
+
+<branch>::
+       Branch to checkout; may be any object ID that resolves to a
+       commit. Defaults to HEAD.
+
+
+EXAMPLES
+--------
+
+. The following sequence checks out the `master` branch, reverts
+the `Makefile` to two revisions back, deletes hello.c by
+mistake, and gets it back from the index.
++
+------------
+$ git checkout master <1>
+$ git checkout master~2 Makefile <2>
+$ rm -f hello.c
+$ git checkout hello.c <3>
+
+<1> switch branch
+<2> take out a file out of other commit
+<3> or "git checkout -- hello.c", as in the next example.
+------------
++
+If you have an unfortunate branch that is named `hello.c`, the
+last step above would be confused as an instruction to switch to
+that branch.  You should instead write:
++
+------------
+$ git checkout -- hello.c
+------------
+
+. After working in a wrong branch, switching to the correct
+branch you would want to is done with:
++
+------------
+$ git checkout mytopic
+------------
++
+However, your "wrong" branch and correct "mytopic" branch may
+differ in files that you have locally modified, in which case,
+the above checkout would fail like this:
++
+------------
+$ git checkout mytopic
+fatal: Entry 'frotz' not uptodate. Cannot merge.
+------------
++
+You can give the `-m` flag to the command, which would try a
+three-way merge:
++
+------------
+$ git checkout -m mytopic
+Auto-merging frotz
+------------
++
+After this three-way merge, the local modifications are _not_
+registered in your index file, so `git diff` would show you what
+changes you made since the tip of the new branch.
+
+. When a merge conflict happens during switching branches with
+the `-m` option, you would see something like this:
++
+------------
+$ git checkout -m mytopic
+Auto-merging frotz
+merge: warning: conflicts during merge
+ERROR: Merge conflict in frotz
+fatal: merge program failed
+------------
++
+At this point, `git diff` shows the changes cleanly merged as in
+the previous example, as well as the changes in the conflicted
+files.  Edit and resolve the conflict and mark it resolved with
+`git update-index` as usual:
++
+------------
+$ edit frotz
+$ git update-index frotz
+------------
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
new file mode 100644 (file)
index 0000000..4f323fa
--- /dev/null
@@ -0,0 +1,60 @@
+git-cherry-pick(1)
+==================
+
+NAME
+----
+git-cherry-pick - Apply the change introduced by an existing commit.
+
+SYNOPSIS
+--------
+'git-cherry-pick' [--edit] [-n] [-r] <commit>
+
+DESCRIPTION
+-----------
+Given one existing commit, apply the change the patch introduces, and record a
+new commit that records it.  This requires your working tree to be clean (no
+modifications from the HEAD commit).
+
+OPTIONS
+-------
+<commit>::
+       Commit to cherry-pick.
+
+-e|--edit::
+       With this option, `git-cherry-pick` will let you edit the commit
+       message prior committing.
+
+-r|--replay::
+       Usually the command appends which commit was
+       cherry-picked after the original commit message when
+       making a commit.  This option, '--replay', causes it to
+       use the original commit message intact.  This is useful
+       when you are reordering the patches in your private tree
+       before publishing.
+
+-n|--no-commit::
+       Usually the command automatically creates a commit with
+       a commit log message stating which commit was
+       cherry-picked.  This flag applies the change necessary
+       to cherry-pick the named commit to your working tree,
+       but does not make the commit.  In addition, when this
+       option is used, your working tree does not have to match
+       the HEAD commit.  The cherry-pick is done against the
+       beginning state of your working tree.
++
+This is useful when cherry-picking more than one commits'
+effect to your working tree in a row.
+
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt
new file mode 100644 (file)
index 0000000..af87966
--- /dev/null
@@ -0,0 +1,42 @@
+git-cherry(1)
+=============
+
+NAME
+----
+git-cherry - Find commits not merged upstream.
+
+SYNOPSIS
+--------
+'git-cherry' [-v] <upstream> [<head>]
+
+DESCRIPTION
+-----------
+Each commit between the fork-point and <head> is examined, and compared against
+the change each commit between the fork-point and <upstream> introduces.
+Commits already included in upstream are prefixed with '-' (meaning "drop from
+my local pull"), while commits missing from upstream are prefixed with '+'
+(meaning "add to the updated upstream").
+
+OPTIONS
+-------
+-v::
+       Verbose.
+
+<upstream>::
+       Upstream branch to compare against.
+
+<head>::
+       Working branch; defaults to HEAD.
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-clone-pack.txt b/Documentation/git-clone-pack.txt
new file mode 100644 (file)
index 0000000..39906fc
--- /dev/null
@@ -0,0 +1,64 @@
+git-clone-pack(1)
+=================
+
+NAME
+----
+git-clone-pack - Clones a repository by receiving packed objects.
+
+
+SYNOPSIS
+--------
+'git-clone-pack' [--exec=<git-upload-pack>] [<host>:]<directory> [<head>...]
+
+DESCRIPTION
+-----------
+Clones a repository into the current repository by invoking
+'git-upload-pack', possibly on the remote host via ssh, in
+the named repository, and stores the sent pack in the local
+repository.
+
+OPTIONS
+-------
+--exec=<git-upload-pack>::
+       Use this to specify the path to 'git-upload-pack' on the
+       remote side, if it is not found on your $PATH.
+       Installations of sshd ignore the user's environment
+       setup scripts for login shells (e.g. .bash_profile) and
+       your privately installed git may not be found on the system
+       default $PATH.  Another workaround suggested is to set
+       up your $PATH in ".bashrc", but this flag is for people
+       who do not want to pay the overhead for non-interactive
+       shells by having a lean .bashrc file (they set most of
+       the things up in .bash_profile).
+
+<host>::
+       A remote host that houses the repository.  When this
+       part is specified, 'git-upload-pack' is invoked via
+       ssh.
+
+<directory>::
+       The repository to sync from.
+
+<head>...::
+       The heads to update.  This is relative to $GIT_DIR
+       (e.g. "HEAD", "refs/heads/master").  When unspecified,
+       all heads are updated to match the remote repository.
++
+Usually all the refs from existing repository are stored
+under the same name in the new repository.  Giving explicit
+<head> arguments instead writes the object names and refs to
+the standard output, just like get-fetch-pack does.
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano.
+
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
new file mode 100644 (file)
index 0000000..684e4bd
--- /dev/null
@@ -0,0 +1,143 @@
+git-clone(1)
+============
+
+NAME
+----
+git-clone - Clones a repository.
+
+
+SYNOPSIS
+--------
+[verse]
+'git-clone' [-l [-s]] [-q] [-n] [--bare] [-o <name>] [-u <upload-pack>]
+         <repository> [<directory>]
+
+DESCRIPTION
+-----------
+Clones a repository into a newly created directory.  All remote
+branch heads are copied under `$GIT_DIR/refs/heads/`, except
+that the remote `master` is also copied to `origin` branch.
+
+In addition, `$GIT_DIR/remotes/origin` file is set up to have
+this line:
+
+       Pull: master:origin
+
+This is to help the typical workflow of working off of the
+remote `master` branch.  Every time `git pull` without argument
+is run, the progress on the remote `master` branch is tracked by
+copying it into the local `origin` branch, and merged into the
+branch you are currently working on.  Remote branches other than
+`master` are also added there to be tracked.
+
+
+OPTIONS
+-------
+--local::
+-l::
+       When the repository to clone from is on a local machine,
+       this flag bypasses normal "git aware" transport
+       mechanism and clones the repository by making a copy of
+       HEAD and everything under objects and refs directories.
+       The files under .git/objects/ directory are hardlinked
+       to save space when possible.
+
+--shared::
+-s::
+       When the repository to clone is on the local machine,
+       instead of using hard links, automatically setup
+       .git/objects/info/alternatives to share the objects
+       with the source repository.  The resulting repository
+       starts out without any object of its own.
+
+--quiet::
+-q::
+       Operate quietly.  This flag is passed to "rsync" and
+       "git-clone-pack" commands when given.
+
+-n::
+       No checkout of HEAD is performed after the clone is complete.
+
+--bare::
+       Make a 'bare' GIT repository.  That is, instead of
+       creating `<directory>` and placing the administrative
+       files in `<directory>/.git`, make the `<directory>`
+       itself the `$GIT_DIR`. This implies `-n` option.  When
+       this option is used, neither the `origin` branch nor the
+       default `remotes/origin` file is created.
+
+-o <name>::
+       Instead of using the branch name 'origin' to keep track
+       of the upstream repository, use <name> instead.  Note
+       that the shorthand name stored in `remotes/origin` is
+       not affected, but the local branch name to pull the
+       remote `master` branch into is.
+
+--upload-pack <upload-pack>::
+-u <upload-pack>::
+       When given, and the repository to clone from is handled
+       by 'git-clone-pack', '--exec=<upload-pack>' is passed to
+       the command to specify non-default path for the command
+       run on the other end.
+
+<repository>::
+       The (possibly remote) repository to clone from.  It can
+       be any URL git-fetch supports.
+
+<directory>::
+       The name of a new directory to clone into.  The "humanish"
+       part of the source repository is used if no directory is
+       explicitly given ("repo" for "/path/to/repo.git" and "foo"
+       for "host.xz:foo/.git").  Cloning into an existing directory
+       is not allowed.
+
+Examples
+~~~~~~~~
+
+Clone from upstream::
++
+------------
+$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
+$ cd my2.6
+$ make
+------------
+
+
+Make a local clone that borrows from the current directory, without checking things out::
++
+------------
+$ git clone -l -s -n . ../copy
+$ cd copy
+$ git show-branch
+------------
+
+
+Create a bare repository to publish your changes to the public::
++
+------------
+$ git clone --bare -l /home/proj/.git /pub/scm/proj.git
+------------
+
+
+Create a repository on the kernel.org machine that borrows from Linus::
++
+------------
+$ git clone --bare -l -s /pub/scm/.../torvalds/linux-2.6.git \
+    /pub/scm/.../me/subsys-2.6.git
+------------
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
new file mode 100644 (file)
index 0000000..41d1a1c
--- /dev/null
@@ -0,0 +1,100 @@
+git-commit-tree(1)
+==================
+
+NAME
+----
+git-commit-tree - Creates a new commit object
+
+
+SYNOPSIS
+--------
+'git-commit-tree' <tree> [-p <parent commit>]\* < changelog
+
+DESCRIPTION
+-----------
+Creates a new commit object based on the provided tree object and
+emits the new commit object id on stdout. If no parent is given then
+it is considered to be an initial tree.
+
+A commit object usually has 1 parent (a commit after a change) or up
+to 16 parents.  More than one parent represents a merge of branches
+that led to them.
+
+While a tree represents a particular directory state of a working
+directory, a commit represents that state in "time", and explains how
+to get there.
+
+Normally a commit would identify a new "HEAD" state, and while git
+doesn't care where you save the note about that state, in practice we
+tend to just write the result to the file that is pointed at by
+`.git/HEAD`, so that we can always see what the last committed
+state was.
+
+OPTIONS
+-------
+<tree>::
+       An existing tree object
+
+-p <parent commit>::
+       Each '-p' indicates the id of a parent commit object.
+       
+
+Commit Information
+------------------
+
+A commit encapsulates:
+
+- all parent object ids
+- author name, email and date
+- committer name and email and the commit time.
+
+If not provided, "git-commit-tree" uses your name, hostname and domain to
+provide author and committer info. This can be overridden by
+either `.git/config` file, or using the following environment variables.
+
+       GIT_AUTHOR_NAME
+       GIT_AUTHOR_EMAIL
+       GIT_AUTHOR_DATE
+       GIT_COMMITTER_NAME
+       GIT_COMMITTER_EMAIL
+
+(nb "<", ">" and "\n"s are stripped)
+
+In `.git/config` file, the following items are used for GIT_AUTHOR_NAME and
+GIT_AUTHOR_EMAIL:
+
+       [user]
+               name = "Your Name"
+               email = "your@email.address.xz"
+
+A commit comment is read from stdin (max 999 chars). If a changelog
+entry is not provided via "<" redirection, "git-commit-tree" will just wait
+for one to be entered and terminated with ^D.
+
+
+Diagnostics
+-----------
+You don't exist. Go away!::
+    The passwd(5) gecos field couldn't be read
+Your parents must have hated you!::
+    The password(5) gecos field is longer than a giant static buffer.
+Your sysadmin must hate you!::
+    The password(5) name field is longer than a giant static buffer.
+
+See Also
+--------
+gitlink:git-write-tree[1]
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
new file mode 100644 (file)
index 0000000..53b64fa
--- /dev/null
@@ -0,0 +1,138 @@
+git-commit(1)
+=============
+
+NAME
+----
+git-commit - Record your changes
+
+SYNOPSIS
+--------
+[verse]
+'git-commit' [-a] [-i] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>]
+          [-e] [--author <author>] [--] <file>...
+
+DESCRIPTION
+-----------
+Updates the index file for given paths, or all modified files if
+'-a' is specified, and makes a commit object.  The command
+VISUAL and EDITOR environment variables to edit the commit log
+message.
+
+This command can run `commit-msg`, `pre-commit`, and
+`post-commit` hooks.  See link:hooks.html[hooks] for more
+information.
+
+OPTIONS
+-------
+-a|--all::
+       Update all paths in the index file.  This flag notices
+       files that have been modified and deleted, but new files
+       you have not told git about are not affected.
+
+-c or -C <commit>::
+       Take existing commit object, and reuse the log message
+       and the authorship information (including the timestamp)
+       when creating the commit.  With '-C', the editor is not
+       invoked; with '-c' the user can further edit the commit
+       message.
+
+-F <file>::
+       Take the commit message from the given file.  Use '-' to
+       read the message from the standard input.
+
+--author <author>::
+       Override the author name used in the commit.  Use
+       `A U Thor <author@example.com>` format.
+
+-m <msg>::
+       Use the given <msg> as the commit message.
+
+-s|--signoff::
+       Add Signed-off-by line at the end of the commit message.
+
+-v|--verify::
+       Look for suspicious lines the commit introduces, and
+       abort committing if there is one.  The definition of
+       'suspicious lines' is currently the lines that has
+       trailing whitespaces, and the lines whose indentation
+       has a SP character immediately followed by a TAB
+       character.  This is the default.
+
+-n|--no-verify::
+       The opposite of `--verify`.
+
+-e|--edit::
+       The message taken from file with `-F`, command line with
+       `-m`, and from file with `-C` are usually used as the
+       commit log message unmodified.  This option lets you
+       further edit the message taken from these sources.
+
+-i|--include::
+       Instead of committing only the files specified on the
+       command line, update them in the index file and then
+       commit the whole index.  This is the traditional
+       behaviour.
+
+--::
+       Do not interpret any more arguments as options.
+
+<file>...::
+       Commit only the files specified on the command line.
+       This format cannot be used during a merge, nor when the
+       index and the latest commit does not match on the
+       specified paths to avoid confusion.
+
+If you make a commit and then found a mistake immediately after
+that, you can recover from it with gitlink:git-reset[1].
+
+
+Discussion
+----------
+
+`git commit` without _any_ parameter commits the tree structure
+recorded by the current index file.  This is a whole-tree commit
+even the command is invoked from a subdirectory.
+
+`git commit --include paths...` is equivalent to
+
+       git update-index --remove paths...
+       git commit
+
+That is, update the specified paths to the index and then commit
+the whole tree.
+
+`git commit paths...` largely bypasses the index file and
+commits only the changes made to the specified paths.  It has
+however several safety valves to prevent confusion.
+
+. It refuses to run during a merge (i.e. when
+  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
+  that the traditional semantics now needs -i flag.
+
+. It refuses to run if named `paths...` are different in HEAD
+  and the index (ditto about reminding).  Added paths are OK.
+  This is because an earlier `git diff` (not `git diff HEAD`)
+  would have shown the differences since the last `git
+  update-index paths...` to the user, and an inexperienced user
+  may mistakenly think that the changes between the index and
+  the HEAD (i.e. earlier changes made before the last `git
+  update-index paths...` was done) are not being committed.
+
+. It reads HEAD commit into a temporary index file, updates the
+  specified `paths...` and makes a commit.  At the same time,
+  the real index file is also updated with the same `paths...`.
+
+`git commit --all` updates the index file with _all_ changes to
+the working tree, and makes a whole-tree commit, regardless of
+which subdirectory the command is invoked in.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org> and
+Junio C Hamano <junkio@cox.net>
+
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git-convert-objects.txt b/Documentation/git-convert-objects.txt
new file mode 100644 (file)
index 0000000..b1220c0
--- /dev/null
@@ -0,0 +1,29 @@
+git-convert-objects(1)
+======================
+
+NAME
+----
+git-convert-objects - Converts old-style git repository
+
+
+SYNOPSIS
+--------
+'git-convert-objects'
+
+DESCRIPTION
+-----------
+Converts old-style git repository to the latest format
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt
new file mode 100644 (file)
index 0000000..36888d9
--- /dev/null
@@ -0,0 +1,28 @@
+git-count-objects(1)
+====================
+
+NAME
+----
+git-count-objects - Reports on unpacked objects.
+
+SYNOPSIS
+--------
+'git-count-objects'
+
+DESCRIPTION
+-----------
+This counts the number of unpacked object files and disk space consumed by
+them, to help you decide when it is a good time to repack.
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt
new file mode 100644 (file)
index 0000000..d30435a
--- /dev/null
@@ -0,0 +1,76 @@
+git-cvsexportcommit(1)
+======================
+
+NAME
+----
+git-cvsexportcommit - Export a commit to a CVS checkout
+
+
+SYNOPSIS
+--------
+'git-cvsexportcommmit' [-h] [-v] [-c] [-p] [PARENTCOMMIT] COMMITID
+
+
+DESCRIPTION
+-----------
+Exports a commit from GIT to a CVS checkout, making it easier
+to merge patches from a git repository into a CVS repository. 
+
+Execute it from the root of the CVS working copy. GIT_DIR must be defined. 
+See examples below.
+
+It does its best to do the safe thing, it will check that the files are 
+unchanged and up to date in the CVS checkout, and it will not autocommit 
+by default.
+
+Supports file additions, removals, and commits that affect binary files.
+
+If the commit is a merge commit, you must tell git-cvsapplycommit what parent
+should the changeset be done against. 
+
+OPTIONS
+-------
+
+-c::
+       Commit automatically if the patch applied cleanly. It will not
+       commit if any hunks fail to apply or there were other problems.
+
+-p::
+       Be pedantic (paranoid) when applying patches. Invokes patch with 
+       --fuzz=0
+
+-v::
+       Verbose.
+
+EXAMPLES
+--------
+
+Merge one patch into CVS::
++
+------------
+$ export GIT_DIR=~/project/.git
+$ cd ~/project_cvs_checkout
+$ git-cvsexportcommit -v <commit-sha1>
+$ cvs commit -F .mgs <files> 
+------------
+
+Merge pending patches into CVS automatically -- only if you really know what you are doing ::
++
+------------
+$ export GIT_DIR=~/project/.git
+$ cd ~/project_cvs_checkout
+$ git-cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git-cvsexportcommit -c -p -v
+------------
+
+Author
+------
+Written by Martin Langhoff <martin@catalyst.net.nz>
+
+Documentation
+--------------
+Documentation by Martin Langhoff <martin@catalyst.net.nz>
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
new file mode 100644 (file)
index 0000000..dfe86ce
--- /dev/null
@@ -0,0 +1,132 @@
+git-cvsimport(1)
+================
+
+NAME
+----
+git-cvsimport - Import a CVS repository into git
+
+
+SYNOPSIS
+--------
+[verse]
+'git-cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] [-s <subst>]
+             [-p <options-for-cvsps>] [-C <git_repository>] [-i] [-P <file>]
+             [-m] [-M regex] [<CVS_module>]
+
+
+DESCRIPTION
+-----------
+Imports a CVS repository into git. It will either create a new
+repository, or incrementally import into an existing one.
+
+Splitting the CVS log into patch sets is done by 'cvsps'.
+At least version 2.1 is required.
+
+OPTIONS
+-------
+-d <CVSROOT>::
+       The root of the CVS archive. May be local (a simple path) or remote;
+       currently, only the :local:, :ext: and :pserver: access methods 
+       are supported.
+
+-C <target-dir>::
+        The git repository to import to.  If the directory doesn't
+        exist, it will be created.  Default is the current directory.
+
+-i::
+       Import-only: don't perform a checkout after importing.  This option
+       ensures the working directory and index remain untouched and will
+       not create them if they do not exist.
+
+-k::
+       Kill keywords: will extract files with -kk from the CVS archive
+       to avoid noisy changesets. Highly recommended, but off by default
+       to preserve compatibility with early imported trees. 
+
+-u::
+       Convert underscores in tag and branch names to dots.
+
+-o <branch-for-HEAD>::
+       The 'HEAD' branch from CVS is imported to the 'origin' branch within
+       the git repository, as 'HEAD' already has a special meaning for git.
+       Use this option if you want to import into a different branch.
++
+Use '-o master' for continuing an import that was initially done by
+the old cvs2git tool.
+
+-p <options-for-cvsps>::
+       Additional options for cvsps.
+       The options '-u' and '-A' are implicit and should not be used here.
++
+If you need to pass multiple options, separate them with a comma.
+
+-P <cvsps-output-file>::
+       Instead of calling cvsps, read the provided cvsps output file. Useful
+       for debugging or when cvsps is being handled outside cvsimport.
+
+-m::    
+       Attempt to detect merges based on the commit message. This option
+       will enable default regexes that try to capture the name source 
+       branch name from the commit message. 
+
+-M <regex>::
+       Attempt to detect merges based on the commit message with a custom
+       regex. It can be used with -m to also see the default regexes. 
+       You must escape forward slashes. 
+
+-v::
+       Verbosity: let 'cvsimport' report what it is doing.
+
+<CVS_module>::
+       The CVS module you want to import. Relative to <CVSROOT>.
+
+-h::
+       Print a short usage message and exit.
+
+-z <fuzz>::
+        Pass the timestamp fuzz factor to cvsps.
+
+-s <subst>::
+       Substitute the character "/" in branch names with <subst>
+
+-A <author-conv-file>::
+       CVS by default uses the unix username when writing its
+       commit logs. Using this option and an author-conv-file
+       in this format
+
+       exon=Andreas Ericsson <ae@op5.se>
+       spawn=Simon Pawn <spawn@frog-pond.org>
+
+       git-cvsimport will make it appear as those authors had
+       their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly
+       all along.
+
+       For convenience, this data is saved to $GIT_DIR/cvs-authors
+       each time the -A option is provided and read from that same
+       file each time git-cvsimport is run.
+
+       It is not recommended to use this feature if you intend to
+       export changes back to CVS again later with
+       git-link[1]::git-cvsexportcommit.
+
+OUTPUT
+------
+If '-v' is specified, the script reports what it is doing.
+
+Otherwise, success is indicated the Unix way, i.e. by simply exiting with
+a zero exit status.
+
+
+Author
+------
+Written by Matthias Urlichs <smurf@smurf.noris.de>, with help from
+various participants of the git-list <git@vger.kernel.org>.
+
+Documentation
+--------------
+Documentation by Matthias Urlichs <smurf@smurf.noris.de>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
new file mode 100644 (file)
index 0000000..2cc6075
--- /dev/null
@@ -0,0 +1,102 @@
+git-daemon(1)
+=============
+
+NAME
+----
+git-daemon - A really simple server for git repositories.
+
+SYNOPSIS
+--------
+[verse]
+'git-daemon' [--verbose] [--syslog] [--inetd | --port=n] [--export-all]
+             [--timeout=n] [--init-timeout=n] [--strict-paths]
+             [--base-path=path] [--user-path | --user-path=path]
+            [directory...]
+
+DESCRIPTION
+-----------
+A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT"
+aka 9418. It waits for a connection, and will just execute "git-upload-pack"
+when it gets one.
+
+It's careful in that there's a magic request-line that gives the command and
+what directory to upload, and it verifies that the directory is ok.
+
+It verifies that the directory has the magic file "git-daemon-export-ok", and
+it will refuse to export any git directory that hasn't explicitly been marked
+for export this way (unless the '--export-all' parameter is specified). If you
+pass some directory paths as 'git-daemon' arguments, you can further restrict
+the offers to a whitelist comprising of those.
+
+This is ideally suited for read-only updates, ie pulling from git repositories.
+
+OPTIONS
+-------
+--strict-paths::
+       Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
+       "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
+       git-daemon will refuse to start when this option is enabled and no
+       whitelist is specified.
+
+--base-path::
+       Remap all the path requests as relative to the given path.
+       This is sort of "GIT root" - if you run git-daemon with
+       '--base-path=/srv/git' on example.com, then if you later try to pull
+       'git://example.com/hello.git', `git-daemon` will interpret the path
+       as '/srv/git/hello.git'.
+
+--export-all::
+       Allow pulling from all directories that look like GIT repositories
+       (have the 'objects' and 'refs' subdirectories), even if they
+       do not have the 'git-daemon-export-ok' file.
+
+--inetd::
+       Have the server run as an inetd service. Implies --syslog.
+
+--port::
+       Listen on an alternative port.
+
+--init-timeout::
+       Timeout between the moment the connection is established and the
+       client request is received (typically a rather low value, since
+       that should be basically immediate).
+
+--timeout::
+       Timeout for specific client sub-requests. This includes the time
+       it takes for the server to process the sub-request and time spent
+       waiting for next client's request.
+
+--syslog::
+       Log to syslog instead of stderr. Note that this option does not imply
+       --verbose, thus by default only error conditions will be logged.
+
+--user-path, --user-path=path::
+       Allow ~user notation to be used in requests.  When
+       specified with no parameter, requests to
+       git://host/~alice/foo is taken as a request to access
+       'foo' repository in the home directory of user `alice`.
+       If `--user-path=path` is specified, the same request is
+       taken as a request to access `path/foo` repository in
+       the home directory of user `alice`.
+
+--verbose::
+       Log details about the incoming connections and requested files.
+
+<directory>::
+       A directory to add to the whitelist of allowed directories. Unless
+       --strict-paths is specified this will also include subdirectories
+       of each named directory.
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki
+<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
new file mode 100644 (file)
index 0000000..0efe82a
--- /dev/null
@@ -0,0 +1,79 @@
+git-describe(1)
+===============
+
+NAME
+----
+git-describe - Show the most recent tag that is reachable from a commit.
+
+
+SYNOPSIS
+--------
+'git-describe' [--all] [--tags] [--abbrev=<n>] <committish>...
+
+DESCRIPTION
+-----------
+The command finds the most recent tag that is reachable from a
+commit, and if the commit itself is pointed at by the tag, shows
+the tag.  Otherwise, it suffixes the tag name with abbreviated
+object name of the commit.
+
+
+OPTIONS
+-------
+<committish>::
+       The object name of the comittish. 
+
+--all::
+       Instead of using only the annotated tags, use any ref
+       found in `.git/refs/`.
+
+--tags::
+       Instead of using only the annotated tags, use any tag
+       found in `.git/refs/tags`.
+
+--abbrev=<n>::
+       Instead of using the default 8 hexadecimal digits as the
+       abbreviated object name, use <n> digits.
+
+
+EXAMPLES
+--------
+
+With something like git.git current tree, I get:
+
+       [torvalds@g5 git]$ git-describe parent
+       v1.0.4-g2414721b
+
+i.e. the current head of my "parent" branch is based on v1.0.4,
+but since it has a few commits on top of that, it has added the
+git hash of the thing to the end: "-g" + 8-char shorthand for
+the commit `2414721b194453f058079d897d13c4e377f92dc6`.
+
+Doing a "git-describe" on a tag-name will just show the tag name:
+
+       [torvalds@g5 git]$ git-describe v1.0.4
+       v1.0.4
+
+With --all, the command can use branch heads as references, so
+the output shows the reference path as well:
+
+       [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
+       tags/v1.0.0-g975b
+
+       [torvalds@g5 git]$ git describe --all HEAD^
+       heads/lt/describe-g975b
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>, but somewhat
+butchered by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
new file mode 100644 (file)
index 0000000..481b8b3
--- /dev/null
@@ -0,0 +1,58 @@
+git-diff-files(1)
+=================
+
+NAME
+----
+git-diff-files - Compares files in the working tree and the index
+
+
+SYNOPSIS
+--------
+'git-diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...]
+
+DESCRIPTION
+-----------
+Compares the files in the working tree and the index.  When paths
+are specified, compares only those named paths.  Otherwise all
+entries in the index are compared.  The output format is the
+same as "git-diff-index" and "git-diff-tree".
+
+OPTIONS
+-------
+include::diff-options.txt[]
+
+-1 -2 -3 or --base --ours --theirs, and -0::
+       Diff against the "base" version, "our branch" or "their
+       branch" respectively.  With these options, diffs for
+       merged entries are not shown.
++
+The default is to diff against our branch (-2) and the 
+cleanly resolved paths.  The option -0 can be given to
+omit diff output for unmerged entries and just show "Unmerged".
+
+-c,--cc::
+       This compares stage 2 (our branch), stage 3 (their
+       branch) and the working tree file and outputs a combined
+       diff, similar to the way 'diff-tree' shows a merge
+       commit with these flags.
+
+-q::
+       Remain silent even on nonexisting files
+
+Output format
+-------------
+include::diff-format.txt[]
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
new file mode 100644 (file)
index 0000000..5d2096a
--- /dev/null
@@ -0,0 +1,133 @@
+git-diff-index(1)
+=================
+
+NAME
+----
+git-diff-index - Compares content and mode of blobs between the index and repository
+
+
+SYNOPSIS
+--------
+'git-diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...]
+
+DESCRIPTION
+-----------
+Compares the content and mode of the blobs found via a tree
+object with the content of the current index and, optionally
+ignoring the stat state of the file on disk.  When paths are
+specified, compares only those named paths.  Otherwise all
+entries in the index are compared.
+
+OPTIONS
+-------
+include::diff-options.txt[]
+
+<tree-ish>::
+       The id of a tree object to diff against.
+
+--cached::
+       do not consider the on-disk file at all
+
+-m::
+       By default, files recorded in the index but not checked
+       out are reported as deleted.  This flag makes
+       "git-diff-index" say that all non-checked-out files are up
+       to date.
+
+Output format
+-------------
+include::diff-format.txt[]
+
+Operating Modes
+---------------
+You can choose whether you want to trust the index file entirely
+(using the '--cached' flag) or ask the diff logic to show any files
+that don't match the stat state as being "tentatively changed".  Both
+of these operations are very useful indeed.
+
+Cached Mode
+-----------
+If '--cached' is specified, it allows you to ask:
+
+       show me the differences between HEAD and the current index
+       contents (the ones I'd write with a "git-write-tree")
+
+For example, let's say that you have worked on your working directory, updated
+some files in the index and are ready to commit. You want to see exactly
+*what* you are going to commit is without having to write a new tree
+object and compare it that way, and to do that, you just do
+
+       git-diff-index --cached HEAD
+
+Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had
+done an "git-update-index" to make that effective in the index file.
+"git-diff-files" wouldn't show anything at all, since the index file
+matches my working directory. But doing a "git-diff-index" does:
+
+  torvalds@ppc970:~/git> git-diff-index --cached HEAD
+  -100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        commit.c
+  +100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        git-commit.c
+
+You can trivially see that the above is a rename.
+
+In fact, "git-diff-index --cached" *should* always be entirely equivalent to
+actually doing a "git-write-tree" and comparing that. Except this one is much
+nicer for the case where you just want to check where you are.
+
+So doing a "git-diff-index --cached" is basically very useful when you are
+asking yourself "what have I already marked for being committed, and 
+what's the difference to a previous tree".
+
+Non-cached Mode
+---------------
+The "non-cached" mode takes a different approach, and is potentially
+the more useful of the two in that what it does can't be emulated with
+a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
+The non-cached version asks the question:
+
+  show me the differences between HEAD and the currently checked out
+  tree - index contents _and_ files that aren't up-to-date
+
+which is obviously a very useful question too, since that tells you what
+you *could* commit. Again, the output matches the "git-diff-tree -r"
+output to a tee, but with a twist.
+
+The twist is that if some file doesn't match the index, we don't have
+a backing store thing for it, and we use the magic "all-zero" sha1 to
+show that. So let's say that you have edited `kernel/sched.c`, but
+have not actually done a "git-update-index" on it yet - there is no
+"object" associated with the new state, and you get:
+
+  torvalds@ppc970:~/v2.6/linux> git-diff-index HEAD
+  *100644->100664 blob    7476bb......->000000......      kernel/sched.c
+
+ie it shows that the tree has changed, and that `kernel/sched.c` has is
+not up-to-date and may contain new stuff. The all-zero sha1 means that to
+get the real diff, you need to look at the object in the working directory
+directly rather than do an object-to-object diff.
+
+NOTE: As with other commands of this type, "git-diff-index" does not
+actually look at the contents of the file at all. So maybe
+`kernel/sched.c` hasn't actually changed, and it's just that you
+touched it. In either case, it's a note that you need to
+"git-update-index" it to make the index be in sync.
+
+NOTE: You can have a mixture of files show up as "has been updated"
+and "is still dirty in the working directory" together. You can always
+tell which file is in which state, since the "has been updated" ones
+show a valid sha1, and the "not in sync with the index" ones will
+always have the special all-zero sha1.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-diff-stages.txt b/Documentation/git-diff-stages.txt
new file mode 100644 (file)
index 0000000..28c60fc
--- /dev/null
@@ -0,0 +1,40 @@
+git-diff-stages(1)
+==================
+
+NAME
+----
+git-diff-stages - Compares content and mode of blobs between stages in an unmerged index file.
+
+
+SYNOPSIS
+--------
+'git-diff-stages' [<common diff options>] <stage1> <stage2> [<path>...]
+
+DESCRIPTION
+-----------
+Compares the content and mode of the blobs in two stages in an
+unmerged index file.
+
+OPTIONS
+-------
+include::diff-options.txt[]
+
+<stage1>,<stage2>::
+       The stage number to be compared.
+
+Output format
+-------------
+include::diff-format.txt[]
+
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano.
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
new file mode 100644 (file)
index 0000000..674ee61
--- /dev/null
@@ -0,0 +1,158 @@
+git-diff-tree(1)
+================
+
+NAME
+----
+git-diff-tree - Compares the content and mode of blobs found via two tree objects
+
+
+SYNOPSIS
+--------
+[verse]
+'git-diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]
+             [-t] [-r] [-c | --cc] [--root] [<common diff options>]
+             <tree-ish> [<tree-ish>] [<path>...]
+
+DESCRIPTION
+-----------
+Compares the content and mode of the blobs found via two tree objects.
+
+If there is only one <tree-ish> given, the commit is compared with its parents
+(see --stdin below).
+
+Note that "git-diff-tree" can use the tree encapsulated in a commit object.
+
+OPTIONS
+-------
+include::diff-options.txt[]
+
+<tree-ish>::
+       The id of a tree object.
+
+<path>...::
+       If provided, the results are limited to a subset of files
+       matching one of these prefix strings.
+       ie file matches `/^<pattern1>|<pattern2>|.../`
+       Note that this parameter does not provide any wildcard or regexp
+       features.
+
+-r::
+        recurse into sub-trees
+
+-t::
+       show tree entry itself as well as subtrees.  Implies -r.
+
+--root::
+       When '--root' is specified the initial commit will be showed as a big
+       creation event. This is equivalent to a diff against the NULL tree.
+
+--stdin::
+       When '--stdin' is specified, the command does not take
+       <tree-ish> arguments from the command line.  Instead, it
+       reads either one <commit> or a pair of <tree-ish>
+       separated with a single space from its standard input.
++
+When a single commit is given on one line of such input, it compares
+the commit with its parents.  The following flags further affects its
+behaviour.  This does not apply to the case where two <tree-ish>
+separated with a single space are given.
+
+-m::
+       By default, "git-diff-tree --stdin" does not show
+       differences for merge commits.  With this flag, it shows
+       differences to that commit from all of its parents.
+
+-s::
+       By default, "git-diff-tree --stdin" shows differences,
+       either in machine-readable form (without '-p') or in patch
+       form (with '-p').  This output can be suppressed.  It is
+       only useful with '-v' flag.
+
+-v::
+       This flag causes "git-diff-tree --stdin" to also show
+       the commit message before the differences.
+
+--pretty[=(raw|medium|short)]::
+       This is used to control "pretty printing" format of the
+       commit message.  Without "=<style>", it defaults to
+       medium.
+
+--no-commit-id::
+       git-diff-tree outputs a line with the commit ID when
+       applicable.  This flag suppressed the commit ID output.
+
+-c,--cc::
+       These flags change the way a merge commit is displayed
+       (which means it is useful only when the command is given
+       one <tree-ish>, or '--stdin').  It shows the differences
+       from each of the parents to the merge result
+       simultaneously, instead of showing pairwise diff between
+       a parent and the result one at a time, which '-m' option
+       output does.  '--cc' further compresses the output by
+       omiting hunks that show differences from only one
+       parent, or show the same change from all but one parent
+       for an Octopus merge.  When this optimization makes all
+       hunks disappear, the commit itself and the commit log
+       message is not shown, just like any other "empty diff" cases.
+
+
+Limiting Output
+---------------
+If you're only interested in differences in a subset of files, for
+example some architecture-specific files, you might do:
+
+       git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
+
+and it will only show you what changed in those two directories.
+
+Or if you are searching for what changed in just `kernel/sched.c`, just do
+
+       git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
+
+and it will ignore all differences to other files.
+
+The pattern is always the prefix, and is matched exactly.  There are no
+wildcards.  Even stricter, it has to match a complete path component.
+I.e. "foo" does not pick up `foobar.h`.  "foo" does match `foo/bar.h`
+so it can be used to name subdirectories.
+
+An example of normal usage is:
+
+  torvalds@ppc970:~/git> git-diff-tree 5319e4......
+  *100664->100664 blob    ac348b.......->a01513.......      git-fsck-objects.c
+
+which tells you that the last commit changed just one file (it's from
+this one:
+
+-----------------------------------------------------------------------------
+commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
+tree 5319e4d609cdd282069cc4dce33c1db559539b03
+parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
+author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
+committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
+
+Make "git-fsck-objects" print out all the root commits it finds.
+
+Once I do the reference tracking, I'll also make it print out all the
+HEAD commits it finds, which is even more interesting.
+-----------------------------------------------------------------------------
+
+in case you care).
+
+Output format
+-------------
+include::diff-format.txt[]
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
new file mode 100644 (file)
index 0000000..ca41634
--- /dev/null
@@ -0,0 +1,116 @@
+git-diff(1)
+===========
+
+NAME
+----
+git-diff - Show changes between commits, commit and working tree, etc.
+
+
+SYNOPSIS
+--------
+'git-diff' [ --diff-options ] <ent>{0,2} [<path>...]
+
+DESCRIPTION
+-----------
+Show changes between two ents, an ent and the working tree, an
+ent and the index file, or the index file and the working tree.
+The combination of what is compared with what is determined by
+the number of ents given to the command.
+
+* When no <ent> is given, the working tree and the index
+  file is compared, using `git-diff-files`.
+
+* When one <ent> is given, the working tree and the named
+  tree is compared, using `git-diff-index`.  The option
+  `--cached` can be given to compare the index file and
+  the named tree.
+
+* When two <ent>s are given, these two trees are compared
+  using `git-diff-tree`.
+
+OPTIONS
+-------
+--diff-options::
+       '--diff-options' are passed to the `git-diff-files`,
+       `git-diff-index`, and `git-diff-tree` commands.  See the
+       documentation for these commands for description.
+
+<path>...::
+       The <path> arguments are also passed to `git-diff-\*`
+       commands.
+
+
+EXAMPLES
+--------
+
+Various ways to check your working tree::
++
+------------
+$ git diff <1>
+$ git diff --cached <2>
+$ git diff HEAD <3>
+
+<1> changes in the working tree since your last git-update-index.
+<2> changes between the index and your last commit; what you
+would be committing if you run "git commit" without "-a" option.
+<3> changes in the working tree since your last commit; what you
+would be committing if you run "git commit -a"
+------------
+
+Comparing with arbitrary commits::
++
+------------
+$ git diff test <1>
+$ git diff HEAD -- ./test <2>
+$ git diff HEAD^ HEAD <3>
+
+<1> instead of using the tip of the current branch, compare with the
+tip of "test" branch.
+<2> instead of comparing with the tip of "test" branch, compare with
+the tip of the current branch, but limit the comparison to the
+file "test".
+<3> compare the version before the last commit and the last commit.
+------------
+
+
+Limiting the diff output::
++
+------------
+$ git diff --diff-filter=MRC <1>
+$ git diff --name-status -r <2>
+$ git diff arch/i386 include/asm-i386 <3>
+
+<1> show only modification, rename and copy, but not addition
+nor deletion.
+<2> show only names and the nature of change, but not actual
+diff output.  --name-status disables usual patch generation
+which in turn also disables recursive behaviour, so without -r
+you would only see the directory name if there is a change in a
+file in a subdirectory.
+<3> limit diff output to named subtrees.
+------------
+
+Munging the diff output::
++
+------------
+$ git diff --find-copies-harder -B -C <1>
+$ git diff -R <2>
+
+<1> spend extra cycles to find renames, copies and complete
+rewrites (very expensive).
+<2> output diff in reverse.
+------------
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
new file mode 100644 (file)
index 0000000..b507e9b
--- /dev/null
@@ -0,0 +1,73 @@
+git-fetch-pack(1)
+=================
+
+NAME
+----
+git-fetch-pack - Receive missing objects from another repository.
+
+
+SYNOPSIS
+--------
+git-fetch-pack [-q] [-k] [--exec=<git-upload-pack>] [<host>:]<directory> [<refs>...]
+
+DESCRIPTION
+-----------
+Invokes 'git-upload-pack' on a potentially remote repository,
+and asks it to send objects missing from this repository, to
+update the named heads.  The list of commits available locally
+is found out by scanning local $GIT_DIR/refs/ and sent to
+'git-upload-pack' running on the other end.
+
+This command degenerates to download everything to complete the
+asked refs from the remote side when the local side does not
+have a common ancestor commit.
+
+
+OPTIONS
+-------
+-q::
+       Pass '-q' flag to 'git-unpack-objects'; this makes the
+       cloning process less verbose.
+
+-k::
+       Do not invoke 'git-unpack-objects' on received data, but
+       create a single packfile out of it instead, and store it
+       in the object database.
+
+--exec=<git-upload-pack>::
+       Use this to specify the path to 'git-upload-pack' on the
+       remote side, if is not found on your $PATH.
+       Installations of sshd ignores the user's environment
+       setup scripts for login shells (e.g. .bash_profile) and
+       your privately installed git may not be found on the system
+       default $PATH.  Another workaround suggested is to set
+       up your $PATH in ".bashrc", but this flag is for people
+       who do not want to pay the overhead for non-interactive
+       shells by having a lean .bashrc file (they set most of
+       the things up in .bash_profile).
+
+<host>::
+       A remote host that houses the repository.  When this
+       part is specified, 'git-upload-pack' is invoked via
+       ssh.
+
+<directory>::
+       The repository to sync from.
+
+<refs>...::
+       The remote heads to update from. This is relative to
+       $GIT_DIR (e.g. "HEAD", "refs/heads/master").  When
+       unspecified, update from all heads the remote side has.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano.
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
new file mode 100644 (file)
index 0000000..a67dc34
--- /dev/null
@@ -0,0 +1,48 @@
+git-fetch(1)
+============
+
+NAME
+----
+git-fetch - Download objects and a head from another repository.
+
+
+SYNOPSIS
+--------
+'git-fetch' <options> <repository> <refspec>...
+
+
+DESCRIPTION
+-----------
+Fetches named heads or tags from another repository, along with
+the objects necessary to complete them.
+
+The ref names and their object names of fetched refs are stored
+in `.git/FETCH_HEAD`.  This information is left for a later merge
+operation done by "git merge".
+
+
+OPTIONS
+-------
+include::fetch-options.txt[]
+
+include::pull-fetch-param.txt[]
+
+include::urls.txt[]
+
+SEE ALSO
+--------
+gitlink:git-pull[1]
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org> and
+Junio C Hamano <junkio@cox.net>
+
+Documentation
+-------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt
new file mode 100644 (file)
index 0000000..a70eb39
--- /dev/null
@@ -0,0 +1,39 @@
+git-fmt-merge-msg(1)
+====================
+
+NAME
+----
+git-fmt-merge-msg - Produce a merge commit message
+
+
+SYNOPSIS
+--------
+'git-fmt-merge-msg' <$GIT_DIR/FETCH_HEAD
+
+DESCRIPTION
+-----------
+Takes the list of merged objects on stdin and produces a suitable
+commit message to be used for the merge commit, usually to be
+passed as the '<merge-message>' argument of `git-merge`.
+
+This script is intended mostly for internal use by scripts
+automatically invoking `git-merge`.
+
+
+SEE ALSO
+--------
+gitlink:git-merge[1]
+
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
new file mode 100644 (file)
index 0000000..47705de
--- /dev/null
@@ -0,0 +1,115 @@
+git-format-patch(1)
+===================
+
+NAME
+----
+git-format-patch - Prepare patches for e-mail submission.
+
+
+SYNOPSIS
+--------
+[verse]
+'git-format-patch' [-n | -k] [-o <dir> | --stdout] [-s] [-c] [--mbox]
+                [--diff-options] <his> [<mine>]
+
+DESCRIPTION
+-----------
+Prepare each commit with its patch since <mine> head forked from
+<his> head, one file per patch, for e-mail submission.  Each
+output file is numbered sequentially from 1, and uses the first
+line of the commit message (massaged for pathname safety) as the
+filename.
+
+When -o is specified, output files are created in that
+directory; otherwise in the current working directory.
+
+When -n is specified, instead of "[PATCH] Subject", the first
+line is formatted as "[PATCH N/M] Subject", unless you have only
+one patch.
+
+When --mbox is specified, the output is formatted to resemble
+UNIX mailbox format, and can be concatenated together for
+processing with applymbox.
+
+
+OPTIONS
+-------
+-o|--output-directory <dir>::
+       Use <dir> to store the resulting files, instead of the
+       current working directory.
+
+-n|--numbered::
+       Name output in '[PATCH n/m]' format.
+
+-k|--keep-subject::
+       Do not strip/add '[PATCH]' from the first line of the
+       commit log message.
+
+-a|--author, -d|--date::
+       Output From: and Date: headers for commits made by
+       yourself as well.  Usually these are output only for
+       commits made by people other than yourself.
+
+-s|--signoff::
+       Add `Signed-off-by:` line to the commit message, using
+       the committer identity of yourself.
+
+-c|--check::
+        Display suspicious lines in the patch.  The definition
+        of 'suspicious lines' is currently the lines that has
+        trailing whitespaces, and the lines whose indentation
+        has a SP character immediately followed by a TAB
+        character.
+
+-m|--mbox::
+       Format the output files for closer to mbox format by
+       adding a phony Unix "From " line, so they can be
+       concatenated together and fed to `git-applymbox`.
+       Implies --author and --date.
+
+--stdout::
+       This flag generates the mbox formatted output to the
+       standard output, instead of saving them into a file per
+       patch and implies --mbox.
+
+
+EXAMPLES
+--------
+
+git-format-patch -k --stdout R1..R2 | git-am -3 -k::
+       Extract commits between revisions R1 and R2, and apply
+       them on top of the current branch using `git-am` to
+       cherry-pick them.
+
+git-format-patch origin::
+       Extract commits the current branch accumulated since it
+       pulled from origin the last time in a patch form for
+       e-mail submission.
+
+git-format-patch -M -B origin::
+       The same as the previous one, except detect and handle
+       renames and complete rewrites intelligently to produce
+       renaming patch.  A renaming patch reduces the amount of
+       text output, and generally makes it easier to review
+       it.  Note that the "patch" program does not understand
+       renaming patch well, so use it only when you know the
+       recipient uses git to apply your patch.
+
+
+See Also
+--------
+gitlink:git-am[1], gitlink:git-send-email[1]
+
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt
new file mode 100644 (file)
index 0000000..387b435
--- /dev/null
@@ -0,0 +1,146 @@
+git-fsck-objects(1)
+===================
+
+NAME
+----
+git-fsck-objects - Verifies the connectivity and validity of the objects in the database
+
+
+SYNOPSIS
+--------
+[verse]
+'git-fsck-objects' [--tags] [--root] [--unreachable] [--cache]
+                [--standalone | --full] [--strict] [<object>*]
+
+DESCRIPTION
+-----------
+Verifies the connectivity and validity of the objects in the database.
+
+OPTIONS
+-------
+<object>::
+       An object to treat as the head of an unreachability trace.
++
+If no objects are given, git-fsck-objects defaults to using the
+index file and all SHA1 references in .git/refs/* as heads.
+
+--unreachable::
+       Print out objects that exist but that aren't readable from any
+       of the reference nodes.
+
+--root::
+       Report root nodes.
+
+--tags::
+       Report tags.
+
+--cache::
+       Consider any object recorded in the index also as a head node for
+       an unreachability trace.
+
+--standalone::
+       Limit checks to the contents of GIT_OBJECT_DIRECTORY
+       ($GIT_DIR/objects), making sure that it is consistent and
+       complete without referring to objects found in alternate
+       object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES,
+       nor packed git archives found in $GIT_DIR/objects/pack;
+       cannot be used with --full.
+
+--full::
+       Check not just objects in GIT_OBJECT_DIRECTORY
+       ($GIT_DIR/objects), but also the ones found in alternate
+       object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES,
+       and in packed git archives found in $GIT_DIR/objects/pack
+       and corresponding pack subdirectories in alternate
+       object pools; cannot be used with --standalone.
+
+--strict::
+       Enable more strict checking, namely to catch a file mode
+       recorded with g+w bit set, which was created by older
+       versions of git.  Existing repositories, including the
+       Linux kernel, git itself, and sparse repository have old
+       objects that triggers this check, but it is recommended
+       to check new projects with this flag.
+
+It tests SHA1 and general object sanity, and it does full tracking of
+the resulting reachability and everything else. It prints out any
+corruption it finds (missing or bad objects), and if you use the
+'--unreachable' flag it will also print out objects that exist but
+that aren't readable from any of the specified head nodes.
+
+So for example
+
+       git-fsck-objects --unreachable HEAD $(cat .git/refs/heads/*)
+
+will do quite a _lot_ of verification on the tree. There are a few
+extra validity tests to be added (make sure that tree objects are
+sorted properly etc), but on the whole if "git-fsck-objects" is happy, you
+do have a valid tree.
+
+Any corrupt objects you will have to find in backups or other archives
+(ie you can just remove them and do an "rsync" with some other site in
+the hopes that somebody else has the object you have corrupted).
+
+Of course, "valid tree" doesn't mean that it wasn't generated by some
+evil person, and the end result might be crap. git is a revision
+tracking system, not a quality assurance system ;)
+
+Extracted Diagnostics
+---------------------
+
+expect dangling commits - potential heads - due to lack of head information::
+       You haven't specified any nodes as heads so it won't be
+       possible to differentiate between un-parented commits and
+       root nodes.
+
+missing sha1 directory '<dir>'::
+       The directory holding the sha1 objects is missing.
+
+unreachable <type> <object>::
+       The <type> object <object>, isn't actually referred to directly
+       or indirectly in any of the trees or commits seen. This can
+       mean that there's another root node that you're not specifying
+       or that the tree is corrupt. If you haven't missed a root node
+       then you might as well delete unreachable nodes since they
+       can't be used.
+
+missing <type> <object>::
+       The <type> object <object>, is referred to but isn't present in
+       the database.
+
+dangling <type> <object>::
+       The <type> object <object>, is present in the database but never
+       'directly' used. A dangling commit could be a root node.
+
+warning: git-fsck-objects: tree <tree> has full pathnames in it::
+       And it shouldn't...
+
+sha1 mismatch <object>::
+       The database has an object who's sha1 doesn't match the
+       database value.
+       This indicates a serious data integrity problem.
+
+Environment Variables
+---------------------
+
+GIT_OBJECT_DIRECTORY::
+       used to specify the object database root (usually $GIT_DIR/objects)
+
+GIT_INDEX_FILE::
+       used to specify the index file of the index
+
+GIT_ALTERNATE_OBJECT_DIRECTORIES::
+       used to specify additional object database roots (usually unset)
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt
new file mode 100644 (file)
index 0000000..30b1fbf
--- /dev/null
@@ -0,0 +1,37 @@
+git-get-tar-commit-id(1)
+========================
+
+NAME
+----
+git-get-tar-commit-id - Extract commit ID from an archive created using git-tar-tree.
+
+
+SYNOPSIS
+--------
+'git-get-tar-commit-id' < <tarfile>
+
+
+DESCRIPTION
+-----------
+Acts as a filter, extracting the commit ID stored in archives created by
+git-tar-tree.  It reads only the first 1024 bytes of input, thus its
+runtime is not influenced by the size of <tarfile> very much.
+
+If no commit ID is found, git-get-tar-commit-id quietly exists with a
+return code of 1.  This can happen if <tarfile> had not been created
+using git-tar-tree or if the first parameter of git-tar-tree had been
+a tree ID instead of a commit ID or tag.
+
+
+Author
+------
+Written by Rene Scharfe <rene.scharfe@lsrfire.ath.cx>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
new file mode 100644 (file)
index 0000000..bf4b592
--- /dev/null
@@ -0,0 +1,56 @@
+git-grep(1)
+===========
+
+NAME
+----
+git-grep - print lines matching a pattern
+
+
+SYNOPSIS
+--------
+'git-grep' [<option>...] [-e] <pattern> [--] [<path>...]
+
+DESCRIPTION
+-----------
+Searches list of files `git-ls-files` produces for lines
+containing a match to the given pattern.
+
+
+OPTIONS
+-------
+`--`::
+       Signals the end of options; the rest of the parameters
+       are <path> limiters.
+
+<option>...::
+       Either an option to pass to `grep` or `git-ls-files`.
+
+       The following are the specific `git-ls-files` options
+       that may be given: `-o`, `--cached`, `--deleted`, `--others`,
+       `--killed`, `--ignored`, `--modified`, `--exclude=*`,
+       `--exclude-from=*`, and `--exclude-per-directory=*`.
+
+       All other options will be passed to `grep`.
+
+<pattern>::
+       The pattern to look for.  The first non option is taken
+       as the pattern; if your pattern begins with a dash, use
+       `-e <pattern>`.
+
+<path>...::
+       Optional paths to limit the set of files to be searched;
+       passed to `git-ls-files`.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
new file mode 100644 (file)
index 0000000..0924931
--- /dev/null
@@ -0,0 +1,46 @@
+git-hash-object(1)
+==================
+
+NAME
+----
+git-hash-object - Computes object ID and optionally creates a blob from a file.
+
+
+SYNOPSIS
+--------
+'git-hash-object' [-t <type>] [-w] [--stdin] [--] <file>...
+
+DESCRIPTION
+-----------
+Computes the object ID value for an object with specified type
+with the contents of the named file (which can be outside of the
+work tree), and optionally writes the resulting object into the
+object database.  Reports its object ID to its standard output.
+This is used by "git-cvsimport" to update the index
+without modifying files in the work tree.  When <type> is not
+specified, it defaults to "blob". 
+
+OPTIONS
+-------
+
+-t <type>::
+       Specify the type (default: "blob").
+
+-w::
+       Actually write the object into the object database.
+
+--stdin::
+       Read the object from standard input instead of from a file.
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt
new file mode 100644 (file)
index 0000000..bc1a132
--- /dev/null
@@ -0,0 +1,47 @@
+git-http-fetch(1)
+=================
+
+NAME
+----
+git-http-fetch - downloads a remote git repository via HTTP
+
+
+SYNOPSIS
+--------
+'git-http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] <commit> <url>
+
+DESCRIPTION
+-----------
+Downloads a remote git repository via HTTP.
+
+OPTIONS
+-------
+commit-id::
+        Either the hash or the filename under [URL]/refs/ to
+        pull.
+
+-c::
+       Get the commit objects.
+-t::
+       Get trees associated with the commit objects.
+-a::
+       Get all the objects.
+-v::
+       Report what is downloaded.
+
+-w <filename>::
+        Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on
+        the local end after the transfer is complete.
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt
new file mode 100644 (file)
index 0000000..c7066d6
--- /dev/null
@@ -0,0 +1,89 @@
+git-http-push(1)
+================
+
+NAME
+----
+git-http-push - Push missing objects using HTTP/DAV.
+
+
+SYNOPSIS
+--------
+'git-http-push' [--complete] [--force] [--verbose] <url> <ref> [<ref>...]
+
+DESCRIPTION
+-----------
+Sends missing objects to remote repository, and updates the
+remote branch.
+
+
+OPTIONS
+-------
+--complete::
+       Do not assume that the remote repository is complete in its
+       current state, and verify all objects in the entire local
+       ref's history exist in the remote repository.
+
+--force::
+       Usually, the command refuses to update a remote ref that
+       is not an ancestor of the local ref used to overwrite it.
+       This flag disables the check.  What this means is that
+       the remote repository can lose commits; use it with
+       care.
+
+--verbose::
+       Report the list of objects being walked locally and the
+       list of objects successfully sent to the remote repository.
+
+<ref>...:
+       The remote refs to update.
+
+
+Specifying the Refs
+-------------------
+
+A '<ref>' specification can be either a single pattern, or a pair
+of such patterns separated by a colon ":" (this means that a ref name
+cannot have a colon in it).  A single pattern '<name>' is just a 
+shorthand for '<name>:<name>'.
+
+Each pattern pair consists of the source side (before the colon)
+and the destination side (after the colon).  The ref to be
+pushed is determined by finding a match that matches the source
+side, and where it is pushed is determined by using the
+destination side.
+
+ - It is an error if <src> does not match exactly one of the
+   local refs.
+
+ - If <dst> does not match any remote ref, either
+
+   * it has to start with "refs/"; <dst> is used as the
+     destination literally in this case.
+
+   * <src> == <dst> and the ref that matched the <src> must not
+     exist in the set of remote refs; the ref matched <src>
+     locally is used as the name of the destination.
+
+Without '--force', the <src> ref is stored at the remote only if
+<dst> does not exist, or <dst> is a proper subset (i.e. an
+ancestor) of <src>.  This check, known as "fast forward check",
+is performed in order to avoid accidentally overwriting the
+remote ref and lose other peoples' commits from there.
+
+With '--force', the fast forward check is disabled for all refs.
+
+Optionally, a <ref> parameter can be prefixed with a plus '+' sign
+to disable the fast-forward check only on that ref.
+
+
+Author
+------
+Written by Nick Hengeveld <nickh@reactrix.com>
+
+Documentation
+--------------
+Documentation by Nick Hengeveld
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
new file mode 100644 (file)
index 0000000..71ce557
--- /dev/null
@@ -0,0 +1,44 @@
+git-index-pack(1)
+=================
+
+NAME
+----
+git-index-pack - Build pack index file for an existing packed archive
+
+
+SYNOPSIS
+--------
+'git-index-pack' [-o <index-file>] <pack-file>
+
+
+DESCRIPTION
+-----------
+Reads a packed archive (.pack) from the specified file, and
+builds a pack index file (.idx) for it.  The packed archive
+together with the pack index can then be placed in the
+objects/pack/ directory of a git repository.
+
+
+OPTIONS
+-------
+-o <index-file>::
+       Write the generated pack index into the specified
+       file.  Without this option the name of pack index
+       file is constructed from the name of packed archive
+       file by replacing .pack with .idx (and the program
+       fails if the name of packed archive does not end
+       with .pack).
+
+
+Author
+------
+Written by Sergey Vlasov <vsu@altlinux.ru>
+
+Documentation
+-------------
+Documentation by Sergey Vlasov
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt
new file mode 100644 (file)
index 0000000..ea4d849
--- /dev/null
@@ -0,0 +1,74 @@
+git-init-db(1)
+==============
+
+NAME
+----
+git-init-db - Creates an empty git repository
+
+
+SYNOPSIS
+--------
+'git-init-db' [--template=<template_directory>] [--shared]
+
+
+OPTIONS
+-------
+--template=<template_directory>::
+       Provide the directory in from which templates will be used.
+
+--shared::
+       Specify that the git repository is to be shared amongst several users.
+
+
+DESCRIPTION
+-----------
+This simply creates an empty git repository - basically a `.git` directory
+and `.git/object/??/`, `.git/refs/heads` and `.git/refs/tags` directories,
+and links `.git/HEAD` symbolically to `.git/refs/heads/master`.
+
+If the `$GIT_DIR` environment variable is set then it specifies a path
+to use instead of `./.git` for the base of the repository.
+
+If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY`
+environment variable then the sha1 directories are created underneath -
+otherwise the default `$GIT_DIR/objects` directory is used.
+
+A shared repository allows users belonging to the same group to push into that
+repository. When specifying `--shared` the config variable "core.sharedRepository" 
+is set to 'true' so that directories under `$GIT_DIR` are made group writable
+(and g+sx, since the git group may be not the primary group of all users).
+
+
+Running `git-init-db` in an existing repository is safe. It will not overwrite
+things that are already there. The primary reason for rerunning `git-init-db`
+is to pick up newly added templates.
+
+
+
+EXAMPLES
+--------
+
+Start a new git repository for an existing code base::
++
+----------------
+$ cd /path/to/my/codebase
+$ git-init-db <1>
+$ git-add . <2>
+
+<1> prepare /path/to/my/codebase/.git directory
+<2> add all existing file to the index
+----------------
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-local-fetch.txt b/Documentation/git-local-fetch.txt
new file mode 100644 (file)
index 0000000..87abec1
--- /dev/null
@@ -0,0 +1,43 @@
+git-local-fetch(1)
+==================
+
+NAME
+----
+git-local-fetch - Duplicates another git repository on a local system
+
+
+SYNOPSIS
+--------
+'git-local-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [-l] [-s] [-n] commit-id path
+
+DESCRIPTION
+-----------
+Duplicates another git repository on a local system.
+
+OPTIONS
+-------
+-c::
+       Get the commit objects.
+-t::
+       Get trees associated with the commit objects.
+-a::
+       Get all the objects.
+-v::
+       Report what is downloaded.
+
+-w <filename>::
+        Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on
+        the local end after the transfer is complete.
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
new file mode 100644 (file)
index 0000000..e995d1b
--- /dev/null
@@ -0,0 +1,62 @@
+git-log(1)
+==========
+
+NAME
+----
+git-log - Show commit logs
+
+
+SYNOPSIS
+--------
+'git-log' <option>...
+
+DESCRIPTION
+-----------
+Shows the commit logs.  This command internally invokes
+'git-rev-list', and the command line options are passed to that
+command.
+
+This manual page describes only the most frequently used options.
+
+OPTIONS
+-------
+--pretty=<format>::
+       Controls the way the commit log is formatted.
+
+--max-count=<n>::
+       Limits the number of commits to show.
+
+<since>..<until>::
+       Show only commits between the named two commits.
+
+
+Examples
+--------
+git log --no-merges::
+
+       Show the whole commit history, but skip any merges
+
+git log v2.6.12.. include/scsi drivers/scsi::
+
+       Show all commits since version 'v2.6.12' that changed any file
+       in the include/scsi or drivers/scsi subdirectories
+
+git log --since="2 weeks ago" -- gitk::
+
+       Show the changes during the last two weeks to the file 'gitk'.
+       The "--" is necessary to avoid confusion with the *branch* named
+       'gitk'
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt
new file mode 100644 (file)
index 0000000..03156f2
--- /dev/null
@@ -0,0 +1,78 @@
+git-lost-found(1)
+=================
+
+NAME
+----
+git-lost-found - Recover lost refs that luckily have not yet been pruned.
+
+SYNOPSIS
+--------
+'git-lost-found'
+
+DESCRIPTION
+-----------
+Finds dangling commits and tags from the object database, and
+creates refs to them in .git/lost-found/ directory.  Commits and
+tags that dereference to commits go to .git/lost-found/commit
+and others are stored in .git/lost-found/other directory.
+
+
+OUTPUT
+------
+One line description from the commit and tag found along with
+their object name are printed on the standard output.
+
+
+EXAMPLE
+-------
+
+Suppose you run 'git tag -f' and mistyped the tag to overwrite.
+The ref to your tag is overwritten, but until you run 'git
+prune', it is still there.
+
+------------
+$ git lost-found
+[1ef2b196d909eed523d4f3c9bf54b78cdd6843c6] GIT 0.99.9c
+...
+------------
+
+Also you can use gitk to browse how they relate to each other
+and existing (probably old) tags.
+
+------------
+$ gitk $(cd .git/lost-found/commit && echo ??*)
+------------
+
+After making sure that it is the object you are looking for, you
+can reconnect it to your regular .git/refs hierarchy.
+
+------------
+$ git cat-file -t 1ef2b196
+tag
+$ git cat-file tag 1ef2b196
+object fa41bbce8e38c67a218415de6cfa510c7e50032a
+type commit
+tag v0.99.9c
+tagger Junio C Hamano <junkio@cox.net> 1131059594 -0800
+
+GIT 0.99.9c
+
+This contains the following changes from the "master" branch, since
+...
+$ git update-ref refs/tags/not-lost-anymore 1ef2b196
+$ git rev-parse not-lost-anymore
+1ef2b196d909eed523d4f3c9bf54b78cdd6843c6
+------------
+
+Author
+------
+Written by Junio C Hamano 濱野 純 <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
new file mode 100644 (file)
index 0000000..e433407
--- /dev/null
@@ -0,0 +1,224 @@
+git-ls-files(1)
+===============
+
+NAME
+----
+git-ls-files - Information about files in the index/working directory
+
+
+SYNOPSIS
+--------
+'git-ls-files' [-z] [-t]
+               (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
+               (-[c|d|o|i|s|u|k|m])\*
+               [-x <pattern>|--exclude=<pattern>]
+               [-X <file>|--exclude-from=<file>]
+               [--exclude-per-directory=<file>] 
+               [--full-name] [--] [<file>]\*
+
+DESCRIPTION
+-----------
+This merges the file listing in the directory cache index with the
+actual working directory list, and shows different combinations of the
+two.
+
+One or more of the options below may be used to determine the files
+shown:
+
+OPTIONS
+-------
+-c|--cached::
+       Show cached files in the output (default)
+
+-d|--deleted::
+       Show deleted files in the output
+
+-m|--modified::
+       Show modified files in the output
+
+-o|--others::
+       Show other files in the output
+
+-i|--ignored::
+       Show ignored files in the output
+       Note the this also reverses any exclude list present.
+
+-s|--stage::
+       Show stage files in the output
+
+--directory::
+       If a whole directory is classified as "other", show just its
+       name (with a trailing slash) and not its whole contents.
+
+-u|--unmerged::
+       Show unmerged files in the output (forces --stage)
+
+-k|--killed::
+       Show files on the filesystem that need to be removed due
+       to file/directory conflicts for checkout-index to
+       succeed.
+
+-z::
+       \0 line termination on output.
+
+-x|--exclude=<pattern>::
+       Skips files matching pattern.
+       Note that pattern is a shell wildcard pattern.
+
+-X|--exclude-from=<file>::
+       exclude patterns are read from <file>; 1 per line.
+
+--exclude-per-directory=<file>::
+       read additional exclude patterns that apply only to the
+       directory and its subdirectories in <file>.
+
+-t::
+       Identify the file status with the following tags (followed by
+       a space) at the start of each line:
+       H::     cached
+       M::     unmerged
+       R::     removed/deleted
+       C::     modified/changed
+       K::     to be killed
+       ?       other
+
+--full-name::
+       When run from a subdirectory, the command usually
+       outputs paths relative to the current directory.  This
+       option forces paths to be output relative to the project
+       top directory.
+
+--::
+       Do not interpret any more arguments as options.
+
+<file>::
+       Files to show. If no files are given all files which match the other
+       specified criteria are shown.
+
+Output
+------
+show files just outputs the filename unless '--stage' is specified in
+which case it outputs:
+
+        [<tag> ]<mode> <object> <stage> <file>
+
+"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
+detailed information on unmerged paths.
+
+For an unmerged path, instead of recording a single mode/SHA1 pair,
+the dircache records up to three such pairs; one from tree O in stage
+1, A in stage 2, and B in stage 3.  This information can be used by
+the user (or the porcelain) to see what should eventually be recorded at the
+path. (see git-read-tree for more information on state)
+
+When `-z` option is not used, TAB, LF, and backslash characters
+in pathnames are represented as `\t`, `\n`, and `\\`,
+respectively.
+
+
+Exclude Patterns
+----------------
+
+'git-ls-files' can use a list of "exclude patterns" when
+traversing the directory tree and finding files to show when the
+flags --others or --ignored are specified.
+
+These exclude patterns come from these places:
+
+  1. command line flag --exclude=<pattern> specifies a single
+     pattern.
+
+  2. command line flag --exclude-from=<file> specifies a list of
+     patterns stored in a file.
+
+  3. command line flag --exclude-per-directory=<name> specifies
+     a name of the file in each directory 'git-ls-files'
+     examines, and if exists, its contents are used as an
+     additional list of patterns.
+
+An exclude pattern file used by (2) and (3) contains one pattern
+per line.  A line that starts with a '#' can be used as comment
+for readability.
+
+There are three lists of patterns that are in effect at a given
+time.  They are built and ordered in the following way:
+
+ * --exclude=<pattern> from the command line; patterns are
+   ordered in the same order as they appear on the command line.
+
+ * lines read from --exclude-from=<file>; patterns are ordered
+   in the same order as they appear in the file.
+
+ * When --exclude-per-directory=<name> is specified, upon
+   entering a directory that has such a file, its contents are
+   appended at the end of the current "list of patterns".  They
+   are popped off when leaving the directory.
+
+Each pattern in the pattern list specifies "a match pattern" and
+optionally the fate; either a file that matches the pattern is
+considered excluded or included.  A filename is matched against
+the patterns in the three lists; the --exclude-from list is
+checked first, then the --exclude-per-directory list, and then
+finally the --exclude list. The last match determines its fate.
+If there is no match in the three lists, the fate is "included".
+
+A pattern specified on the command line with --exclude or read
+from the file specified with --exclude-from is relative to the
+top of the directory tree.  A pattern read from a file specified
+by --exclude-per-directory is relative to the directory that the
+pattern file appears in.
+
+An exclude pattern is of the following format:
+
+ - an optional prefix '!' which means that the fate this pattern
+   specifies is "include", not the usual "exclude"; the
+   remainder of the pattern string is interpreted according to
+   the following rules.
+
+ - if it does not contain a slash '/', it is a shell glob
+   pattern and used to match against the filename without
+   leading directories (i.e. the same way as the current
+   implementation).
+
+ - otherwise, it is a shell glob pattern, suitable for
+   consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
+   slash in the pattern must match a slash in the pathname.
+   "Documentation/\*.html" matches "Documentation/git.html" but
+   not "ppc/ppc.html".  As a natural exception, "/*.c" matches
+   "cat-file.c" but not "mozilla-sha1/sha1.c".
+
+An example:
+
+--------------------------------------------------------------
+    $ cat .git/ignore
+    # ignore objects and archives, anywhere in the tree.
+    *.[oa]
+    $ cat Documentation/.gitignore
+    # ignore generated html files,
+    *.html
+    # except foo.html which is maintained by hand
+    !foo.html
+    $ git-ls-files --ignored \
+        --exclude='Documentation/*.[0-9]' \
+        --exclude-from=.git/ignore \
+        --exclude-per-directory=.gitignore
+--------------------------------------------------------------
+
+
+See Also
+--------
+gitlink:git-read-tree[1]
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
new file mode 100644 (file)
index 0000000..66fe60f
--- /dev/null
@@ -0,0 +1,63 @@
+git-ls-remote(1)
+================
+
+NAME
+----
+git-ls-remote - Look at references other repository has.
+
+
+SYNOPSIS
+--------
+'git-ls-remote' [--heads] [--tags] <repository> <refs>...
+
+DESCRIPTION
+-----------
+Displays the references other repository has.
+
+
+OPTIONS
+-------
+-h|--heads, -t|--tags::
+       Limit to only refs/heads and refs/tags, respectively.
+       These options are _not_ mutually exclusive; when given
+       both, references stored in refs/heads and refs/tags are
+       displayed.
+
+<repository>::
+       Location of the repository.  The shorthand defined in
+       $GIT_DIR/branches/ can be used.
+
+<refs>...::
+       When unspecified, all references, after filtering done
+       with --heads and --tags, are shown.  When <refs>... are
+       specified, only references matching the given patterns
+       are displayed.
+
+EXAMPLES
+--------
+
+       $ git ls-remote --tags ./.
+       d6602ec5194c87b0fc87103ca4d67251c76f233a        refs/tags/v0.99
+       f25a265a342aed6041ab0cc484224d9ca54b6f41        refs/tags/v0.99.1
+       7ceca275d047c90c0c7d5afb13ab97efdf51bd6e        refs/tags/v0.99.3
+       c5db5456ae3b0873fc659c19fafdde22313cc441        refs/tags/v0.99.2
+       0918385dbd9656cab0d1d81ba7453d49bbc16250        refs/tags/junio-gpg-pub
+       $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master pu rc
+       5fe978a5381f1fbad26a80e682ddd2a401966740        refs/heads/master
+       c781a84b5204fb294c9ccc79f8b3baceeb32c061        refs/heads/pu
+       b1d096f2926c4e37c9c0b6a7bf2119bedaa277cb        refs/heads/rc
+       $ echo http://www.kernel.org/pub/scm/git/git.git >.git/branches/public
+       $ git ls-remote --tags public v\*
+       d6602ec5194c87b0fc87103ca4d67251c76f233a        refs/tags/v0.99
+       f25a265a342aed6041ab0cc484224d9ca54b6f41        refs/tags/v0.99.1
+       c5db5456ae3b0873fc659c19fafdde22313cc441        refs/tags/v0.99.2
+       7ceca275d047c90c0c7d5afb13ab97efdf51bd6e        refs/tags/v0.99.3
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
new file mode 100644 (file)
index 0000000..b92a8b2
--- /dev/null
@@ -0,0 +1,73 @@
+git-ls-tree(1)
+==============
+
+NAME
+----
+git-ls-tree - Lists the contents of a tree object.
+
+
+SYNOPSIS
+--------
+'git-ls-tree' [-d] [-r] [-t] [-z] [--name-only] [--name-status] <tree-ish> [paths...]
+
+DESCRIPTION
+-----------
+Lists the contents of a given tree object, like what "/bin/ls -a" does
+in the current working directory. Note that the usage is subtly different,
+though - 'paths' denote just a list of patterns to match, e.g. so specifying
+directory name (without '-r') will behave differently, and order of the
+arguments does not matter.
+
+OPTIONS
+-------
+<tree-ish>::
+       Id of a tree-ish.
+
+-d::
+       Show only the named tree entry itself, not its children.
+
+-r::
+       Recurse into sub-trees.
+
+-t::
+       Show tree entries even when going to recurse them. Has no effect
+       if '-r' was not passed. '-d' implies '-t'.
+
+-z::
+       \0 line termination on output.
+
+--name-only::
+--name-status::
+       List only filenames (instead of the "long" output), one per line.
+
+paths::
+       When paths are given, show them (note that this isn't really raw
+       pathnames, but rather a list of patterns to match).  Otherwise
+       implicitly uses the root level of the tree as the sole path argument.
+
+
+Output Format
+-------------
+        <mode> SP <type> SP <object> TAB <file>
+
+When the `-z` option is not used, TAB, LF, and backslash characters
+in pathnames are represented as `\t`, `\n`, and `\\`, respectively.
+
+
+Author
+------
+Written by Petr Baudis <pasky@suse.cz>
+Completely rewritten from scratch by Junio C Hamano <junkio@cox.net>,
+another major rewrite by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list
+<git@vger.kernel.org>.
+
+This manual page is a stub. You can help the git documentation by expanding it.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
new file mode 100644 (file)
index 0000000..8890754
--- /dev/null
@@ -0,0 +1,72 @@
+git-mailinfo(1)
+===============
+
+NAME
+----
+git-mailinfo - Extracts patch from a single e-mail message.
+
+
+SYNOPSIS
+--------
+'git-mailinfo' [-k] [-u | --encoding=<encoding>] <msg> <patch>
+
+
+DESCRIPTION
+-----------
+Reading a single e-mail message from the standard input, and
+writes the commit log message in <msg> file, and the patches in
+<patch> file.  The author name, e-mail and e-mail subject are
+written out to the standard output to be used by git-applypatch
+to create a commit.  It is usually not necessary to use this
+command directly.
+
+
+OPTIONS
+-------
+-k::
+       Usually the program 'cleans up' the Subject: header line
+       to extract the title line for the commit log message,
+       among which (1) remove 'Re:' or 're:', (2) leading
+       whitespaces, (3) '[' up to ']', typically '[PATCH]', and
+       then prepends "[PATCH] ".  This flag forbids this
+       munging, and is most useful when used to read back 'git
+       format-patch --mbox' output.
+
+-u::
+       By default, the commit log message, author name and
+       author email are taken from the e-mail without any
+       charset conversion, after minimally decoding MIME
+       transfer encoding.  This flag causes the resulting
+       commit to be encoded in the encoding specified by
+       i18n.commitencoding configuration (defaults to utf-8) by
+       transliterating them. 
+       Note that the patch is always used as is without charset
+       conversion, even with this flag.
+
+--encoding=<encoding>::
+       Similar to -u but if the local convention is different
+       from what is specified by i18n.commitencoding, this flag
+       can be used to override it.
+
+<msg>::
+       The commit log message extracted from e-mail, usually
+       except the title line which comes from e-mail Subject.
+
+<patch>::
+       The patch extracted from e-mail.
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org> and
+Junio C Hamano <junkio@cox.net>
+
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt
new file mode 100644 (file)
index 0000000..e0703e9
--- /dev/null
@@ -0,0 +1,52 @@
+git-mailsplit(1)
+================
+
+NAME
+----
+git-mailsplit - Totally braindamaged mbox splitter program.
+
+SYNOPSIS
+--------
+'git-mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>...]
+
+DESCRIPTION
+-----------
+Splits a mbox file into a list of files: "0001" "0002" ..  in the specified
+directory so you can process them further from there.
+
+OPTIONS
+-------
+<mbox>::
+       Mbox file to split.  If not given, the mbox is read from
+       the standard input.
+
+<directory>::
+       Directory in which to place the individual messages.
+
+-b::
+       If any file doesn't begin with a From line, assume it is a
+       single mail message instead of signalling error.
+
+-d<prec>::
+       Instead of the default 4 digits with leading zeros,
+       different precision can be specified for the generated
+       filenames.
+
+-f<nn>::
+       Skip the first <nn> numbers, for example if -f3 is specified,
+       start the numbering with 0004.
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+and Junio C Hamano <junkio@cox.net>
+
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
new file mode 100644 (file)
index 0000000..d1d56f1
--- /dev/null
@@ -0,0 +1,33 @@
+git-merge-base(1)
+=================
+
+NAME
+----
+git-merge-base - Finds as good a common ancestor as possible for a merge
+
+
+SYNOPSIS
+--------
+'git-merge-base' <commit> <commit>
+
+DESCRIPTION
+-----------
+"git-merge-base" finds as good a common ancestor as possible. Given a
+selection of equally good common ancestors it should not be relied on
+to decide in any particular way.
+
+The "git-merge-base" algorithm is still in flux - use the source...
+
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt
new file mode 100644 (file)
index 0000000..fbc986a
--- /dev/null
@@ -0,0 +1,88 @@
+git-merge-index(1)
+==================
+
+NAME
+----
+git-merge-index - Runs a merge for files needing merging
+
+
+SYNOPSIS
+--------
+'git-merge-index' [-o] [-q] <merge-program> (-a | -- | <file>\*)
+
+DESCRIPTION
+-----------
+This looks up the <file>(s) in the index and, if there are any merge
+entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty
+argument if no file), and <file> as argument 4.  File modes for the three
+files are passed as arguments 5, 6 and 7.
+
+OPTIONS
+-------
+--::
+       Do not interpret any more arguments as options.
+
+-a::
+       Run merge against all files in the index that need merging.
+
+-o::
+       Instead of stopping at the first failed merge, do all of them
+       in one shot - continue with merging even when previous merges
+       returned errors, and only return the error code after all the
+       merges are over.
+
+-q::
+       Do not complain about failed merge program (the merge program
+       failure usually indicates conflicts during merge). This is for
+       porcelains which might want to emit custom messages.
+
+If "git-merge-index" is called with multiple <file>s (or -a) then it
+processes them in turn only stopping if merge returns a non-zero exit
+code.
+
+Typically this is run with the a script calling the merge command from
+the RCS package.
+
+A sample script called "git-merge-one-file" is included in the
+distribution.
+
+ALERT ALERT ALERT! The git "merge object order" is different from the
+RCS "merge" program merge object order. In the above ordering, the
+original is first. But the argument order to the 3-way merge program
+"merge" is to have the original in the middle. Don't ask me why.
+
+Examples:
+
+  torvalds@ppc970:~/merge-test> git-merge-index cat MM
+  This is MM from the original tree.                   # original
+  This is modified MM in the branch A.                 # merge1
+  This is modified MM in the branch B.                 # merge2
+  This is modified MM in the branch B.                 # current contents
+
+or 
+
+  torvalds@ppc970:~/merge-test> git-merge-index cat AA MM
+  cat: : No such file or directory
+  This is added AA in the branch A.
+  This is added AA in the branch B.
+  This is added AA in the branch B.
+  fatal: merge program failed
+
+where the latter example shows how "git-merge-index" will stop trying to
+merge once anything has returned an error (ie "cat" returned an error
+for the AA file, because it didn't exist in the original, and thus
+"git-merge-index" didn't even try to merge the MM thing).
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>
+One-shot merge by Petr Baudis <pasky@ucw.cz>
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt
new file mode 100644 (file)
index 0000000..86aad37
--- /dev/null
@@ -0,0 +1,30 @@
+git-merge-one-file(1)
+=====================
+
+NAME
+----
+git-merge-one-file - The standard helper program to use with "git-merge-index"
+
+
+SYNOPSIS
+--------
+'git-merge-one-file'
+
+DESCRIPTION
+-----------
+This is the standard helper program to use with "git-merge-index"
+to resolve a merge after the trivial merge done with "git-read-tree -m".
+
+Author
+------
+Written by Linus Torvalds <torvalds@osdl.org>,
+Junio C Hamano <junkio@cox.net> and Petr Baudis <pasky@suse.cz>.
+
+Documentation
+--------------
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
new file mode 100644 (file)
index 0000000..4ce799b
--- /dev/null
@@ -0,0 +1,158 @@
+git-merge(1)
+============
+
+NAME
+----
+git-merge - Grand Unified Merge Driver
+
+
+SYNOPSIS
+--------
+'git-merge' [-n] [--no-commit] [-s <strategy>]... <msg> <head> <remote> <remote>...
+
+
+DESCRIPTION
+-----------
+This is the top-level user interface to the merge machinery
+which drives multiple merge strategy scripts.
+
+
+OPTIONS
+-------
+include::merge-options.txt[]
+
+<msg>::
+       The commit message to be used for the merge commit (in case
+       it is created). The `git-fmt-merge-msg` script can be used
+       to give a good default for automated `git-merge` invocations.
+
+<head>::
+       our branch head commit.
+
+<remote>::
+       other branch head merged into our branch.  You need at
+       least one <remote>.  Specifying more than one <remote>
+       obviously means you are trying an Octopus.
+
+include::merge-strategies.txt[]
+
+
+If you tried a merge which resulted in a complex conflicts and
+would want to start over, you can recover with
+gitlink:git-reset[1].
+
+
+HOW MERGE WORKS
+---------------
+
+A merge is always between the current `HEAD` and one or more
+remote branch heads, and the index file must exactly match the
+tree of `HEAD` commit (i.e. the contents of the last commit) when
+it happens.  In other words, `git-diff --cached HEAD` must
+report no changes.
+
+[NOTE]
+This is a bit of lie.  In certain special cases, your index are
+allowed to be different from the tree of `HEAD` commit.  The most
+notable case is when your `HEAD` commit is already ahead of what
+is being merged, in which case your index can have arbitrary
+difference from your `HEAD` commit.  Otherwise, your index entries
+are allowed have differences from your `HEAD` commit that match
+the result of trivial merge (e.g. you received the same patch
+from external source to produce the same result as what you are
+merging).  For example, if a path did not exist in the common
+ancestor and your head commit but exists in the tree you are
+merging into your repository, and if you already happen to have
+that path exactly in your index, the merge does not have to
+fail.
+
+Otherwise, merge will refuse to do any harm to your repository
+(that is, it may fetch the objects from remote, and it may even
+update the local branch used to keep track of the remote branch
+with `git pull remote rbranch:lbranch`, but your working tree,
+`.git/HEAD` pointer and index file are left intact).
+
+You may have local modifications in the working tree files.  In
+other words, `git-diff` is allowed to report changes.
+However, the merge uses your working tree as the working area,
+and in order to prevent the merge operation from losing such
+changes, it makes sure that they do not interfere with the
+merge. Those complex tables in read-tree documentation define
+what it means for a path to "interfere with the merge".  And if
+your local modifications interfere with the merge, again, it
+stops before touching anything.
+
+So in the above two "failed merge" case, you do not have to
+worry about lossage of data --- you simply were not ready to do
+a merge, so no merge happened at all.  You may want to finish
+whatever you were in the middle of doing, and retry the same
+pull after you are done and ready.
+
+When things cleanly merge, these things happen:
+
+1. the results are updated both in the index file and in your
+   working tree,
+2. index file is written out as a tree,
+3. the tree gets committed, and 
+4. the `HEAD` pointer gets advanced.
+
+Because of 2., we require that the original state of the index
+file to match exactly the current `HEAD` commit; otherwise we
+will write out your local changes already registered in your
+index file along with the merge result, which is not good.
+Because 1. involves only the paths different between your
+branch and the remote branch you are pulling from during the
+merge (which is typically a fraction of the whole tree), you can
+have local modifications in your working tree as long as they do
+not overlap with what the merge updates.
+
+When there are conflicts, these things happen:
+
+1. `HEAD` stays the same.
+
+2. Cleanly merged paths are updated both in the index file and
+   in your working tree.
+
+3. For conflicting paths, the index file records up to three
+   versions; stage1 stores the version from the common ancestor,
+   stage2 from `HEAD`, and stage3 from the remote branch (you
+   can inspect the stages with `git-ls-files -u`).  The working
+   tree files have the result of "merge" program; i.e. 3-way
+   merge result with familiar conflict markers `<<< === >>>`.
+
+4. No other changes are done.  In particular, the local
+   modifications you had before you started merge will stay the
+   same and the index entries for them stay as they were,
+   i.e. matching `HEAD`.
+
+After seeing a conflict, you can do two things:
+
+ * Decide not to merge.  The only clean-up you need are to reset
+   the index file to the `HEAD` commit to reverse 2. and to clean
+   up working tree changes made by 2. and 3.; `git-reset` can
+   be used for this.
+
+ * Resolve the conflicts.  `git-diff` would report only the
+   conflicting paths because of the above 2. and 3..  Edit the
+   working tree files into a desirable shape, `git-update-index`
+   them, to make the index file contain what the merge result
+   should be, and run `git-commit` to commit the result.
+
+
+SEE ALSO
+--------
+gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]
+
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+
+Documentation
+--------------
+Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt
new file mode 100644 (file)
index 0000000..2860a3d
--- /dev/null
@@ -0,0 +1,47 @@
+git-mktag(1)
+============
+
+NAME
+----
+git-mktag - Creates a tag object
+
+
+SYNOPSIS
+--------
+'git-mktag' < signature_file
+
+DESCRIPTION
+-----------
+Reads a tag contents on standard input and creates a tag object
+that can also be used to sign other objects.
+
+The output is the new tag's <object> identifier.
+
+Tag Format
+----------
+A tag signature file has a very simple fixed format: three lines of
+
+  object <sha1>
+  type <typename>