From b37dfa4081144f0f3a6805ebe0f00d6bcbd4e531 Mon Sep 17 00:00:00 2001 From: Sven Strickroth Date: Thu, 5 May 2016 19:34:27 +0200 Subject: [PATCH] Update git documentation Signed-off-by: Sven Strickroth --- doc/source/en/TortoiseGit/git_doc.patch | 29 +- doc/source/en/TortoiseGit/git_doc/everyday.xml | 713 ----- doc/source/en/TortoiseGit/git_doc/git-add.xml | 85 +- doc/source/en/TortoiseGit/git_doc/git-am.xml | 90 +- doc/source/en/TortoiseGit/git_doc/git-annotate.xml | 46 +- doc/source/en/TortoiseGit/git_doc/git-apply.xml | 28 +- .../en/TortoiseGit/git_doc/git-archimport.xml | 16 +- doc/source/en/TortoiseGit/git_doc/git-archive.xml | 14 +- doc/source/en/TortoiseGit/git_doc/git-bisect.xml | 215 +- doc/source/en/TortoiseGit/git_doc/git-blame.xml | 72 +- doc/source/en/TortoiseGit/git_doc/git-branch.xml | 78 +- doc/source/en/TortoiseGit/git_doc/git-bundle.xml | 13 +- doc/source/en/TortoiseGit/git_doc/git-cat-file.xml | 238 +- .../en/TortoiseGit/git_doc/git-check-attr.xml | 16 +- .../en/TortoiseGit/git_doc/git-check-ignore.xml | 185 ++ .../{git-shortlog.xml => git-check-mailmap.xml} | 121 +- .../TortoiseGit/git_doc/git-check-ref-format.xml | 20 +- doc/source/en/TortoiseGit/git_doc/git-checkout.xml | 88 +- .../en/TortoiseGit/git_doc/git-cherry-pick.xml | 22 +- doc/source/en/TortoiseGit/git_doc/git-cherry.xml | 111 +- doc/source/en/TortoiseGit/git_doc/git-clean.xml | 122 +- doc/source/en/TortoiseGit/git_doc/git-clone.xml | 126 +- doc/source/en/TortoiseGit/git_doc/git-column.xml | 4 - .../en/TortoiseGit/git_doc/git-commit-tree.xml | 83 +- doc/source/en/TortoiseGit/git_doc/git-commit.xml | 184 +- doc/source/en/TortoiseGit/git_doc/git-config.xml | 2826 +++++++++++++++++--- .../en/TortoiseGit/git_doc/git-count-objects.xml | 31 +- .../git_doc/git-credential-cache--daemon.xml | 5 +- .../TortoiseGit/git_doc/git-credential-cache.xml | 6 +- .../TortoiseGit/git_doc/git-credential-store.xml | 54 +- .../en/TortoiseGit/git_doc/git-credential.xml | 8 +- .../en/TortoiseGit/git_doc/git-cvsexportcommit.xml | 6 +- .../en/TortoiseGit/git_doc/git-cvsimport.xml | 29 +- .../en/TortoiseGit/git_doc/git-cvsserver.xml | 89 +- doc/source/en/TortoiseGit/git_doc/git-daemon.xml | 35 +- doc/source/en/TortoiseGit/git_doc/git-describe.xml | 37 +- .../en/TortoiseGit/git_doc/git-diff-files.xml | 165 +- .../en/TortoiseGit/git_doc/git-diff-index.xml | 177 +- .../en/TortoiseGit/git_doc/git-diff-tree.xml | 320 ++- doc/source/en/TortoiseGit/git_doc/git-diff.xml | 219 +- doc/source/en/TortoiseGit/git_doc/git-difftool.xml | 41 +- doc/source/en/TortoiseGit/git_doc/git-doc.xml | 13 +- .../en/TortoiseGit/git_doc/git-fast-export.xml | 91 +- .../en/TortoiseGit/git_doc/git-fast-import.xml | 234 +- .../en/TortoiseGit/git_doc/git-fetch-pack.xml | 30 +- doc/source/en/TortoiseGit/git_doc/git-fetch.xml | 309 ++- .../en/TortoiseGit/git_doc/git-filter-branch.xml | 73 +- .../en/TortoiseGit/git_doc/git-fmt-merge-msg.xml | 14 +- .../en/TortoiseGit/git_doc/git-for-each-ref.xml | 144 +- .../en/TortoiseGit/git_doc/git-format-patch.xml | 179 +- doc/source/en/TortoiseGit/git_doc/git-fsck.xml | 34 +- doc/source/en/TortoiseGit/git_doc/git-gc.xml | 35 +- .../TortoiseGit/git_doc/git-get-tar-commit-id.xml | 11 +- doc/source/en/TortoiseGit/git_doc/git-grep.xml | 80 +- doc/source/en/TortoiseGit/git_doc/git-gui.xml | 2 +- .../en/TortoiseGit/git_doc/git-hash-object.xml | 24 +- doc/source/en/TortoiseGit/git_doc/git-help.xml | 50 +- .../en/TortoiseGit/git_doc/git-http-backend.xml | 87 +- .../en/TortoiseGit/git_doc/git-http-fetch.xml | 4 +- .../en/TortoiseGit/git_doc/git-imap-send.xml | 69 +- .../en/TortoiseGit/git_doc/git-index-pack.xml | 18 +- doc/source/en/TortoiseGit/git_doc/git-init-db.xml | 2 +- doc/source/en/TortoiseGit/git_doc/git-init.xml | 117 +- doc/source/en/TortoiseGit/git_doc/git-instaweb.xml | 2 +- .../TortoiseGit/git_doc/git-interpret-trailers.xml | 404 +++ doc/source/en/TortoiseGit/git_doc/git-log.xml | 825 ++++-- .../en/TortoiseGit/git_doc/git-lost-found.xml | 67 - doc/source/en/TortoiseGit/git_doc/git-ls-files.xml | 35 +- .../en/TortoiseGit/git_doc/git-ls-remote.xml | 51 +- doc/source/en/TortoiseGit/git_doc/git-mailinfo.xml | 16 +- .../en/TortoiseGit/git_doc/git-merge-base.xml | 44 +- .../en/TortoiseGit/git_doc/git-merge-file.xml | 15 +- .../en/TortoiseGit/git_doc/git-merge-index.xml | 6 +- .../en/TortoiseGit/git_doc/git-merge-tree.xml | 2 +- doc/source/en/TortoiseGit/git_doc/git-merge.xml | 325 ++- .../en/TortoiseGit/git_doc/git-mergetool--lib.xml | 4 +- .../en/TortoiseGit/git_doc/git-mergetool.xml | 10 +- doc/source/en/TortoiseGit/git_doc/git-mktag.xml | 9 +- doc/source/en/TortoiseGit/git_doc/git-mv.xml | 24 +- doc/source/en/TortoiseGit/git_doc/git-name-rev.xml | 11 +- doc/source/en/TortoiseGit/git_doc/git-notes.xml | 71 +- doc/source/en/TortoiseGit/git_doc/git-p4.xml | 274 +- .../en/TortoiseGit/git_doc/git-pack-objects.xml | 33 +- .../en/TortoiseGit/git_doc/git-pack-refs.xml | 4 +- doc/source/en/TortoiseGit/git_doc/git-patch-id.xml | 58 +- .../en/TortoiseGit/git_doc/git-peek-remote.xml | 73 - .../en/TortoiseGit/git_doc/git-prune-packed.xml | 2 +- doc/source/en/TortoiseGit/git_doc/git-prune.xml | 8 +- doc/source/en/TortoiseGit/git_doc/git-pull.xml | 343 ++- doc/source/en/TortoiseGit/git_doc/git-push.xml | 293 +- .../en/TortoiseGit/git_doc/git-quiltimport.xml | 23 +- .../en/TortoiseGit/git_doc/git-read-tree.xml | 4 +- doc/source/en/TortoiseGit/git_doc/git-rebase.xml | 195 +- .../en/TortoiseGit/git_doc/git-receive-pack.xml | 147 +- doc/source/en/TortoiseGit/git_doc/git-reflog.xml | 335 ++- .../en/TortoiseGit/git_doc/git-remote-ext.xml | 21 +- .../en/TortoiseGit/git_doc/git-remote-fd.xml | 12 +- .../en/TortoiseGit/git_doc/git-remote-testgit.xml | 4 +- doc/source/en/TortoiseGit/git_doc/git-remote.xml | 73 +- doc/source/en/TortoiseGit/git_doc/git-repack.xml | 38 +- doc/source/en/TortoiseGit/git_doc/git-replace.xml | 130 +- .../en/TortoiseGit/git_doc/git-repo-config.xml | 28 - .../en/TortoiseGit/git_doc/git-request-pull.xml | 42 +- doc/source/en/TortoiseGit/git_doc/git-rerere.xml | 2 +- doc/source/en/TortoiseGit/git_doc/git-reset.xml | 26 +- doc/source/en/TortoiseGit/git_doc/git-rev-list.xml | 518 ++-- .../en/TortoiseGit/git_doc/git-rev-parse.xml | 393 ++- doc/source/en/TortoiseGit/git_doc/git-revert.xml | 20 +- doc/source/en/TortoiseGit/git_doc/git-rm.xml | 32 +- .../en/TortoiseGit/git_doc/git-send-email.xml | 227 +- .../en/TortoiseGit/git_doc/git-send-pack.xml | 58 +- doc/source/en/TortoiseGit/git_doc/git-sh-setup.xml | 25 +- doc/source/en/TortoiseGit/git_doc/git-shell.xml | 95 +- doc/source/en/TortoiseGit/git_doc/git-shortlog.xml | 51 +- .../en/TortoiseGit/git_doc/git-show-branch.xml | 6 +- .../en/TortoiseGit/git_doc/git-show-index.xml | 9 +- doc/source/en/TortoiseGit/git_doc/git-show-ref.xml | 25 +- .../git_doc/{git-diff-tree.xml => git-show.xml} | 2351 ++++++++-------- doc/source/en/TortoiseGit/git_doc/git-stash.xml | 24 +- doc/source/en/TortoiseGit/git_doc/git-status.xml | 58 +- .../en/TortoiseGit/git_doc/git-stripspace.xml | 25 +- .../en/TortoiseGit/git_doc/git-submodule.xml | 258 +- doc/source/en/TortoiseGit/git_doc/git-svn.xml | 345 ++- doc/source/en/TortoiseGit/git_doc/git-tag.xml | 118 +- doc/source/en/TortoiseGit/git_doc/git-tar-tree.xml | 152 -- .../en/TortoiseGit/git_doc/git-unpack-objects.xml | 6 +- .../en/TortoiseGit/git_doc/git-update-index.xml | 170 +- .../en/TortoiseGit/git_doc/git-update-ref.xml | 94 +- .../en/TortoiseGit/git_doc/git-upload-archive.xml | 42 +- .../en/TortoiseGit/git_doc/git-upload-pack.xml | 2 +- doc/source/en/TortoiseGit/git_doc/git-var.xml | 12 +- .../en/TortoiseGit/git_doc/git-verify-commit.xml | 66 + .../en/TortoiseGit/git_doc/git-verify-pack.xml | 8 +- .../en/TortoiseGit/git_doc/git-verify-tag.xml | 13 +- .../en/TortoiseGit/git_doc/git-web--browse.xml | 18 +- .../en/TortoiseGit/git_doc/git-whatchanged.xml | 719 +---- doc/source/en/TortoiseGit/git_doc/git-worktree.xml | 319 +++ doc/source/en/TortoiseGit/git_doc/git.xml | 686 +++-- .../en/TortoiseGit/git_doc/gitattributes.xml | 100 +- doc/source/en/TortoiseGit/git_doc/gitcli.xml | 52 +- .../en/TortoiseGit/git_doc/gitcore-tutorial.xml | 209 +- .../en/TortoiseGit/git_doc/gitcredentials.xml | 30 +- .../en/TortoiseGit/git_doc/gitcvs-migration.xml | 28 +- doc/source/en/TortoiseGit/git_doc/gitdiffcore.xml | 43 +- doc/source/en/TortoiseGit/git_doc/giteveryday.xml | 781 ++++++ doc/source/en/TortoiseGit/git_doc/gitglossary.xml | 409 ++- doc/source/en/TortoiseGit/git_doc/githooks.xml | 71 +- doc/source/en/TortoiseGit/git_doc/gitignore.xml | 88 +- doc/source/en/TortoiseGit/git_doc/gitk.xml | 214 +- doc/source/en/TortoiseGit/git_doc/gitmodules.xml | 46 +- .../en/TortoiseGit/git_doc/gitnamespaces.xml | 2 +- ...it-remote-helpers.xml => gitremote-helpers.xml} | 191 +- .../TortoiseGit/git_doc/gitrepository-layout.xml | 186 +- doc/source/en/TortoiseGit/git_doc/gitrevisions.xml | 94 +- .../en/TortoiseGit/git_doc/gittutorial-2.xml | 74 +- doc/source/en/TortoiseGit/git_doc/gittutorial.xml | 62 +- doc/source/en/TortoiseGit/git_doc/gitweb.conf.xml | 125 +- doc/source/en/TortoiseGit/git_doc/gitweb.xml | 24 +- doc/source/en/TortoiseGit/git_doc/gitworkflows.xml | 6 +- doc/source/en/TortoiseGit/git_doc/user-manual.xml | 2020 ++++++++------ .../en/TortoiseGit/tgit_dug/dug_settings_git.xml | 2 +- 161 files changed, 16620 insertions(+), 7658 deletions(-) delete mode 100644 doc/source/en/TortoiseGit/git_doc/everyday.xml create mode 100644 doc/source/en/TortoiseGit/git_doc/git-check-ignore.xml copy doc/source/en/TortoiseGit/git_doc/{git-shortlog.xml => git-check-mailmap.xml} (50%) create mode 100644 doc/source/en/TortoiseGit/git_doc/git-interpret-trailers.xml delete mode 100644 doc/source/en/TortoiseGit/git_doc/git-lost-found.xml delete mode 100644 doc/source/en/TortoiseGit/git_doc/git-peek-remote.xml rewrite doc/source/en/TortoiseGit/git_doc/git-reflog.xml (63%) delete mode 100644 doc/source/en/TortoiseGit/git_doc/git-repo-config.xml copy doc/source/en/TortoiseGit/git_doc/{git-diff-tree.xml => git-show.xml} (71%) delete mode 100644 doc/source/en/TortoiseGit/git_doc/git-tar-tree.xml create mode 100644 doc/source/en/TortoiseGit/git_doc/git-verify-commit.xml rewrite doc/source/en/TortoiseGit/git_doc/git-whatchanged.xml (91%) create mode 100644 doc/source/en/TortoiseGit/git_doc/git-worktree.xml create mode 100644 doc/source/en/TortoiseGit/git_doc/giteveryday.xml rename doc/source/en/TortoiseGit/git_doc/{git-remote-helpers.xml => gitremote-helpers.xml} (78%) diff --git a/doc/source/en/TortoiseGit/git_doc.patch b/doc/source/en/TortoiseGit/git_doc.patch index 2188f8a91..d33d21a0b 100644 --- a/doc/source/en/TortoiseGit/git_doc.patch +++ b/doc/source/en/TortoiseGit/git_doc.patch @@ -13,8 +13,7 @@ Generating git docbook documentation: (done on Debian SID) (\w)--(\w)=\1—\2 (\w)'(\w)=\1’\2 - make xml -- take *.xml files (skip git-tools.xml) -- after generation change everyday.xml: article-id to everyday +- take *.xml files diff --git a/Documentation/Makefile b/Documentation/Makefile index 9ad6a6a..adfe07a 100644 @@ -29,22 +28,15 @@ index 9ad6a6a..adfe07a 100644 man: man1 man5 man7 man1: $(DOC_MAN1) man5: $(DOC_MAN5) -@@ -257,13 +259,13 @@ manpage-base-url.xsl: manpage-base-url.xsl.in +@@ -330,7 +332,7 @@ manpage-base-url.xsl: manpage-base-url.xsl.in - %.xml : %.txt + %.xml : %.txt asciidoc.conf $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ -- $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ -+ $(ASCIIDOC) -b docbook -d article -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ +- $(TXT_TO_XML) -d manpage -o $@+ $< && \ ++ $(TXT_TO_XML) -d article -o $@+ $< && \ mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ -- $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o $@+ $< && \ -+ $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d article -o $@+ $< && \ - mv $@+ $@ - - technical/api-index.txt: technical/api-index-skel.txt \ diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 1273a85..5223c99 --- a/Documentation/asciidoc.conf @@ -225,14 +217,3 @@ index d87294d..704f2cc + +{title#} +endif::doctype-manpage[] -diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt -index 1b94207..49a0a9c 100644 ---- a/Documentation/user-manual.txt -+++ b/Documentation/user-manual.txt -@@ -1,5 +1,5 @@ - Git User's Manual (for version 1.5.3 or newer) --______________________________________________ -+============================================== - - - Git is a fast distributed revision control system. diff --git a/doc/source/en/TortoiseGit/git_doc/everyday.xml b/doc/source/en/TortoiseGit/git_doc/everyday.xml deleted file mode 100644 index 9fd54228e..000000000 --- a/doc/source/en/TortoiseGit/git_doc/everyday.xml +++ /dev/null @@ -1,713 +0,0 @@ - - - - - Everyday GIT With 20 Commands Or So - -Everyday GIT With 20 Commands Or So - - 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 -the section as well. -People who play the role need to learn some more -commands in addition to the above. - commands are for system -administrators who are responsible for the care and feeding -of git repositories. - -Individual Developer (Standalone)<anchor id="Everyday GIT With 20 Commands Or So_Individual Developer (Standalone)" xreflabel="[Individual Developer (Standalone)]"/> -A standalone individual developer does not exchange patches with -other people, and works alone in a single repository, using the -following commands. - - - - to create a new repository. - - - - - to see where you are. - - - - - to see what happened. - - - - - and to switch - branches. - - - - - to manage the index file. - - - - - and to see what - you are in the middle of doing. - - - - - to advance the current branch. - - - - - and (with - pathname parameters) to undo changes. - - - - - to merge between local branches. - - - - - to maintain topic branches. - - - - - to mark known point. - - - -
-Examples - - - -Use a tarball as a starting point for a new repository. - - -$ tar zxf frotz.tar.gz -$ cd frotz -$ git init -$ git add . -$ git commit -m "import of frotz source tree." -$ git tag v2.43 - - - -add everything under the current directory. - - - - -make a lightweight, unannotated tag. - - - - - - - -Create a topic branch and develop. - - -$ git checkout -b alsa-audio -$ edit/compile/test -$ git checkout -- curses/ux_audio_oss.c -$ git add curses/ux_audio_alsa.c -$ edit/compile/test -$ git diff HEAD -$ git commit -a -s -$ edit/compile/test -$ git reset --soft HEAD^ -$ edit/compile/test -$ git diff ORIG_HEAD -$ git commit -a -c ORIG_HEAD -$ git checkout master -$ git merge alsa-audio -$ git log --since='3 days ago' -$ git log v2.43.. curses/ - - - -create a new topic branch. - - - - -revert your botched changes in curses/ux_audio_oss.c. - - - - -you need to tell git if you added a new file; removal and -modification will be caught if you do git commit -a later. - - - - -to see what changes you are committing. - - - - -commit everything as you have tested, with your sign-off. - - - - -take the last commit back, keeping what is in the working tree. - - - - -look at the changes since the premature commit we took back. - - - - -redo the commit undone in the previous step, using the message -you originally wrote. - - - - -switch to the master branch. - - - - -merge a topic branch into your master branch. - - - - -review commit logs; other forms to limit output can be -combined and include --max-count=10 (show 10 commits), ---until=2005-12-10, etc. - - - - -view only the changes that touch what's in curses/ -directory, since v2.43 tag. - - - - - - -
- - -Individual Developer (Participant)<anchor id="Everyday GIT With 20 Commands Or So_Individual Developer (Participant)" xreflabel="[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. - - - - from the upstream to prime your local - repository. - - - - - and from "origin" - to keep up-to-date with the upstream. - - - - - to shared repository, if you adopt CVS - style shared repository workflow. - - - - - 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 -$ git format-patch origin -$ git pull -$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 -$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL -$ git reset --hard ORIG_HEAD -$ git gc -$ git fetch --tags - - - -repeat as needed. - - - - -extract patches from your branch for e-mail submission. - - - - -git pull fetches from origin by default and merges into the -current branch. - - - - -immediately after pulling, look at the changes done upstream -since last time we checked, only in the -area we are interested in. - - - - -fetch from a specific branch from a specific repository and merge. - - - - -revert the pull. - - - - -garbage collect leftover objects from reverted pull. - - - - -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 frotz -satellite$ cd frotz -satellite$ git config --get-regexp '^(remote|branch)\.' -remote.origin.url mothership:frotz -remote.origin.fetch refs/heads/*:refs/remotes/origin/* -branch.master.remote origin -branch.master.merge refs/heads/master -satellite$ git config remote.origin.push \ - master:refs/remotes/satellite/master -satellite$ edit/compile/test/commit -satellite$ git push origin - -mothership$ cd frotz -mothership$ git checkout master -mothership$ git merge satellite/master - - - -mothership machine has a frotz repository under your home -directory; clone from it to start a repository on the satellite -machine. - - - - -clone sets these configuration variables by default. -It arranges git pull to fetch and store the branches of mothership -machine to local remotes/origin/* remote-tracking branches. - - - - -arrange git push to push local master branch to -remotes/satellite/master branch of the mothership machine. - - - - -push will stash our work away on remotes/satellite/master -remote-tracking branch on the mothership machine. You could use this -as a back-up method. - - - - -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 -$ 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 - - - -create a private branch based on a well known (but somewhat behind) -tag. - - - - -forward port all changes in private2.6.14 branch to master branch -without a formal "merging". - - - - - - -
- - -Integrator<anchor id="Everyday GIT With 20 Commands Or So_Integrator" xreflabel="[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. - - - - to apply patches e-mailed in from your - contributors. - - - - - to merge from your trusted lieutenants. - - - - - to prepare and send suggested - alternative to contributors. - - - - - to undo botched commits. - - - - - to publish the bleeding edge. - - - -
-Examples - - - -My typical GIT day. - - -$ git status -$ git show-branch -$ mailx -& s 2 3 4 5 ./+to-apply -& s 7 8 ./+hold-linus -& q -$ git checkout -b topic/one master -$ git am -3 -i -s -u ./+to-apply -$ compile/test -$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus -$ git checkout topic/one && git rebase master -$ git checkout pu && git reset --hard next -$ git merge topic/one topic/two && git merge hold/linus -$ git checkout maint -$ git cherry-pick master~4 -$ compile/test -$ git tag -s -m "GIT 0.99.9x" v0.99.9x -$ git fetch ko && git show-branch master maint 'tags/ko-*' -$ git push ko -$ git push ko v0.99.9x - - - -see what I was in the middle of doing, if any. - - - - -see what topic branches I have and think about how ready -they are. - - - - -read mails, save ones that are applicable, and save others -that are not quite ready. - - - - -apply them, interactively, with my sign-offs. - - - - -create topic branch as needed and apply, again with my -sign-offs. - - - - -rebase internal topic branch that has not been merged to the -master, nor exposed as a part of a stable branch. - - - - -restart pu every time from the next. - - - - -and bundle topic branches still cooking. - - - - -backport a critical fix. - - - - -create a signed tag. - - - - -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: next:refs/tags/ko-next -Pull: maint:refs/tags/ko-maint -Push: master -Push: next -Push: +pu -Push: maint -In the output from git show-branch, master should have -everything ko-master has, and next should have -everything ko-next has. - - - -push out the bleeding edge. - - - - -push the tag out, too. - - - - - - -
- - -Repository Administration<anchor id="Everyday GIT With 20 Commands Or So_Repository Administration" xreflabel="[Repository Administration]"/> -A repository administrator uses the following tools to set up -and maintain access to the repository by developers. - - - - to allow anonymous download from - repository. - - - - - 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 - - - -We assume the following in /etc/services - - -$ grep 9418 /etc/services -git 9418/tcp # Git Version Control System - - - - -Run git-daemon to serve /pub/scm from inetd. - - -$ grep git /etc/inetd.conf -git stream tcp nowait nobody \ - /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm -The actual configuration line should be on one line. - - - - -Run git-daemon to serve /pub/scm from xinetd. - - -$ cat /etc/xinetd.d/git-daemon -# default: off -# description: The git server offers access to git repositories -service git -{ - disable = no - type = UNLISTED - port = 9418 - socket_type = stream - wait = no - user = nobody - server = /usr/bin/git-daemon - server_args = --inetd --export-all --base-path=/pub/scm - log_on_failure += USERID -} -Check your xinetd(8) documentation and setup, this is from a Fedora system. -Others might be different. - - - - -Give push/pull only access to developers. - - -$ grep git /etc/passwd -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 -/usr/bin/git-shell - - - -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. - - - - -in many distributions /etc/shells needs to list what is used -as the login shell. - - - - - - - -CVS-style shared repository. - - -$ grep git /etc/group -git:x:9418:alice,bob,cindy,david -$ cd /home/devo.git -$ ls -l - 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 - -r-xr-xr-x 1 david git 3536 Dec 4 22:40 update -$ cat info/allowed-users -refs/heads/master alice\|cindy -refs/heads/doc-update bob -refs/tags/v[0-9]* david - - - -place the developers into the same git group. - - - - -and make the shared repository writable by the group. - - - - -use update-hook example by Carl from Documentation/howto/ -for branch policy control. - - - - -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 -dev$ ftp user@isp.example.com -ftp> cp -r .git /home/user/myproject.git - - - -make sure your info/refs and objects/info/packs are up-to-date - - - - -upload to public HTTP server hosted by your ISP. - - - - - - -
- - diff --git a/doc/source/en/TortoiseGit/git_doc/git-add.xml b/doc/source/en/TortoiseGit/git_doc/git-add.xml index 28ea2f18a..bd542c8d9 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-add.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-add.xml @@ -13,10 +13,10 @@ SYNOPSIS
-git add [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] - [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N] - [--refresh] [--ignore-errors] [--ignore-missing] [--] - [<filepattern>…] +git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] + [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] + [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] + [--] [<pathspec>…]
@@ -29,7 +29,7 @@ only part of the changes made to the working tree files applied, or remove paths that do not exist in the working tree anymore. The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus -after making any changes to the working directory, and before running +after making any changes to the working tree, and before running the commit command, you must use the add command to add any new or modified files to the index. This command can be performed multiple times before a commit. It only @@ -52,15 +52,21 @@ commit. -<filepattern>… +<pathspec>… Files to add content from. Fileglobs (e.g. *.c) can be given to add all matching files. Also a leading directory name (e.g. dir to add dir/file1 - and dir/file2) can be given to add all files in the - directory, recursively. + and dir/file2) can be given to update the index to + match the current state of the directory as a whole (e.g. + specifying dir will record not just a file dir/file1 + modified in the working tree, a file dir/file2 added to + the working tree, but also a file dir/file3 removed from + the working tree. Note that older versions of Git used + to ignore removed files; use --no-all option if you want + to add modified or new files but ignore removed ones. @@ -141,7 +147,10 @@ See Interactive mode for details. --e, --edit +-e + + +--edit @@ -165,16 +174,14 @@ apply to the index. See EDITING PATCHES below. - Only match <filepattern> against already tracked files in - the index rather than the working tree. That means that it - will never stage new files, but that it will stage modified - new contents of tracked files and that it will remove files - from the index if the corresponding files in the working tree - have been removed. + Update the index just where it already has an entry matching + <pathspec>. This removes as well as modifies index entries to + match the working tree, but adds no new files. -If no <filepattern> is given, default to "."; in other words, -update all tracked files in the current directory and its -subdirectories. +If no <pathspec> is given when -u option is used, all +tracked files in the entire working tree are updated (old versions +of Git used to limit the update to the current directory and its +subdirectories). @@ -184,13 +191,39 @@ subdirectories. --all + +--no-ignore-removal + + + + Update the index not only where the working tree has a file + matching <pathspec> but also where the index already has an + entry. This adds, modifies, and removes index entries to + match the working tree. + +If no <pathspec> is given when -A option is used, all +files in the entire working tree are updated (old versions +of Git used to limit the update to the current directory and its +subdirectories). + + + + +--no-all + + +--ignore-removal + - Like -u, but match <filepattern> against files in the - working tree in addition to the index. That means that it - will find new files as well as staging modified content and - removing files that are no longer in the working tree. + Update the index by adding new files that are unknown to the + index and files modified in the working tree, but ignore + files that have been removed from the working tree. This + option is a no-op when no <pathspec> is used. +This option is primarily to help users who are used to older +versions of Git, whose "git add <pathspec>…" was a synonym +for "git add --no-all <pathspec>…", i.e. ignored removed files. @@ -264,7 +297,7 @@ subdirectories. Configuration -The optional configuration variable core.excludesfile indicates a path to a +The optional configuration variable core.excludesFile indicates a path to a file containing patterns of file names to exclude from git-add, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to those in info/exclude. See . @@ -399,9 +432,9 @@ patch y - stage this hunk n - do not stage this hunk -q - quit; do not stage this hunk nor any of the remaining ones +q - quit; do not stage this hunk or any of the remaining ones a - stage this hunk and all later hunks in the file -d - do not stage this hunk nor any of the later hunks in the file +d - do not stage this hunk or any of the later hunks in the file g - select a hunk to go to / - search for a hunk matching the given regex j - leave this hunk undecided, see next undecided hunk @@ -414,7 +447,7 @@ e - manually edit the current hunk After deciding the fate for all hunks, if there is any hunk that was chosen, the index is updated with the selected hunks. You can omit having to type return here, by setting the configuration -variable interactive.singlekey to true. +variable interactive.singleKey to true. diff --git a/doc/source/en/TortoiseGit/git_doc/git-am.xml b/doc/source/en/TortoiseGit/git_doc/git-am.xml index 8ce12c26a..0b72d021f 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-am.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-am.xml @@ -13,12 +13,12 @@ SYNOPSIS
-git am [--signoff] [--keep] [--keep-cr | --no-keep-cr] [--utf8 | --no-utf8] - [--3way] [--interactive] [--committer-date-is-author-date] +git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] + [--[no-]3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] - [--scissors | --no-scissors] + [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>] [(<mbox> | <Maildir>)…] git am (--continue | --skip | --abort)
@@ -55,6 +55,7 @@ current branch. Add a Signed-off-by: line to the commit message, using the committer identity of yourself. + See the signoff option in for more information. @@ -83,10 +84,7 @@ current branch. ---keep-cr - - ---no-keep-cr +--[no-]keep-cr @@ -107,7 +105,8 @@ current branch. Remove everything in body before a scissors line (see - ). + ). Can be activated by default using + the mailinfo.scissors configuration variable. @@ -123,6 +122,33 @@ current branch. +-m + + +--message-id + + + + Pass the -m flag to git mailinfo (see ), + so that the Message-ID header is added to the commit message. + The am.messageid configuration variable can be used to specify + the default behaviour. + + + + + +--no-message-id + + + + Do not add the Message-ID header to the commit message. + no-message-id is useful to override am.messageid. + + + + + -q @@ -171,20 +197,22 @@ default. You can use --no-utf8 to override this. --3way + +--no-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 - available locally. + available locally. --no-3way can be used to override + am.threeWay configuration variable. For more information, + see am.threeWay in . ---ignore-date - - --ignore-space-change @@ -221,6 +249,19 @@ default. You can use --no-utf8 to override this. +--patch-format + + + + By default the command will try to detect the patch format + automatically. This option allows the user to bypass the automatic + detection and specify the patch format that the patch(es) should be + interpreted as. Valid formats are mbox, stgit, stgit-series and hg. + + + + + -i @@ -273,6 +314,21 @@ default. You can use --no-utf8 to override this. +-S[<keyid>] + + +--gpg-sign[=<keyid>] + + + + GPG-sign commits. The keyid argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. + + + + + --continue @@ -300,7 +356,7 @@ default. You can use --no-utf8 to override this. When a patch failure occurs, <msg> will be printed to the screen before exiting. This overrides the - standard message informing you to use --resolved + standard message informing you to use --continue or --skip to handle the failure. This is solely for internal use between git rebase and git am. @@ -367,7 +423,7 @@ skip the current patch by re-running the command with the --skip hand resolve the conflict in the working directory, and update the index file to bring it into a state that the patch should - have produced. Then run the command with the --resolved option. + have produced. Then run the command with the --continue option. @@ -381,6 +437,12 @@ commits, like running git am on the wrong branch or an erro commits that is more easily fixed by changing the mailbox (e.g. errors in the "From:" lines). + +HOOKS +This command can run applypatch-msg, pre-applypatch, +and post-applypatch hooks. See for more +information. + SEE ALSO . diff --git a/doc/source/en/TortoiseGit/git_doc/git-annotate.xml b/doc/source/en/TortoiseGit/git_doc/git-annotate.xml index 2d9a54631..3a57c532c 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-annotate.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-annotate.xml @@ -46,7 +46,7 @@ familiar command name for people coming from other SCM systems. Do not treat root commits as boundaries. This can also be - controlled via the blame.showroot config option. + controlled via the blame.showRoot config option. @@ -64,11 +64,17 @@ familiar command name for people coming from other SCM systems. -L <start>,<end> + +-L :<funcname> + - Annotate only the given line range. <start> and <end> can take - one of these forms: + Annotate only the given line range. May be specified multiple times. + Overlapping ranges are allowed. +<start> and <end> are optional. -L <start> or -L <start>, spans from +<start> to end of file. -L ,<end> spans from start of file to <end>. +<start> and <end> can take one of these forms: @@ -82,7 +88,10 @@ absolute line number (lines count from 1). /regex/ This form will use the first line matching the given -POSIX regex. If <end> is a regex, it will search +POSIX regex. If <start> is a regex, it will search from the end of +the previous -L range, if any, otherwise from the start of file. +If <start> is ^/regex/, it will search from the start of file. +If <end> is a regex, it will search starting at the line given by <start>. @@ -93,6 +102,12 @@ starting at the line given by <start>. of lines before or after the line given by <start>. +If :<funcname> is given in place of <start> and <end>, it is a +regular expression that denotes the range from the first funcname line +that matches <funcname>, up to the next funcname line. :<funcname> +searches from the end of the previous -L range, if any, otherwise +from the start of file. ^:<funcname> searches from the start of +file. @@ -209,17 +224,30 @@ of lines before or after the line given by <start>. - The value is one of the following alternatives: - {relative,local,default,iso,rfc,short}. If --date is not + Specifies the format used to output dates. If --date is not provided, the value of the blame.date config variable is used. If the blame.date config variable is also not set, the - iso format is used. For more information, See the discussion + iso format is used. For supported values, see the discussion of the --date option at . +--[no-]progress + + + + Progress status is reported on the standard error stream + by default when it is attached to a terminal. This flag + enables progress reporting even if not attached to a + terminal. Can't use --progress together with --porcelain + or --incremental. + + + + + -M|<num>| @@ -235,7 +263,7 @@ of lines before or after the line given by <start>. running extra passes of inspection. <num> is optional but it is the lower bound on the number of -alphanumeric characters that git must detect as moving/copying +alphanumeric characters that Git must detect as moving/copying within a file for it to associate those lines with the parent commit. The default value is 20. @@ -256,7 +284,7 @@ commit. The default value is 20. looks for copies from other files in any commit. <num> is optional but it is the lower bound on the number of -alphanumeric characters that git must detect as moving/copying +alphanumeric characters that Git must detect as moving/copying between files for it to associate those lines with the parent commit. And the default value is 40. If there are more than one -C options given, the <num> argument of the last -C will diff --git a/doc/source/en/TortoiseGit/git_doc/git-apply.xml b/doc/source/en/TortoiseGit/git_doc/git-apply.xml index 537f29007..e9e7ee9bd 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-apply.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-apply.xml @@ -17,19 +17,21 @@ [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached] - [--ignore-space-change | --ignore-whitespace ] + [--ignore-space-change | --ignore-whitespace] [--whitespace=(nowarn|warn|fix|error|error-all)] [--exclude=<path>] [--include=<path>] [--directory=<root>] - [--verbose] [<patch>…] + [--verbose] [--unsafe-paths] [<patch>…] DESCRIPTION Reads the supplied diff output (i.e. "a patch") and applies it to files. +When running from a subdirectory in a repository, patched paths +outside the directory are ignored. With the --index option the patch is also applied to the index, and with the --cached option the patch is only applied to the index. Without these options, the command applies the patch only to files, -and does not require them to be in a git repository. +and does not require them to be in a Git repository. This command applies the patch but does not create a commit. Use to create commits from patches generated by and/or received by email. @@ -368,7 +370,7 @@ behavior: fix outputs warnings for a few such errors, and applies the patch after fixing them (strip is a synonym --- the tool used to consider only trailing whitespace characters as errors, and the - fix involved stripping them, but modern gits do more). + fix involved stripping them, but modern Gits do more). @@ -440,6 +442,22 @@ can be applied to the file in the working tree modules/git-gui/git-gui running git apply --directory=modules/git-gui. + + +--unsafe-paths + + + + By default, a patch that affects outside the working area + (either a Git controlled working tree, or the current working + directory when "git apply" is used as a replacement of GNU + patch) is rejected as a mistake (or a mischief). + +When git apply is used as a "better GNU patch", the user can pass +the --unsafe-paths option to override this safety check. This option +has no effect when --index or --cached is in use. + + @@ -447,7 +465,7 @@ running git apply --directory=modules/git-gui. -apply.ignorewhitespace +apply.ignoreWhitespace diff --git a/doc/source/en/TortoiseGit/git_doc/git-archimport.xml b/doc/source/en/TortoiseGit/git_doc/git-archimport.xml index 63fbb61eb..3c179d784 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-archimport.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-archimport.xml @@ -8,7 +8,7 @@ NAME -git-archimport - Import an Arch repository into git +git-archimport - Import an Arch repository into Git SYNOPSIS @@ -40,25 +40,25 @@ 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. While git archimport will try to create sensible branch names for the -archives that it imports, it is also possible to specify git branch names -manually. To do so, write a git branch name after each <archive/branch> +archives that it imports, it is also possible to specify Git branch names +manually. To do so, write a Git branch name after each <archive/branch> parameter, separated by a colon. This way, you can shorten the Arch -branch names and convert Arch jargon to git jargon, for example mapping a +branch names and convert Arch jargon to Git jargon, for example mapping a "PROJECT--devo--VERSION" branch to "master". -Associating multiple Arch branches to one git branch is possible; the +Associating multiple Arch branches to one Git branch is possible; the result will make the most sense only if no commits are made to the first branch, after the second branch is created. Still, this is useful to convert Arch repositories that had been rotated periodically. MERGES -Patch merge data from Arch is used to mark merges in git as well. git +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 +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 +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. diff --git a/doc/source/en/TortoiseGit/git_doc/git-archive.xml b/doc/source/en/TortoiseGit/git_doc/git-archive.xml index 6ea0cc3dd..6fd1e44c7 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-archive.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-archive.xml @@ -14,7 +14,7 @@ SYNOPSIS
git archive [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] - [-o | --output=<file>] [--worktree-attributes] + [-o <file> | --output=<file>] [--worktree-attributes] [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> [<path>…]
@@ -106,7 +106,8 @@ comment. - Look for attributes in .gitattributes in working directory too. + Look for attributes in .gitattributes files in the working tree + as well (see ). @@ -128,7 +129,10 @@ comment. Instead of making a tar archive from the local repository, - retrieve a tar archive from a remote repository. + retrieve a tar archive from a remote repository. Note that the + remote repository may place restrictions on which sha1 + expressions may be allowed in <tree-ish>. See + for details. @@ -248,7 +252,7 @@ tar.<format>.remote - + ATTRIBUTES @@ -268,7 +272,7 @@ export-subst - If the attribute export-subst is set for a file then git will + If the attribute export-subst is set for a file then Git will expand several placeholders when adding this file to an archive. See for details. diff --git a/doc/source/en/TortoiseGit/git_doc/git-bisect.xml b/doc/source/en/TortoiseGit/git_doc/git-bisect.xml index 75671c4df..6bff1bc8a 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-bisect.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-bisect.xml @@ -8,7 +8,7 @@ NAME -git-bisect - Find by binary search the change that introduced a bug +git-bisect - Use binary search to find the commit that introduced a bug SYNOPSIS @@ -20,47 +20,57 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: -git bisect help -git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] -git bisect bad [<rev>] -git bisect good [<rev>...] +git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>] + [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] +git bisect (bad|new) [<rev>] +git bisect (good|old) [<rev>...] +git bisect terms [--term-good | --term-bad] git bisect skip [(<rev>|<range>)...] git bisect reset [<commit>] git bisect visualize git bisect replay <logfile> git bisect log -git bisect run <cmd>... -This command uses git rev-list --bisect 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. -
-Getting help -Use "git bisect" to get a short usage description, and "git bisect -help" or "git bisect -h" to get a long usage description. -
+git bisect run <cmd>... +git bisect help +This command uses a binary search algorithm to find which commit in +your project's history introduced a bug. You use it by first telling +it a "bad" commit that is known to contain the bug, and a "good" +commit that is known to be before the bug was introduced. Then git +bisect picks a commit between those two endpoints and asks you +whether the selected commit is "good" or "bad". It continues narrowing +down the range until it finds the exact commit that introduced the +change. +In fact, git bisect can be used to find the commit that changed +any property of your project; e.g., the commit that fixed a bug, or +the commit that caused a benchmark's performance to improve. To +support this more general usage, the terms "old" and "new" can be used +in place of "good" and "bad", or you can choose your own terms. See +section "Alternate terms" below for more information.
Basic bisect commands: start, bad, good -Using the Linux kernel tree as an example, basic use of the bisect -command is as follows: +As an example, suppose you are trying to find the commit that broke a +feature that was known to work in version v2.6.13-rc2 of your +project. You start a bisect session as follows: $ 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 have specified at least one bad and one good version, the -command bisects the revision tree and outputs something similar to -the following: -Bisecting: 675 revisions left to test after this -The state in the middle of the set of revisions is then checked out. -You would now compile that kernel and boot it. If the booted kernel -works correctly, you would then issue the following command: -$ git bisect good # this one is good -The output of this command would be something similar to the following: -Bisecting: 337 revisions left to test after this -You keep repeating this process, compiling the tree, testing it, and -depending on whether it is good or bad issuing the command "git bisect good" -or "git bisect bad" to ask for the next bisection. -Eventually there will be no more revisions left to bisect, and you -will have been left with the first bad kernel revision in "refs/bisect/bad". +$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 is known to be good +Once you have specified at least one bad and one good commit, git +bisect selects a commit in the middle of that range of history, +checks it out, and outputs something similar to the following: +Bisecting: 675 revisions left to test after this (roughly 10 steps) +You should now compile the checked-out version and test it. If that +version works correctly, type +$ git bisect good +If that version is broken, type +$ git bisect bad +Then git bisect will respond with something like +Bisecting: 337 revisions left to test after this (roughly 9 steps) +Keep repeating the process: compile the tree, test it, and depending +on whether it is good or bad run git bisect good or git bisect bad +to ask for the next commit that needs testing. +Eventually there will be no more revisions left to inspect, and the +command will print out a description of the first bad commit. The +reference refs/bisect/bad will be left pointing at that commit.
Bisect reset @@ -73,9 +83,52 @@ that, as it cleans up the old bisection state.) With an optional argument, you can return to a different commit instead: $ git bisect reset <commit> -For example, git bisect reset HEAD will leave you on the current -bisection commit and avoid switching commits at all, while git bisect -reset bisect/bad will check out the first bad revision. +For example, git bisect reset bisect/bad will check out the first +bad revision, while git bisect reset HEAD will leave you on the +current bisection commit and avoid switching commits at all. +
+
+Alternate terms +Sometimes you are not looking for the commit that introduced a +breakage, but rather for a commit that caused a change between some +other "old" state and "new" state. For example, you might be looking +for the commit that introduced a particular fix. Or you might be +looking for the first commit in which the source-code filenames were +finally all converted to your company's naming standard. Or whatever. +In such cases it can be very confusing to use the terms "good" and +"bad" to refer to "the state before the change" and "the state after +the change". So instead, you can use the terms "old" and "new", +respectively, in place of "good" and "bad". (But note that you cannot +mix "good" and "bad" with "old" and "new" in a single session.) +In this more general usage, you provide git bisect with a "new" +commit has some property and an "old" commit that doesn't have that +property. Each time git bisect checks out a commit, you test if that +commit has the property. If it does, mark the commit as "new"; +otherwise, mark it as "old". When the bisection is done, git bisect +will report which commit introduced the property. +To use "old" and "new" instead of "good" and bad, you must run git +bisect start without commits as argument and then run the following +commands to add the commits: +git bisect old [<rev>] +to indicate that a commit was before the sought change, or +git bisect new [<rev>...] +to indicate that it was after. +To get a reminder of the currently used terms, use +git bisect terms +You can get just the old (respectively new) term with git bisect term +--term-old or git bisect term --term-good. +If you would like to use your own terms instead of "bad"/"good" or +"new"/"old", you can choose any names you like (except existing bisect +subcommands like reset, start, …) by starting the +bisection using +git bisect start --term-old <term-old> --term-new <term-new> +For example, if you are looking for a commit that introduced a +performance regression, you might use +git bisect start --term-old fast --term-new slow +Or if you are looking for the commit that fixed a bug, you might use +git bisect start --term-new fixed --term-old broken +Then, use git bisect <term-old> and git bisect <term-new> instead +of git bisect good and git bisect bad to mark commits.
Bisect visualize @@ -84,7 +137,7 @@ command during the bisection process: $ git bisect visualize view may also be used as a synonym for visualize. If the DISPLAY environment variable is not set, git log is used -instead. You can also give command line options such as -p and +instead. You can also give command-line options such as -p and --stat. $ git bisect view --stat
@@ -102,14 +155,14 @@ $ git bisect replay that-file
Avoiding testing a commit -If, in the middle of a bisect session, you know that the next suggested -revision 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 nearby commit and try that instead. +If, in the middle of a bisect session, you know that the suggested +revision is not a good one to test (e.g. it fails to build and you +know that the failure does not have anything to do with the bug you +are chasing), you can manually select a nearby commit and test that +one instead. For example: $ git bisect good/bad # previous round was good or bad. -Bisecting: 337 revisions left to test after this +Bisecting: 337 revisions left to test after this (roughly 9 steps) $ git bisect visualize # oops, that is uninteresting. $ git reset --hard HEAD~3 # try 3 revisions before what # was suggested @@ -118,21 +171,22 @@ the revision as good or bad in the usual manner.
Bisect skip -Instead of choosing by yourself a nearby commit, you can ask git -to do it for you by issuing the command: +Instead of choosing a nearby commit by yourself, you can ask Git to do +it for you by issuing the command: $ git bisect skip # Current version cannot be tested -But git may eventually be unable to tell the first bad commit among -a bad commit and one or more skipped commits. -You can even skip a range of commits, instead of just one commit, -using the "<commit1>..<commit2>" notation. For example: +However, if you skip a commit adjacent to the one you are looking for, +Git will be unable to tell exactly which of those commits was the +first bad one. +You can also skip a range of commits, instead of just one commit, +using range notation. For example: $ git bisect skip v2.5..v2.6 This tells the bisect process that no commit after v2.5, up to and including v2.6, should be tested. Note that if you also want to skip the first commit of the range you would issue the command: $ git bisect skip v2.5 v2.5..v2.6 -This tells the bisect process that the commits between v2.5 included -and v2.6 included should be skipped. +This tells the bisect process that the commits between v2.5 and +v2.6 (inclusive) should be skipped.
Cutting down bisection by giving more parameters to bisect start @@ -152,21 +206,21 @@ the bad commit when issuing the bisect start command:If you have a script that can tell if the current source code is good or bad, you can bisect by issuing the command: $ git bisect run my_script arguments -Note that the script (my_script in the above example) should -exit with code 0 if the current source code is good, and exit with a -code between 1 and 127 (inclusive), except 125, if the current -source code is bad. +Note that the script (my_script in the above example) should exit +with code 0 if the current source code is good/old, and exit with a +code between 1 and 127 (inclusive), except 125, if the current source +code is bad/new. Any other exit code will abort the bisect process. It should be noted -that a program that terminates via "exit(-1)" leaves $? = 255, (see the -exit(3) manual page), as the value is chopped with "& 0377". +that a program that terminates via exit(-1) leaves $? = 255, (see the +exit(3) manual page), as the value is chopped with & 0377. The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current revision will be skipped (see git bisect skip above). 125 was chosen as the highest sensible value to use for this purpose, because 126 and 127 are used by POSIX shells to signal specific error status (127 is for -command not found, 126 is for command found but not executable---these +command not found, 126 is for command found but not executable--these details do not matter, as they are normal errors in the script, as far as -"bisect run" is concerned). +bisect run is concerned). You may often find that during a bisect session you want to have temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a header file, or "revision that does not have this commit needs this @@ -177,7 +231,7 @@ next revision to test, the script can apply the patch before compiling, run the real test, and afterwards decide if the revision (possibly with the needed patch) passed the test and then rewind the tree to the pristine state. Finally the script should exit -with the status of the real test to let the "git bisect run" command loop +with the status of the real test to let the git bisect run command loop determine the eventual outcome of the bisect session.
@@ -207,14 +261,16 @@ does not require a checked out tree. Automatically bisect a broken build between v1.2 and HEAD: $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good -$ git bisect run make # "make" builds the app +$ git bisect run make # "make" builds the app +$ git bisect reset # quit the bisect session Automatically bisect a test failure between origin and HEAD: $ git bisect start HEAD origin -- # HEAD is bad, origin is good -$ git bisect run make test # "make test" builds and tests +$ git bisect run make test # "make test" builds and tests +$ git bisect reset # quit the bisect session @@ -225,12 +281,13 @@ Automatically bisect a broken test case: make || exit 125 # this skips broken builds ~/check_test_case.sh # does the test case pass? $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 -$ git bisect run ~/test.sh -Here we use a "test.sh" custom script. In this script, if "make" +$ git bisect run ~/test.sh +$ git bisect reset # quit the bisect session +Here we use a test.sh custom script. In this script, if make fails, we skip the current commit. -"check_test_case.sh" should "exit 0" if the test case passes, -and "exit 1" otherwise. -It is safer if both "test.sh" and "check_test_case.sh" are +check_test_case.sh should exit 0 if the test case passes, +and exit 1 otherwise. +It is safer if both test.sh and check_test_case.sh are outside the repository to prevent interactions between the bisect, make and test processes and the scripts. @@ -271,7 +328,8 @@ use git cherry-pick instead of git merge $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 -$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" +$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" +$ git bisect reset # quit the bisect session This shows that you can do without a run script if you write the test on a single line. @@ -286,12 +344,31 @@ $ git bisect run sh -c ' git pack-objects --stdout >/dev/null <tmp.$$ rc=$? rm -f tmp.$$ - test $rc = 0' + test $rc = 0' + +$ git bisect reset # quit the bisect session In this case, when git bisect run finishes, bisect/bad will refer to a commit that has at least one parent whose reachable graph is fully traversable in the sense required by git pack objects. + + +Look for a fix instead of a regression in the code + +$ git bisect start +$ git bisect new HEAD # current commit is marked as new +$ git bisect old HEAD~10 # the tenth commit from now is marked as old +or: + +$ git bisect start --term-old broken --term-new fixed +$ git bisect fixed +$ git bisect broken HEAD~10 +
+Getting help +Use git bisect to get a short usage description, and git bisect +help or git bisect -h to get a long usage description. +
 SEE ALSO diff --git a/doc/source/en/TortoiseGit/git_doc/git-blame.xml b/doc/source/en/TortoiseGit/git_doc/git-blame.xml index c0244f756..b2aec6995 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-blame.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-blame.xml @@ -13,16 +13,18 @@ SYNOPSIS
-git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L n,m] - [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--abbrev=<n>] - [<rev> | --contents <file> | --reverse <rev>] [--] <file> +git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] + [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] + [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] + [--] <file>
DESCRIPTION Annotates each line in the given file with information from the revision which last modified the line. Optionally, start annotating from the given revision. -The command can also limit the range of lines annotated. +When specified one or more times, -L restricts annotation to the requested +lines. The origin of lines is automatically followed across whole-file renames (currently there is no option to turn the rename-following off). To follow lines moved from one file to another, or to follow @@ -31,11 +33,12 @@ lines that were copied and pasted from another file, etc., see the The report does not tell you anything about lines which have been deleted or replaced; you need to use a tool such as git diff or the "pickaxe" interface briefly mentioned in the following paragraph. -Apart from supporting file annotation, git also supports searching the +Apart from supporting file annotation, Git also supports searching the development history for when a code snippet occurred in a change. This makes it possible to track when a code snippet was added to a file, moved or copied between files, and eventually deleted or replaced. It works by searching for -a text string in the diff. A small example: +a text string in the diff. A small example of the pickaxe interface +that searches for blame_usage: $ git log --pretty=oneline -S'blame_usage' 5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file> ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output @@ -61,7 +64,7 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output Do not treat root commits as boundaries. This can also be - controlled via the blame.showroot config option. + controlled via the blame.showRoot config option. @@ -79,11 +82,17 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output -L <start>,<end> + +-L :<funcname> + - Annotate only the given line range. <start> and <end> can take - one of these forms: + Annotate only the given line range. May be specified multiple times. + Overlapping ranges are allowed. +<start> and <end> are optional. -L <start> or -L <start>, spans from +<start> to end of file. -L ,<end> spans from start of file to <end>. +<start> and <end> can take one of these forms: @@ -97,7 +106,10 @@ absolute line number (lines count from 1). /regex/ This form will use the first line matching the given -POSIX regex. If <end> is a regex, it will search +POSIX regex. If <start> is a regex, it will search from the end of +the previous -L range, if any, otherwise from the start of file. +If <start> is ^/regex/, it will search from the start of file. +If <end> is a regex, it will search starting at the line given by <start>. @@ -108,6 +120,12 @@ starting at the line given by <start>. of lines before or after the line given by <start>. +If :<funcname> is given in place of <start> and <end>, it is a +regular expression that denotes the range from the first funcname line +that matches <funcname>, up to the next funcname line. :<funcname> +searches from the end of the previous -L range, if any, otherwise +from the start of file. ^:<funcname> searches from the start of +file. @@ -224,17 +242,30 @@ of lines before or after the line given by <start>. - The value is one of the following alternatives: - {relative,local,default,iso,rfc,short}. If --date is not + Specifies the format used to output dates. If --date is not provided, the value of the blame.date config variable is used. If the blame.date config variable is also not set, the - iso format is used. For more information, See the discussion + iso format is used. For supported values, see the discussion of the --date option at . +--[no-]progress + + + + Progress status is reported on the standard error stream + by default when it is attached to a terminal. This flag + enables progress reporting even if not attached to a + terminal. Can't use --progress together with --porcelain + or --incremental. + + + + + -M|<num>| @@ -250,7 +281,7 @@ of lines before or after the line given by <start>. running extra passes of inspection. <num> is optional but it is the lower bound on the number of -alphanumeric characters that git must detect as moving/copying +alphanumeric characters that Git must detect as moving/copying within a file for it to associate those lines with the parent commit. The default value is 20. @@ -271,7 +302,7 @@ commit. The default value is 20. looks for copies from other files in any commit. <num> is optional but it is the lower bound on the number of -alphanumeric characters that git must detect as moving/copying +alphanumeric characters that Git must detect as moving/copying between files for it to associate those lines with the parent commit. And the default value is 40. If there are more than one -C options given, the <num> argument of the last -C will @@ -362,6 +393,8 @@ take effect. Show the author email instead of author name (Default: off). + This can also be controlled via the blame.showEmail config + option. @@ -424,7 +457,7 @@ at least once for each commit: the author name ("author"), email ("author-mail"), time - ("author-time"), and timezone ("author-tz"); similarly + ("author-time"), and time zone ("author-tz"); similarly for committer. @@ -458,7 +491,9 @@ sort | uniq -c | sort -rn SPECIFYING RANGES Unlike git blame and git annotate in older versions of git, the extent of the annotation can be limited to both line ranges and revision -ranges. When you are interested in finding the origin for +ranges. The -L option, which limits annotation to a range of lines, may be +specified multiple times. +When you are interested in finding the origin for lines 40-60 for file foo, you can use the -L option like so (they mean the same thing -- both ask for 21 lines starting at line 40): @@ -533,7 +568,8 @@ commit commentary), a blame viewer will not care. MAPPING AUTHORS If the file .mailmap exists at the toplevel of the repository, or at -the location pointed to by the mailmap.file configuration option, it +the location pointed to by the mailmap.file or mailmap.blob +configuration options, it is used to map author and committer names and email addresses to canonical real names and email addresses. In the simple form, each line in the file consists of the canonical diff --git a/doc/source/en/TortoiseGit/git_doc/git-branch.xml b/doc/source/en/TortoiseGit/git_doc/git-branch.xml index 1142714c2..1013a02f1 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-branch.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-branch.xml @@ -16,7 +16,8 @@ git branch [--color[=<when>] | --no-color] [-r | -a] [--list] [-v [--abbrev=<length> | --no-abbrev]] [--column[=<options>] | --no-column] - [(--merged | --no-merged | --contains) [<commit>]] [<pattern>…] + [(--merged | --no-merged | --contains) [<commit>]] [--sort=<key>] + [--points-at <object>] [<pattern>…] git branch [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] git branch (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] git branch --unset-upstream [<branchname>] @@ -27,13 +28,15 @@ DESCRIPTION -With no arguments, existing branches are listed and the current branch will -be highlighted with an asterisk. Option -r causes the remote-tracking -branches to be listed, and option -a shows both. This list mode is also -activated by the --list option (see below). -<pattern> restricts the output to matching branches, the pattern is a shell -wildcard (i.e., matched using fnmatch(3)). -Multiple patterns may be given; if any of them matches, the branch is shown. +If --list is given, or if there are no non-option arguments, existing +branches are listed; the current branch will be highlighted with an +asterisk. Option -r causes the remote-tracking branches to be listed, +and option -a shows both local and remote branches. If a <pattern> +is given, it is used as a shell wildcard to restrict the output to +matching branches. If multiple patterns are given, a branch is shown if +it matches any of the patterns. Note that when providing a +<pattern>, you must use --list; otherwise the command is interpreted +as branch creation. With --contains, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the named commit). With --merged, only branches merged into the named @@ -46,10 +49,11 @@ which points to the current HEAD, or <start-point> if Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout <newbranch>" to switch to the new branch. -When a local branch is started off a remote-tracking branch, git sets up the -branch so that git pull will appropriately merge from +When a local branch is started off a remote-tracking branch, Git sets up the +branch (specifically the branch.<name>.remote and branch.<name>.merge +configuration entries) so that git pull will appropriately merge from the remote-tracking branch. This behavior may be changed via the global -branch.autosetupmerge configuration flag. That setting can be +branch.autoSetupMerge configuration flag. That setting can be overridden by using the --track and --no-track options, and changed later using git branch --set-upstream-to. With a -m or -M option, <oldbranch> will be renamed to <newbranch>. @@ -90,7 +94,7 @@ way to clean up all obsolete remote-tracking branches. - Delete a branch irrespective of its merged status. + Shortcut for --delete --force. @@ -122,6 +126,10 @@ way to clean up all obsolete remote-tracking branches. Reset <branchname> to <startpoint> if <branchname> exists already. Without -f git branch refuses to change an existing branch. + In combination with -d (or --delete), allow deleting the + branch irrespective of its merged status. In combination with + -m (or --move), allow renaming the branch even if the new + branch name already exists. @@ -144,7 +152,7 @@ way to clean up all obsolete remote-tracking branches. - Move/rename a branch even if the new branch name already exists. + Shortcut for --move --force. @@ -290,7 +298,8 @@ way to clean up all obsolete remote-tracking branches. - When creating a new branch, set up configuration to mark the + When creating a new branch, set up branch.<name>.remote and + branch.<name>.merge configuration entries to mark the start-point branch as "upstream" from the new branch. This configuration will tell git to show the relationship between the two branches in git status and git branch -v. Furthermore, @@ -298,7 +307,7 @@ way to clean up all obsolete remote-tracking branches. upstream when the new branch is checked out. This behavior is the default when the start point is a remote-tracking branch. -Set the branch.autosetupmerge configuration variable to false if you +Set the branch.autoSetupMerge configuration variable to false if you want git checkout and git branch to always behave as if --no-track were given. Set it to always if you want this behavior when the start-point is either a local or remote-tracking branch. @@ -311,7 +320,7 @@ start-point is either a local or remote-tracking branch. Do not set up "upstream" configuration, even if the - branch.autosetupmerge configuration variable is true. + branch.autoSetupMerge configuration variable is true. @@ -361,7 +370,9 @@ start-point is either a local or remote-tracking branch. Open an editor and edit the text to explain what the branch is - for, to be used by various other commands (e.g. request-pull). + for, to be used by various other commands (e.g. format-patch, + request-pull, and merge (if enabled)). Multi-line explanations + may be used. @@ -372,7 +383,7 @@ start-point is either a local or remote-tracking branch. Only list branches which contain the specified commit (HEAD - if not specified). + if not specified). Implies --list. @@ -383,7 +394,7 @@ start-point is either a local or remote-tracking branch. Only list branches whose tips are reachable from the - specified commit (HEAD if not specified). + specified commit (HEAD if not specified). Implies --list. @@ -394,7 +405,7 @@ start-point is either a local or remote-tracking branch. Only list branches whose tips are not reachable from the - specified commit (HEAD if not specified). + specified commit (HEAD if not specified). Implies --list. @@ -444,6 +455,33 @@ start-point is either a local or remote-tracking branch. + + +--sort=<key> + + + + Sort based on the key given. Prefix - to sort in descending + order of the value. You may use the --sort=<key> option + multiple times, in which case the last key becomes the primary + key. The keys supported are the same as those in git + for-each-ref. Sort order defaults to sorting based on the + full refname (including refs/... prefix). This lists + detached HEAD (if present) first, then local branches and + finally remote-tracking branches. + + + + + +--points-at <object> + + + + Only list branches of the given object. + + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-bundle.xml b/doc/source/en/TortoiseGit/git_doc/git-bundle.xml index 1944f50c0..b2946a2da 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-bundle.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-bundle.xml @@ -23,8 +23,8 @@ DESCRIPTION Some workflows require that one or more branches of development on one machine be replicated on another machine, but the two machines cannot -be directly connected, and therefore the interactive git protocols (git, -ssh, rsync, http) cannot be used. This command provides support for +be directly connected, and therefore the interactive Git protocols (git, +ssh, http) cannot be used. This command provides support for git fetch and git pull to operate by packaging objects and references in an archive at the originating machine, then importing those into another repository using git fetch and git pull @@ -151,11 +151,10 @@ with an incremental bundle: machineA$ cd R1 machineA$ git bundle create file.bundle master machineA$ git tag -f lastR2bundle master -Then you transfer file.bundle to the target machine B. If you are creating -the repository on machine B, then you can clone from the bundle as if it -were a remote repository instead of creating an empty repository and then -pulling or fetching objects from the bundle: -machineB$ git clone /home/me/tmp/file.bundle R2 +Then you transfer file.bundle to the target machine B. Because this +bundle does not require any existing object to be extracted, you can +create a new repository on machine B by cloning from it: +machineB$ git clone -b master /home/me/tmp/file.bundle R2 This will define a remote called "origin" in the resulting repository that lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will have an entry like this: diff --git a/doc/source/en/TortoiseGit/git_doc/git-cat-file.xml b/doc/source/en/TortoiseGit/git_doc/git-cat-file.xml index 9b97f846a..4f1d0afbd 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-cat-file.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-cat-file.xml @@ -13,8 +13,8 @@ SYNOPSIS
-git cat-file (-t | -s | -e | -p | <type> | --textconv ) <object> -git cat-file (--batch | --batch-check) < <list-of-objects> +git cat-file (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv ) <object> +git cat-file (--batch | --batch-check) [--follow-symlinks]
@@ -24,7 +24,7 @@ the repository. The type is required unless -t or -s is used to find the object size, or --textconv is used (which implies type "blob"). In the second form, a list of objects (separated by linefeeds) is provided on -stdin, and the SHA1, type, and size of each object is printed on stdout. +stdin, and the SHA-1, type, and size of each object is printed on stdout. OPTIONS @@ -106,7 +106,7 @@ stdin, and the SHA1, type, and size of each object is printed on stdout. Show the content as transformed by a textconv filter. In this case, - <object> has be of the form <treeish>:<path>, or :<path> in order + <object> has be of the form <tree-ish>:<path>, or :<path> in order to apply the filter to the content recorded in the index at <path>. @@ -115,10 +115,14 @@ stdin, and the SHA1, type, and size of each object is printed on stdout. --batch + +--batch=<format> + - Print the SHA1, type, size, and contents of each object provided on - stdin. May not be combined with any other options or arguments. + Print object information and contents for each object provided + on stdin. May not be combined with any other options or arguments. + See the section BATCH OUTPUT below for details. @@ -126,13 +130,97 @@ stdin, and the SHA1, type, and size of each object is printed on stdout. --batch-check + +--batch-check=<format> + + + + Print object information for each object provided on stdin. May + not be combined with any other options or arguments. See the + section BATCH OUTPUT below for details. + + + + + +--batch-all-objects + - Print the SHA1, type, and size of each object provided on stdin. May not - be combined with any other options or arguments. + Instead of reading a list of objects on stdin, perform the + requested batch operation on all objects in the repository and + any alternate object stores (not just reachable objects). + Requires --batch or --batch-check be specified. Note that + the objects are visited in order sorted by their hashes. + + +--buffer + + + + Normally batch output is flushed after each object is output, so + that a process can interactively read and write from + cat-file. With this option, the output uses normal stdio + buffering; this is much more efficient when invoking + --batch-check on a large number of objects. + + + + + +--allow-unknown-type + + + + Allow -s or -t to query broken/corrupt objects of unknown type. + + + + + +--follow-symlinks + + + + With --batch or --batch-check, follow symlinks inside the + repository when requesting objects with extended SHA-1 + expressions of the form tree-ish:path-in-tree. Instead of + providing output about the link itself, provide output about + the linked-to object. If a symlink points outside the + tree-ish (e.g. a link to /foo or a root-level link to ../foo), + the portion of the link which is outside the tree will be + printed. + +This option does not (currently) work correctly when an object in the +index is specified (e.g. :link instead of HEAD:link) rather than +one in the tree. +This option cannot (currently) be used unless --batch or +--batch-check is used. +For example, consider a git repository containing: +f: a file containing "hello\n" +link: a symlink to f +dir/link: a symlink to ../f +plink: a symlink to ../f +alink: a symlink to /etc/passwd +For a regular file f, echo HEAD:f | git cat-file --batch would print +ce013625030ba8dba906f756967f9e9ca394464a blob 6 +And echo HEAD:link | git cat-file --batch --follow-symlinks would +print the same thing, as would HEAD:dir/link, as they both point at +HEAD:f. +Without --follow-symlinks, these would print data about the symlink +itself. In the case of HEAD:link, you would see +4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1 +Both plink and alink point outside the tree, so they would +respectively print: +symlink 4 +../f +symlink 11 +/etc/passwd + + @@ -143,16 +231,136 @@ stdin, and the SHA1, type, and size of each object is printed on stdout.If -p is specified, the contents of <object> are pretty-printed. If <type> is specified, the raw (though uncompressed) contents of the <object> will be returned. -If --batch is specified, output of the following form is printed for each -object specified on stdin: + + +BATCH OUTPUT +If --batch or --batch-check is given, cat-file will read objects +from stdin, one per line, and print information about them. By default, +the whole line is considered as an object, as if it were fed to +. +You can specify the information shown for each object by using a custom +<format>. The <format> is copied literally to stdout for each +object, with placeholders of the form %(atom) expanded, followed by a +newline. The available atoms are: + + + +objectname + + + + The 40-hex object name of the object. + + + + + +objecttype + + + + The type of of the object (the same as cat-file -t reports). + + + + + +objectsize + + + + The size, in bytes, of the object (the same as cat-file -s + reports). + + + + + +objectsize:disk + + + + The size, in bytes, that the object takes up on disk. See the + note about on-disk sizes in the CAVEATS section below. + + + + + +deltabase + + + + If the object is stored as a delta on-disk, this expands to the + 40-hex sha1 of the delta base object. Otherwise, expands to the + null sha1 (40 zeroes). See CAVEATS below. + + + + + +rest + + + + If this atom is used in the output string, input lines are split + at the first whitespace boundary. All characters before that + whitespace are considered to be the object name; characters + after that first run of whitespace (i.e., the "rest" of the + line) are output in place of the %(rest) atom. + + + + +If no format is specified, the default format is %(objectname) +%(objecttype) %(objectsize). +If --batch is specified, the object information is followed by the +object contents (consisting of %(objectsize) bytes), followed by a +newline. +For example, --batch without a custom format would produce: <sha1> SP <type> SP <size> LF <contents> LF -If --batch-check is specified, output of the following form is printed for -each object specified on stdin: -<sha1> SP <type> SP <size> LF -For both --batch and --batch-check, output of the following form is printed -for each object specified on stdin that does not exist in the repository: +Whereas --batch-check='%(objectname) %(objecttype)' would produce: +<sha1> SP <type> LF +If a name is specified on stdin that cannot be resolved to an object in +the repository, then cat-file will ignore any custom format and print: <object> SP missing LF +If --follow-symlinks is used, and a symlink in the repository points +outside the repository, then cat-file will ignore any custom format +and print: +symlink SP <size> LF +<symlink> LF +The symlink will either be absolute (beginning with a /), or relative +to the tree root. For instance, if dir/link points to ../../foo, then +<symlink> will be ../foo. <size> is the size of the symlink in bytes. +If --follow-symlinks is used, the following error messages will be +displayed: +<object> SP missing LF +is printed when the initial symlink requested does not exist. +dangling SP <size> LF +<object> LF +is printed when the initial symlink exists, but something that +it (transitive-of) points to does not. +loop SP <size> LF +<object> LF +is printed for symlink loops (or any symlinks that +require more than 40 link resolutions to resolve). +notdir SP <size> LF +<object> LF +is printed when, during symlink resolution, a file is used as a +directory name. + + +CAVEATS +Note that the sizes of objects on disk are reported accurately, but care +should be taken in drawing conclusions about which refs or objects are +responsible for disk usage. The size of a packed non-delta object may be +much larger than the size of objects which delta against it, but the +choice of which object is the base and which is the delta is arbitrary +and is subject to change during a repack. +Note also that multiple copies of an object may be present in the object +database; in this case, it is undefined which copy's size or delta base +will be reported. GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-check-attr.xml b/doc/source/en/TortoiseGit/git_doc/git-check-attr.xml index 5446509e8..97421e815 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-check-attr.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-check-attr.xml @@ -14,7 +14,7 @@ SYNOPSIS
git check-attr [-a | --all | attr…] [--] pathname… -git check-attr --stdin [-z] [-a | --all | attr…] < <list-of-paths> +git check-attr --stdin [-z] [-a | --all | attr…]
@@ -53,7 +53,8 @@ - Read file names from stdin instead of from the command-line. + Read pathnames from the standard input, one per line, + instead of from the command-line. @@ -63,8 +64,9 @@ - Only meaningful with --stdin; paths are separated with a - NUL character instead of a linefeed character. + The output format is modified to be machine-parseable. + If --stdin is also given, input paths are separated + with a NUL character instead of a linefeed character. @@ -88,6 +90,8 @@ pathnames. OUTPUT The output is of the form: <path> COLON SP <attribute> COLON SP <info> LF +unless -z is in effect, in which case NUL is used as delimiter: +<path> NUL <attribute> NUL <info> NUL <path> is the path of a file being queried, <attribute> is an attribute being queried and <info> can be either: @@ -132,6 +136,10 @@ when a value has been assigned to the attribute. +Buffering happens as documented under the GIT_FLUSH option in +. The caller is responsible for avoiding deadlocks +caused by overfilling an input buffer or reading from an empty output +buffer. EXAMPLES diff --git a/doc/source/en/TortoiseGit/git_doc/git-check-ignore.xml b/doc/source/en/TortoiseGit/git_doc/git-check-ignore.xml new file mode 100644 index 000000000..0c6340f36 --- /dev/null +++ b/doc/source/en/TortoiseGit/git_doc/git-check-ignore.xml @@ -0,0 +1,185 @@ + + + + + git-check-ignore(1) + +git-check-ignore(1) + + +NAME +git-check-ignore - Debug gitignore / exclude files + + +SYNOPSIS +
+git check-ignore [options] pathname… +git check-ignore [options] --stdin +
+ + +DESCRIPTION +For each pathname given via the command-line or from a file via +--stdin, check whether the file is excluded by .gitignore (or other +input files to the exclude mechanism) and output the path if it is +excluded. +By default, tracked files are not shown at all since they are not +subject to exclude rules; but see --no-index. + + +OPTIONS + + + +-q, --quiet + + + + Don't output anything, just set exit status. This is only + valid with a single pathname. + + + + + +-v, --verbose + + + + Also output details about the matching pattern (if any) + for each given pathname. For precedence rules within and + between exclude sources, see . + + + + + +--stdin + + + + Read pathnames from the standard input, one per line, + instead of from the command-line. + + + + + +-z + + + + The output format is modified to be machine-parseable (see + below). If --stdin is also given, input paths are separated + with a NUL character instead of a linefeed character. + + + + + +-n, --non-matching + + + + Show given paths which don't match any pattern. This only + makes sense when --verbose is enabled, otherwise it would + not be possible to distinguish between paths which match a + pattern and those which don't. + + + + + +--no-index + + + + Don't look in the index when undertaking the checks. This can + be used to debug why a path became tracked by e.g. git add . + and was not ignored by the rules as expected by the user or when + developing patterns including negation to match a path previously + added with git add -f. + + + + + + +OUTPUT +By default, any of the given pathnames which match an ignore pattern +will be output, one per line. If no pattern matches a given path, +nothing will be output for that path; this means that path will not be +ignored. +If --verbose is specified, the output is a series of lines of the form: +<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname> +<pathname> is the path of a file being queried, <pattern> is the +matching pattern, <source> is the pattern's source file, and <linenum> +is the line number of the pattern within that source. If the pattern +contained a ! prefix or / suffix, it will be preserved in the +output. <source> will be an absolute path when referring to the file +configured by core.excludesFile, or relative to the repository root +when referring to .git/info/exclude or a per-directory exclude file. +If -z is specified, the pathnames in the output are delimited by the +null character; if --verbose is also specified then null characters +are also used instead of colons and hard tabs: +<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL> +If -n or --non-matching are specified, non-matching pathnames will +also be output, in which case all fields in each output record except +for <pathname> will be empty. This can be useful when running +non-interactively, so that files can be incrementally streamed to +STDIN of a long-running check-ignore process, and for each of these +files, STDOUT will indicate whether that file matched a pattern or +not. (Without this option, it would be impossible to tell whether the +absence of output for a given file meant that it didn't match any +pattern, or that the output hadn't been generated yet.) +Buffering happens as documented under the GIT_FLUSH option in +. The caller is responsible for avoiding deadlocks +caused by overfilling an input buffer or reading from an empty output +buffer. + + +EXIT STATUS + + + +0 + + + + One or more of the provided paths is ignored. + + + + + +1 + + + + None of the provided paths are ignored. + + + + + +128 + + + + A fatal error was encountered. + + + + + + +SEE ALSO + + + + + +GIT +Part of the suite + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-shortlog.xml b/doc/source/en/TortoiseGit/git_doc/git-check-mailmap.xml similarity index 50% copy from doc/source/en/TortoiseGit/git_doc/git-shortlog.xml copy to doc/source/en/TortoiseGit/git_doc/git-check-mailmap.xml index eb3dcc1ef..d3b9e7888 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-shortlog.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-check-mailmap.xml @@ -1,124 +1,55 @@ - - git-shortlog(1) + + git-check-mailmap(1) -git-shortlog(1) +git-check-mailmap(1) - + NAME -git-shortlog - Summarize git log output +git-check-mailmap - Show canonical names and email addresses of contacts - + SYNOPSIS
-git log --pretty=short | git shortlog [-h] [-n] [-s] [-e] [-w] -git shortlog [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] <commit>… +git check-mailmap [options] <contact>…
- + DESCRIPTION -Summarizes git log output in a format suitable for inclusion -in release announcements. Each commit will be grouped by author and title. -Additionally, "[PATCH]" will be stripped from the commit description. -If no revisions are passed on the command line and either standard input -is not a terminal or there is no current branch, git shortlog will -output a summary of the log read from standard input, without -reference to the current repository. +For each Name <user@host> or <user@host> from the command-line +or standard input (when using --stdin), look up the person's canonical name +and email address (see "Mapping Authors" below). If found, print them; +otherwise print the input as-is. - + OPTIONS --h - - ---help +--stdin - Print a short usage message and exit. - - - - - --n - - ---numbered - - - - Sort output according to the number of commits per author instead - of author alphabetic order. - - - - - --s - - ---summary - - - - Suppress commit description and provide a commit count summary only. - - - - - --e - - ---email - - - - Show the email address of each author. - - - - - ---format[=<format>] - - - - Instead of the commit subject, use some other information to - describe each commit. <format> can be any string accepted - by the --format option of git log, such as * [%h] %s. - (See the "PRETTY FORMATS" section of .) - -Each pretty-printed commit will be rewrapped before it is shown. - - - - --w[<width>[,<indent1>[,<indent2>]]] - - - - Linewrap the output by wrapping each line at width. The first - line of each entry is indented by indent1 spaces, and the second - and subsequent lines are indented by indent2 spaces. width, - indent1, and indent2 default to 76, 6 and 9 respectively. + Read contacts, one per line, from the standard input after exhausting + contacts provided on the command-line. - + +OUTPUT +For each contact, a single line is output, terminated by a newline. If the +name is provided or known to the mailmap, Name <user@host> is +printed; otherwise only <user@host> is printed. + + MAPPING AUTHORS -The .mailmap feature is used to coalesce together commits by the same -person in the shortlog, where their name and/or email address was -spelled differently. If the file .mailmap exists at the toplevel of the repository, or at -the location pointed to by the mailmap.file configuration option, it +the location pointed to by the mailmap.file or mailmap.blob +configuration options, it is used to map author and committer names and email addresses to canonical real names and email addresses. In the simple form, each line in the file consists of the canonical @@ -165,7 +96,7 @@ Santa Claus <santa.claus@northpole.xx> <me@company.xx> Use hash # for comments that are either on their own line, or after the email address. - + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-check-ref-format.xml b/doc/source/en/TortoiseGit/git_doc/git-check-ref-format.xml index afab5f69d..01673cee0 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-check-ref-format.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-check-ref-format.xml @@ -23,13 +23,13 @@ DESCRIPTION Checks if a given refname is acceptable, and exits with a non-zero status if it is not. -A reference is used in git to specify branches and tags. A +A reference is used in Git to specify branches and tags. A branch head is stored in the refs/heads hierarchy, while a tag is stored in the refs/tags hierarchy of the ref namespace (typically in $GIT_DIR/refs/heads and $GIT_DIR/refs/tags directories or, as entries in file $GIT_DIR/packed-refs if refs are packed by git gc). -git imposes the following rules on how references are named: +Git imposes the following rules on how references are named: @@ -84,13 +84,18 @@ They cannot contain a sequence @{. +They cannot be the single character @. + + + + They cannot contain a \. These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used -unquoted (by mistake), and also avoids ambiguities in certain +unquoted (by mistake), and also avoid ambiguities in certain reference name expressions (see ): @@ -131,10 +136,7 @@ typed the branch name. ---allow-onelevel - - ---no-allow-onelevel +--[no-]allow-onelevel @@ -153,8 +155,8 @@ typed the branch name. Interpret <refname> as a reference name pattern for a refspec (as used with remote repositories). If this option is enabled, <refname> is allowed to contain a single * - in place of a one full pathname component (e.g., - foo/*/bar but not foo/bar*). + in the refspec (e.g., foo/bar*/baz or foo/bar*baz/ + but not foo/bar*/baz*). diff --git a/doc/source/en/TortoiseGit/git_doc/git-checkout.xml b/doc/source/en/TortoiseGit/git_doc/git-checkout.xml index c6b3ce50d..9b3292971 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-checkout.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-checkout.xml @@ -8,13 +8,14 @@ NAME -git-checkout - Checkout a branch or paths to the working tree +git-checkout - Switch branches or restore working tree files SYNOPSIS
git checkout [-q] [-f] [-m] [<branch>] -git checkout [-q] [-f] [-m] [--detach] [<commit>] +git checkout [-q] [-f] [-m] --detach [<branch>] +git checkout [-q] [-f] [-m] [--detach] <commit> git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>… git checkout [-p|--patch] [<tree-ish>] [--] [<paths>…] @@ -75,7 +76,7 @@ successful. git checkout --detach [<branch>] -git checkout <commit> +git checkout [--detach] <commit> @@ -86,10 +87,10 @@ successful. tree will be the state recorded in the commit plus the local modifications. -Passing --detach forces this behavior in the case of a <branch> (without -the option, giving a branch name to the command would check out the branch, -instead of detaching HEAD at it), or the current commit, -if no <branch> is specified. +When the <commit> argument is a branch name, the --detach option can +be used to detach HEAD at the tip of the branch (git checkout +<branch> would check out that branch without detaching HEAD). +Omitting <branch> detaches HEAD at the tip of the current branch. @@ -107,6 +108,9 @@ if no <branch> is specified. (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree. +git checkout with <paths> or --patch is used to restore modified or +deleted paths to their original contents from the index or replace paths +with the contents from a named <tree-ish> (most often a commit-ish). The index may contain unmerged entries because of a previous failed merge. By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. @@ -136,6 +140,19 @@ file can be discarded to re-create the original conflicted merge result. +--[no-]progress + + + + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless --quiet + is specified. This flag enables progress reporting even if not + attached to a terminal, regardless of --quiet. + + + + + -f @@ -163,6 +180,19 @@ entries; instead, unmerged entries are ignored. When checking out paths from the index, check out stage #2 (ours) or #3 (theirs) for unmerged paths. +Note that during git rebase and git pull --rebase, ours and +theirs may appear swapped; --ours gives the version from the +branch the changes are rebased onto, while --theirs gives the +version from the branch that holds your work that is being rebased. +This is because rebase is used in a workflow that treats the +history at the remote as the shared canonical one, and treats the +work done on the branch you are rebasing as the third-party work to +be integrated, and you are temporarily assuming the role of the +keeper of the canonical history during the rebase. As the keeper of +the canonical history, you need to view the history from the remote +as ours (i.e. "our shared canonical history"), while what you did +on your side branch as theirs (i.e. "one contributor's work on top +of it"). @@ -202,9 +232,9 @@ entries; instead, unmerged entries are ignored. "--track" in for details. If no -b option is given, the name of the new branch will be -derived from the remote-tracking branch. If "remotes/" or "refs/remotes/" -is prefixed it is stripped away, and then the part up to the -next slash (which would be the nickname of the remote) is removed. +derived from the remote-tracking branch, by looking at the local part of +the refspec configured for the corresponding remote, and then stripping +the initial part up to the "*". This would tell us to use "hack" as the local branch when branching off of "origin/hack" (or "remotes/origin/hack", or even "refs/remotes/origin/hack"). If the given name has no slash, or the above @@ -219,7 +249,7 @@ explicitly give a name with -b in such a case. Do not set up "upstream" configuration, even if the - branch.autosetupmerge configuration variable is true. + branch.autoSetupMerge configuration variable is true. @@ -279,6 +309,19 @@ working tree, by copying them from elsewhere, extracting a tarball, etc. +--ignore-skip-worktree-bits + + + + In sparse checkout mode, git checkout -- <paths> would + update only entries matched by <paths> and sparse patterns + in $GIT_DIR/info/sparse-checkout. This option ignores + the sparse patterns and adds back any files in <paths>. + + + + + -m @@ -311,7 +354,7 @@ the conflicted merge in the specified paths. The same as --merge option above, but changes the way the conflicting hunks are presented, overriding the - merge.conflictstyle configuration variable. Possible values are + merge.conflictStyle configuration variable. Possible values are "merge" (default) and "diff3" (in addition to what is shown by "merge" style, shows the original contents). @@ -338,6 +381,19 @@ section of to learn how to operate the - +--ignore-other-worktrees + + + + git checkout refuses when the wanted ref is already checked + out by another worktree. This option makes it check the ref + out anyway. In other words, the ref can be held by more than one + worktree. + + + + + <branch> @@ -348,8 +404,8 @@ section of to learn how to operate the - commit, your HEAD becomes "detached" and you are no longer on any branch (see below for details). -As a special case, the "@{-N}" syntax for the N-th last branch -checks out the branch (instead of detaching). You may also specify +As a special case, the "@{-N}" syntax for the N-th last branch/commit +checks out branches (instead of detaching). You may also specify - which is synonymous with "@{-1}". As a further special case, you may use "A...B" as a shortcut for the merge base of A and B if there is exactly one merge base. You can @@ -458,7 +514,7 @@ a---b---c---d branch 'master' (refers to commit 'd') ^ | tag 'v2.0' (refers to commit 'b') -In fact, we can perform all the normal git operations. But, let's look +In fact, we can perform all the normal Git operations. But, let's look at what happens when we then checkout master: $ git checkout master @@ -471,7 +527,7 @@ a---b---c---d branch 'master' (refers to commit 'd') tag 'v2.0' (refers to commit 'b') It is important to realize that at this point nothing refers to commit f. Eventually commit f (and by extension commit e) will be deleted -by the routine git garbage collection process, unless we create a reference +by the routine Git garbage collection process, unless we create a reference before that happens. If we have not yet moved away from commit f, any of these will create a reference to it: $ git checkout -b foo diff --git a/doc/source/en/TortoiseGit/git_doc/git-cherry-pick.xml b/doc/source/en/TortoiseGit/git_doc/git-cherry-pick.xml index f2f71d084..79e2386ac 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-cherry-pick.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-cherry-pick.xml @@ -13,7 +13,8 @@ SYNOPSIS
-git cherry-pick [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>… +git cherry-pick [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] + [-S[<keyid>]] <commit>… git cherry-pick --continue git cherry-pick --quit git cherry-pick --abort @@ -178,6 +179,22 @@ effect to your index in a row. Add Signed-off-by line at the end of the commit message. + See the signoff option in for more information. + + + + + +-S[<keyid>] + + +--gpg-sign[=<keyid>] + + + + GPG-sign commits. The keyid argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. @@ -233,7 +250,8 @@ effect to your index in a row. If a commit being cherry picked duplicates a commit already in the current history, it will become empty. By default these - redundant commits are ignored. This option overrides that behavior and + redundant commits cause cherry-pick to stop so the user can + examine the commit. This option overrides that behavior and creates an empty commit object. Implies --allow-empty. diff --git a/doc/source/en/TortoiseGit/git_doc/git-cherry.xml b/doc/source/en/TortoiseGit/git_doc/git-cherry.xml index 83af0ba1c..c57e0f9d6 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-cherry.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-cherry.xml @@ -8,7 +8,7 @@ NAME -git-cherry - Find commits not merged upstream +git-cherry - Find commits yet to be applied to upstream SYNOPSIS @@ -18,30 +18,15 @@ DESCRIPTION -The changeset (or "diff") of each commit between the fork-point and <head> -is compared against each commit between the fork-point and <upstream>. -The commits are compared with their patch id, obtained from -the git patch-id program. -Every commit that doesn't exist in the <upstream> branch -has its id (sha1) reported, prefixed by a symbol. The ones that have -equivalent change already -in the <upstream> branch are prefixed with a minus (-) sign, and those -that only exist in the <head> branch are prefixed with a plus (+) symbol: - __*__*__*__*__> <upstream> - / -fork-point - \__+__+__-__+__+__-__+__> <head> -If a <limit> has been given then the commits along the <head> branch up -to and including <limit> are not reported: - __*__*__*__*__> <upstream> - / -fork-point - \__*__*__<limit>__-__+__> <head> -Because git cherry compares the changeset rather than the commit id -(sha1), you can use git cherry to find out if a commit you made locally -has been applied <upstream> under a different commit id. For example, -this will happen if you're feeding patches <upstream> via email rather -than pushing or pulling commits directly. +Determine whether there are commits in <head>..<upstream> that are +equivalent to those in the range <limit>..<head>. +The equivalence test is based on the diff, after removing whitespace +and line numbers. git-cherry therefore detects when commits have been +"copied" by means of , or +. +Outputs the SHA1 of every commit in <limit>..<head>, prefixed with +- for commits that have an equivalent in <upstream>, and + for +commits that do not. OPTIONS @@ -52,7 +37,7 @@ than pushing or pulling commits directly. - Verbose. + Show the commit subjects next to the SHA1s. @@ -62,8 +47,8 @@ than pushing or pulling commits directly. - Upstream branch to compare against. - Defaults to the first tracked remote branch, if available. + Upstream branch to search for equivalent commits. + Defaults to the upstream branch of HEAD. @@ -89,6 +74,76 @@ than pushing or pulling commits directly. + +EXAMPLES +
+Patch workflows +git-cherry is frequently used in patch-based workflows (see +) to determine if a series of patches has been +applied by the upstream maintainer. In such a workflow you might +create and send a topic branch like this: +$ git checkout -b topic origin/master +# work and create some commits +$ git format-patch origin/master +$ git send-email ... 00* +Later, you can see whether your changes have been applied by saying +(still on topic): +$ git fetch # update your notion of origin/master +$ git cherry -v +
+
+Concrete example +In a situation where topic consisted of three commits, and the +maintainer applied two of them, the situation might look like: +$ git log --graph --oneline --decorate --boundary origin/master...topic +* 7654321 (origin/master) upstream tip commit +[... snip some other commits ...] +* cccc111 cherry-pick of C +* aaaa111 cherry-pick of A +[... snip a lot more that has happened ...] +| * cccc000 (topic) commit C +| * bbbb000 commit B +| * aaaa000 commit A +|/ +o 1234567 branch point +In such cases, git-cherry shows a concise summary of what has yet to +be applied: +$ git cherry origin/master topic +- cccc000... commit C ++ bbbb000... commit B +- aaaa000... commit A +Here, we see that the commits A and C (marked with -) can be +dropped from your topic branch when you rebase it on top of +origin/master, while the commit B (marked with +) still needs to +be kept so that it will be sent to be applied to origin/master. +
+
+Using a limit +The optional <limit> is useful in cases where your topic is based on +other work that is not in upstream. Expanding on the previous +example, this might look like: +$ git log --graph --oneline --decorate --boundary origin/master...topic +* 7654321 (origin/master) upstream tip commit +[... snip some other commits ...] +* cccc111 cherry-pick of C +* aaaa111 cherry-pick of A +[... snip a lot more that has happened ...] +| * cccc000 (topic) commit C +| * bbbb000 commit B +| * aaaa000 commit A +| * 0000fff (base) unpublished stuff F +[... snip ...] +| * 0000aaa unpublished stuff A +|/ +o 1234567 merge-base between upstream and topic +By specifying base as the limit, you can avoid listing commits +between base and topic: +$ git cherry origin/master topic base +- cccc000... commit C ++ bbbb000... commit B +- aaaa000... commit A +
+ SEE ALSO diff --git a/doc/source/en/TortoiseGit/git_doc/git-clean.xml b/doc/source/en/TortoiseGit/git_doc/git-clean.xml index c6fe8a159..0450bd09a 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-clean.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-clean.xml @@ -13,14 +13,14 @@ SYNOPSIS
-git clean [-d] [-f] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>… +git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>…
DESCRIPTION Cleans the working tree by recursively removing files that are not under version control, starting from the current directory. -Normally, only files unknown to git are removed, but if the -x +Normally, only files unknown to Git are removed, but if the -x option is specified, ignored files are also removed. This can, for example, be useful to remove all build products. If any optional <path>... arguments are given, only those paths @@ -36,7 +36,7 @@ are affected. Remove untracked directories in addition to untracked files. - If an untracked directory is managed by a different git + If an untracked directory is managed by a different Git repository, it is not removed by default. Use -f option twice if you really want to remove such a directory. @@ -51,8 +51,25 @@ are affected. - If the git configuration variable clean.requireForce is not set - to false, git clean will refuse to run unless given -f or -n. + If the Git configuration variable clean.requireForce is not set + to false, git clean will refuse to delete files or directories + unless given -f, -n or -i. Git will refuse to delete directories + with .git sub directory or file unless a second -f + is given. + + + + + +-i + + +--interactive + + + + Show what would be done and clean files interactively. See + Interactive mode for details. @@ -119,13 +136,106 @@ are affected. - Remove only files ignored by git. This may be useful to rebuild + Remove only files ignored by Git. This may be useful to rebuild everything from scratch, but keep manually created files. + +Interactive mode +When the command enters the interactive mode, it shows the +files and directories to be cleaned, and goes into its +interactive command loop. +The command loop shows the list of subcommands available, and +gives a prompt "What now> ". In general, when the prompt ends +with a single >, you can pick only one of the choices given +and type return, like this: + *** Commands *** + 1: clean 2: filter by pattern 3: select by numbers + 4: ask each 5: quit 6: help + What now> 1 +You also could say c or clean above as long as the choice is unique. +The main command loop has 6 subcommands. + + + +clean + + + + Start cleaning files and directories, and then quit. + + + + + +filter by pattern + + + + This shows the files and directories to be deleted and issues an + "Input ignore patterns>>" prompt. You can input space-separated + patterns to exclude files and directories from deletion. + E.g. "*.c *.h" will excludes files end with ".c" and ".h" from + deletion. When you are satisfied with the filtered result, press + ENTER (empty) back to the main menu. + + + + + +select by numbers + + + + This shows the files and directories to be deleted and issues an + "Select items to delete>>" prompt. When the prompt ends with double + >> like this, you can make more than one selection, concatenated + with whitespace or comma. Also you can say ranges. E.g. "2-5 7,9" + to choose 2,3,4,5,7,9 from the list. If the second number in a + range is omitted, all remaining items are selected. E.g. "7-" to + choose 7,8,9 from the list. You can say * to choose everything. + Also when you are satisfied with the filtered result, press ENTER + (empty) back to the main menu. + + + + + +ask each + + + + This will start to clean, and you must confirm one by one in order + to delete items. Please note that this action is not as efficient + as the above two actions. + + + + + +quit + + + + This lets you quit without do cleaning. + + + + + +help + + + + Show brief usage of interactive git-clean. + + + + + SEE ALSO diff --git a/doc/source/en/TortoiseGit/git_doc/git-clone.xml b/doc/source/en/TortoiseGit/git_doc/git-clone.xml index 9de1dcbe5..07955f88c 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-clone.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-clone.xml @@ -16,9 +16,9 @@ git clone [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] - [--separate-git-dir <git dir>] + [--dissociate] [--separate-git-dir <git dir>] [--depth <depth>] [--[no-]single-branch] - [--recursive|--recurse-submodules] [--] <repository> + [--recursive | --recurse-submodules] [--jobs <n>] [--] <repository> [<directory>]
@@ -52,7 +52,7 @@ configuration variables. When the repository to clone from is on a local machine, - this flag bypasses the normal "git aware" transport + this flag bypasses the 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 @@ -63,10 +63,7 @@ this is the default, and --local is essentially a no-op. If the repository is specified as a URL, then this flag is ignored (and we never use the local optimizations). Specifying --no-local will override the default when /path/to/repo is given, using the regular -git transport instead. -To force copying instead of hardlinking (which may be desirable if you -are trying to make a back-up of your repository), but still avoid the -usual "git aware" transport mechanism, --no-hardlinks can be used. +Git transport instead. @@ -75,9 +72,10 @@ usual "git aware" transport mechanism, --no-hardlinks can b - Optimize the cloning process from a repository on a - local filesystem by copying files under .git/objects - directory. + Force the cloning process from a repository on a local + filesystem to copy the files under the .git/objects + directory instead of using hardlinks. This may be desirable + if you are trying to make a back-up of your repository. @@ -99,9 +97,9 @@ usual "git aware" transport mechanism, --no-hardlinks can b NOTE: this is a possibly dangerous operation; do not use it unless you understand what it does. If you clone your repository using this option and then delete branches (or use any -other git command that makes any existing commit unreferenced) in the +other Git command that makes any existing commit unreferenced) in the source repository, some objects may become unreferenced (or dangling). -These objects may be removed by normal git operations (such as git commit) +These objects may be removed by normal Git operations (such as git commit) which automatically call git gc --auto. (See .) If these objects are removed and were referenced by the cloned repository, then the cloned repository will become corrupt. @@ -128,7 +126,26 @@ objects from the source repository into a pack in the cloned repository. -NOTE: see the NOTE for the --shared option. +NOTE: see the NOTE for the --shared option, and also the +--dissociate option. + + + + +--dissociate + + + + Borrow the objects from reference repositories specified + with the --reference options only to reduce network + transfer, and stop borrowing from them after a clone is made + by making necessary local copies of borrowed objects. This + option can also be used when cloning locally from a + repository that already borrows objects from another + repository--the new repository will borrow objects from the + same repository, and this option can be used to stop the + borrowing. + @@ -141,8 +158,7 @@ objects from the source repository into a pack in the cloned repository. Operate quietly. Progress is not reported to the standard - error stream. This flag is also passed to the rsync - command when given. + error stream. @@ -192,7 +208,7 @@ objects from the source repository into a pack in the cloned repository. - Make a bare GIT repository. That is, instead of + 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 obviously implies the -n @@ -305,27 +321,21 @@ objects from the source repository into a pack in the cloned repository. Create a shallow clone with a history truncated to the - specified number of revisions. A shallow repository has a - number of limitations (you cannot clone or fetch from - it, nor push from nor into it), but is adequate if you - are only interested in the recent history of a large project - with a long history, and would want to send in fixes - as patches. + specified number of commits. Implies --single-branch unless + --no-single-branch is given to fetch the histories near the + tips of all branches. ---single-branch +--[no-]single-branch Clone only the history leading to the tip of a single branch, either specified by the --branch option or the primary - branch remote's HEAD points at. When creating a shallow - clone with the --depth option, this is the default, unless - --no-single-branch is given to fetch the histories near the - tips of all branches. + branch remote's HEAD points at. Further fetches into the resulting repository will only update the remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any @@ -360,14 +370,28 @@ objects from the source repository into a pack in the cloned repository. Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, - then make a filesytem-agnostic git symbolic link to there. - The result is git repository can be separated from working + then make a filesystem-agnostic Git symbolic link to there. + The result is Git repository can be separated from working tree. +-j <n> + + +--jobs <n> + + + + The number of submodules fetched at the same time. + Defaults to the submodule.fetchJobs option. + + + + + <repository> @@ -401,9 +425,10 @@ address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. Git supports ssh, git, http, and https protocols (in addition, ftp, -and ftps can be used for fetching and rsync can be used for fetching -and pushing, but these are inefficient and deprecated; do not use -them). +and ftps can be used for fetching, but this is inefficient and +deprecated; do not use it). +The native transport (i.e. git:// URL) does no authentication and +should be used with caution on unsecured networks. The following syntaxes may be used with them: @@ -426,11 +451,6 @@ http[s]://host.xz[:port]/path/to/repo.git/ ftp[s]://host.xz[:port]/path/to/repo.git/ - - -rsync://host.xz/path/to/repo.git/ - - An alternative scp-like syntax may also be used with the ssh protocol: @@ -440,6 +460,11 @@ rsync://host.xz/path/to/repo.git/ +This syntax is only recognized if there are no slashes before the +first colon. This helps differentiate a local path that contains a +colon. For example the local path foo:bar could be specified as an +absolute path or ./foo:bar to avoid being misinterpreted as an ssh +url. The ssh and git protocols additionally support ~username expansion: @@ -458,7 +483,7 @@ git://host.xz[:port]/~[user]/path/to/repo.git/ -For local repositories, also supported by git natively, the following +For local repositories, also supported by Git natively, the following syntaxes may be used: @@ -468,13 +493,13 @@ syntaxes may be used: -file:///path/to/repo.git/ +file:///path/to/repo.git/ These two syntaxes are mostly equivalent, except the former implies --local option. -When git doesn't know how to handle a certain transport protocol, it +When Git doesn't know how to handle a certain transport protocol, it attempts to use the remote-<transport> remote helper, if one exists. To explicitly request a remote helper, the following syntax may be used: @@ -487,7 +512,7 @@ may be used: where <address> may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being -invoked. See for details. +invoked. See for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you use will be rewritten into URLs that work), you can create a @@ -518,8 +543,8 @@ use the original URL. Clone from upstream: -$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 -$ cd my2.6 +$ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux +$ cd my-linux $ make @@ -534,10 +559,10 @@ $ git show-branch Clone from upstream while borrowing from an existing local directory: -$ git clone --reference my2.6 \ - git://git.kernel.org/pub/scm/.../linux-2.7 \ - my2.7 -$ cd my2.7 +$ git clone --reference /git/linux.git \ + git://git.kernel.org/pub/scm/.../linux.git \ + my-linux +$ cd my-linux @@ -545,13 +570,6 @@ 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 - diff --git a/doc/source/en/TortoiseGit/git_doc/git-column.xml b/doc/source/en/TortoiseGit/git_doc/git-column.xml index 6f8618e79..f9fee629e 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-column.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-column.xml @@ -101,10 +101,6 @@ - -Author -Written by Nguyen Thai Ngoc Duy <pclouds@gmail.com> - GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-commit-tree.xml b/doc/source/en/TortoiseGit/git_doc/git-commit-tree.xml index 5a54123eb..ac7cce8a5 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-commit-tree.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-commit-tree.xml @@ -13,8 +13,9 @@ SYNOPSIS
-git commit-tree <tree> [(-p <parent>)…] < changelog -git commit-tree [(-p <parent>)…] [(-m <message>)…] [(-F <file>)…] <tree> +git commit-tree <tree> [(-p <parent>)…] +git commit-tree [(-p <parent>)…] [-S[<keyid>]] [(-m <message>)…] + [(-F <file>)…] <tree>
@@ -31,7 +32,7 @@ commits have no parents. 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 +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 @@ -82,6 +83,32 @@ state was. + + +-S[<keyid>] + + +--gpg-sign[=<keyid>] + + + + GPG-sign commits. The keyid argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. + + + + + +--no-gpg-sign + + + + Countermand commit.gpgSign configuration variable that is + set to force each and every commit to be signed. + + + @@ -112,12 +139,12 @@ GIT_AUTHOR_EMAIL GIT_AUTHOR_DATE GIT_COMMITTER_NAME GIT_COMMITTER_EMAIL -GIT_COMMITTER_DATE -EMAIL +GIT_COMMITTER_DATE (nb "<", ">" and "\n"s are stripped) In case (some of) these environment variables are not set, the information is taken from the configuration items user.name and user.email, or, if not -present, system user name and the hostname used for outgoing mail (taken +present, the environment variable EMAIL, or, if that is not set, +system user name and the hostname used for outgoing mail (taken from /etc/mailname and falling back to the fully qualified hostname when that file does not exist). A commit comment is read from stdin. If a changelog @@ -135,9 +162,9 @@ Git internal format - It is <unix timestamp> <timezone offset>, where <unix + It is <unix timestamp> <time zone offset>, where <unix timestamp> is the number of seconds since the UNIX epoch. - <timezone offset> is a positive or negative offset from UTC. + <time zone offset> is a positive or negative offset from UTC. For example CET (which is 2 hours ahead UTC) is +0200. @@ -171,36 +198,48 @@ ISO 8601 Discussion -At the core level, git is character encoding agnostic. +Git is to some extent character encoding agnostic. -The pathnames recorded in the index and in the tree objects - are treated as uninterpreted sequences of non-NUL bytes. - What readdir(2) returns are what are recorded and compared - with the data git keeps track of, which in turn are expected - to be what lstat(2) and creat(2) accepts. There is no such - thing as pathname encoding translation. +The contents of the blob objects are uninterpreted sequences + of bytes. There is no encoding translation at the core + level. -The contents of the blob objects are uninterpreted sequences - of bytes. There is no encoding translation at the core - level. +Path names are encoded in UTF-8 normalization form C. This + applies to tree objects, the index file, ref names, as well as + path names in command line arguments, environment variables + and config files (.git/config (see ), + , and + ). +Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly. -The commit log messages are uninterpreted sequences of non-NUL - bytes. +Commit log messages are typically encoded in UTF-8, but other + extended ASCII encodings are also supported. This includes + ISO-8859-x, CP125x and many others, but not UTF-16/32, + EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, + EUC-x, CP9xx etc.). Although we encourage that the commit log messages are encoded -in UTF-8, both the core and git Porcelain are designed not to +in UTF-8, both the core and Git Porcelain are designed not to force UTF-8 on projects. If all participants of a particular -project find it more convenient to use legacy encodings, git +project find it more convenient to use legacy encodings, Git does not forbid it. However, there are a few things to keep in mind. diff --git a/doc/source/en/TortoiseGit/git_doc/git-commit.xml b/doc/source/en/TortoiseGit/git_doc/git-commit.xml index f796a61f3..6b508a2f4 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-commit.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-commit.xml @@ -17,7 +17,7 @@ [--dry-run] [(-c | -C | --fixup | --squash) <commit>] [-F <file> | -m <msg>] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] - [--date=<date>] [--cleanup=<mode>] [--status | --no-status] + [--date=<date>] [--cleanup=<mode>] [--[no-]status] [-i | -o] [-S[<keyid>]] [--] [<file>…]
@@ -45,7 +45,7 @@ by using git rm to remove files from the working tree by listing files as arguments to the commit command, in which case the commit will ignore changes staged in the index, and instead record the current content of the listed files (which must already - be known to git); + be known to Git); @@ -86,7 +86,7 @@ that, you can recover from it with git reset. Tell the command to automatically stage files that have been modified and deleted, but new files you have not - told git about are not affected. + told Git about are not affected. @@ -169,7 +169,7 @@ that, you can recover from it with git reset. When used with -C/-c/--amend options, or when committing after a a conflicting cherry-pick, declare that the authorship of the - resulting commit now belongs of the committer. This also renews + resulting commit now belongs to the committer. This also renews the author timestamp. @@ -281,6 +281,8 @@ that, you can recover from it with git reset. Use the given <msg> as the commit message. + If multiple -m options are given, their values are + concatenated as separate paragraphs. @@ -314,7 +316,11 @@ that, you can recover from it with git reset. Add Signed-off-by line by the committer at the end of the commit - log message. + log message. The meaning of a signoff depends on the project, + but it typically certifies that committer has + the rights to submit this work under the same license and + agrees to a Developer Certificate of Origin + (see http://developercertificate.org/ for more information). @@ -364,15 +370,70 @@ that, you can recover from it with git reset. - This option sets how the commit message is cleaned up. - The <mode> can be one of verbatim, whitespace, strip, - and default. The default mode will strip leading and - trailing empty lines and #commentary from the commit message - only if the message is to be edited. Otherwise only whitespace - removed. The verbatim mode does not change message at all, - whitespace removes just leading/trailing whitespace lines - and strip removes both whitespace and commentary. + This option determines how the supplied commit message should be + cleaned up before committing. The <mode> can be strip, + whitespace, verbatim, scissors or default. + + + +strip + + + + Strip leading and trailing empty lines, trailing whitespace, + commentary and collapse consecutive empty lines. + + + + + +whitespace + + + + Same as strip except #commentary is not removed. + + + + + +verbatim + + + + Do not change the message at all. + + + + + +scissors + + + + Same as whitespace, except that everything from (and + including) the line + "# ------------------------ >8 ------------------------" + is truncated if the message is to be edited. "#" can be + customized with core.commentChar. + + + + + +default + + + + Same as strip if the message is to be edited. + Otherwise whitespace. + + + + +The default can be changed by the commit.cleanup configuration +variable (see ). @@ -385,8 +446,8 @@ that, you can recover from it with git reset. 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 + -m, and from commit object with -C are usually used as + the commit log message unmodified. This option lets you further edit the message taken from these sources. @@ -409,14 +470,15 @@ that, you can recover from it with git reset. - Used to amend the tip of the current branch. Prepare the tree - object you would want to replace the latest commit as usual - (this includes the usual -i/-o and explicit paths), and the - commit log editor is seeded with the commit message from the - tip of the current branch. The commit you create replaces the - current tip -- if it was a merge, it will have the parents of - the current tip as parents -- so the current top commit is - discarded. + Replace the tip of the current branch by creating a new + commit. The recorded tree is prepared as usual (including + the effect of the -i and -o options and explicit + pathspec), and the message from the original commit is used + as the starting point, instead of an empty message, when no + other message is specified from the command line via options + such as -m, -F, -c, etc. The new commit has the same + parents and author as the current one (the --reset-author + option can countermand this). It is a rough equivalent for: $ git reset --soft HEAD^ @@ -463,9 +525,10 @@ FROM UPSTREAM REBASE" section in .) - Make a commit only from the paths specified on the + Make a commit by taking the updated working tree contents + of the paths specified on the command line, disregarding any contents that have been - staged so far. This is the default mode of operation of + staged for other paths. This is the default mode of operation of git commit if any paths are given on the command line, in which case this option can be omitted. If this option is specified together with --amend, then @@ -522,9 +585,15 @@ configuration variable documented in . Show unified diff between the HEAD commit and what would be committed at the bottom of the commit message - template. Note that this diff output doesn't have its - lines prefixed with #. + template to help the user describe the commit by reminding + what changes the commit has. + Note that this diff output doesn't have its + lines prefixed with #. This diff will not be a part + of the commit message. +If specified twice, show in addition the unified diff between +what would be committed and the worktree files, i.e. the unstaged +changes to tracked files. @@ -586,7 +655,20 @@ configuration variable documented in . - GPG-sign commit. + GPG-sign commits. The keyid argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. + + + + + +--no-gpg-sign + + + + Countermand commit.gpgSign configuration variable that is + set to force each and every commit to be signed. @@ -628,9 +710,9 @@ Git internal format - It is <unix timestamp> <timezone offset>, where <unix + It is <unix timestamp> <time zone offset>, where <unix timestamp> is the number of seconds since the UNIX epoch. - <timezone offset> is a positive or negative offset from UTC. + <time zone offset> is a positive or negative offset from UTC. For example CET (which is 2 hours ahead UTC) is +0200. @@ -735,39 +817,51 @@ refuses to run when given pathnames (but see -i option). turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body. -At the core level, git is character encoding agnostic. +Git is to some extent character encoding agnostic. -The pathnames recorded in the index and in the tree objects - are treated as uninterpreted sequences of non-NUL bytes. - What readdir(2) returns are what are recorded and compared - with the data git keeps track of, which in turn are expected - to be what lstat(2) and creat(2) accepts. There is no such - thing as pathname encoding translation. +The contents of the blob objects are uninterpreted sequences + of bytes. There is no encoding translation at the core + level. -The contents of the blob objects are uninterpreted sequences - of bytes. There is no encoding translation at the core - level. +Path names are encoded in UTF-8 normalization form C. This + applies to tree objects, the index file, ref names, as well as + path names in command line arguments, environment variables + and config files (.git/config (see ), + , and + ). +Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly. -The commit log messages are uninterpreted sequences of non-NUL - bytes. +Commit log messages are typically encoded in UTF-8, but other + extended ASCII encodings are also supported. This includes + ISO-8859-x, CP125x and many others, but not UTF-16/32, + EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, + EUC-x, CP9xx etc.). Although we encourage that the commit log messages are encoded -in UTF-8, both the core and git Porcelain are designed not to +in UTF-8, both the core and Git Porcelain are designed not to force UTF-8 on projects. If all participants of a particular -project find it more convenient to use legacy encodings, git +project find it more convenient to use legacy encodings, Git does not forbid it. However, there are a few things to keep in mind. diff --git a/doc/source/en/TortoiseGit/git_doc/git-config.xml b/doc/source/en/TortoiseGit/git_doc/git-config.xml index aeb50ded9..e2026ef42 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-config.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-config.xml @@ -13,17 +13,18 @@ SYNOPSIS
-git config [<file-option>] [type] [-z|--null] name [value [value_regex]] +git config [<file-option>] [type] [--show-origin] [-z|--null] name [value [value_regex]] git config [<file-option>] [type] --add name value git config [<file-option>] [type] --replace-all name value [value_regex] -git config [<file-option>] [type] [-z|--null] --get name [value_regex] -git config [<file-option>] [type] [-z|--null] --get-all name [value_regex] -git config [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] +git config [<file-option>] [type] [--show-origin] [-z|--null] --get name [value_regex] +git config [<file-option>] [type] [--show-origin] [-z|--null] --get-all name [value_regex] +git config [<file-option>] [type] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] +git config [<file-option>] [type] [-z|--null] --get-urlmatch name URL git config [<file-option>] --unset name [value_regex] git config [<file-option>] --unset-all name [value_regex] git config [<file-option>] --rename-section old_name new_name git config [<file-option>] --remove-section name -git config [<file-option>] [-z|--null] -l | --list +git config [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list git config [<file-option>] --get-color name [default] git config [<file-option>] --get-colorbool name [stdout-is-tty] git config [<file-option>] -e | --edit @@ -56,7 +57,7 @@ configuration file by default, and options --system, --local but that is the default). This command will fail with non-zero status upon error. Some exit codes are: - + The config file is invalid (ret=3), @@ -92,7 +93,7 @@ you try to unset/set an option for which multiple lines match (ret=5), or you try to use an invalid regexp (ret=6). - + On success, the command returns the exit code 0. @@ -129,7 +130,7 @@ you try to use an invalid regexp (ret=6). Get the value for a given key (optionally filtered by a regex matching the value). Returns error code 1 if the key was not - found and error code 2 if multiple key values were found. + found and the last value if multiple key values were found. @@ -139,8 +140,7 @@ you try to use an invalid regexp (ret=6). - Like get, but does not fail if the number of values for the key - is not exactly one. + Like get, but returns all values for a multi-valued key. @@ -160,16 +160,32 @@ you try to use an invalid regexp (ret=6). +--get-urlmatch name URL + + + + When given a two-part name section.key, the value for + section.<url>.key whose <url> part matches the best to the + given URL is returned (if no such key exists, the value for + section.key is used as a fallback). When given just the + section as name, do so for all the keys in the section and + list them. Returns error code 1 if no value is found. + + + + + --global - For writing options: write to global /.gitconfig file rather than - the repository .git/config, write to $XDG_CONFIG_HOME/git/config file - if this file exists and the /.gitconfig file doesn't. + For writing options: write to global ~/.gitconfig file + rather than the repository .git/config, write to + $XDG_CONFIG_HOME/git/config file if this file exists and the + ~/.gitconfig file doesn't. -For reading options: read only from global ~/.gitconfig and from -$XDG_CONFIG_HOME/git/config rather than from all available files. +For reading options: read only from global ~/.gitconfig and from +$XDG_CONFIG_HOME/git/config rather than from all available files. See also . @@ -179,16 +195,31 @@ $XDG_CONFIG_HOME/git/config rather than from all available files. - For writing options: write to system-wide $(prefix)/etc/gitconfig - rather than the repository .git/config. + For writing options: write to system-wide + $(prefix)/etc/gitconfig rather than the repository + .git/config. -For reading options: read only from system-wide $(prefix)/etc/gitconfig +For reading options: read only from system-wide $(prefix)/etc/gitconfig rather than from all available files. See also . +--local + + + + For writing options: write to the repository .git/config file. + This is the default behavior. + +For reading options: read only from the repository .git/config rather than +from all available files. +See also . + + + + -f config-file @@ -202,6 +233,20 @@ rather than from all available files. +--blob blob + + + + Similar to --file but use the given blob instead of a file. E.g. + you can use master:.gitmodules to read values from the file + .gitmodules in the master branch. See "SPECIFYING REVISIONS" + section in for a more complete list of + ways to spell blob names. + + + + + --remove-section @@ -249,7 +294,7 @@ rather than from all available files. - List all variables set in config file. + List all variables set in config file, along with their values. @@ -321,6 +366,30 @@ rather than from all available files. +--name-only + + + + Output only the names of config variables for --list or + --get-regexp. + + + + + +--show-origin + + + + Augment the output of all queried config options with the + origin type (file, standard input, blob, command line) and + the actual origin (config file path, ref, or blob id if + applicable). + + + + + --get-colorbool name [stdout-is-tty] @@ -365,15 +434,14 @@ rather than from all available files. ---includes - - ---no-includes +--[no-]includes Respect include.* directives in config files when looking up - values. Defaults to on. + values. Defaults to off when a specific file is given (e.g., + using --file, --global, etc) and on when searching all + config files. @@ -386,47 +454,47 @@ rather than from all available files. -$GIT_DIR/config +$(prefix)/etc/gitconfig - Repository specific configuration file. + System-wide configuration file. -~/.gitconfig +$XDG_CONFIG_HOME/git/config - User-specific configuration file. Also called "global" - configuration file. + Second user-specific configuration file. If $XDG_CONFIG_HOME is not set + or empty, $HOME/.config/git/config will be used. Any single-valued + variable set in this file will be overwritten by whatever is in + ~/.gitconfig. It is a good idea not to create this file if + you sometimes use older versions of Git, as support for this + file was added fairly recently. -$XDG_CONFIG_HOME/git/config +~/.gitconfig - Second user-specific configuration file. If $XDG_CONFIG_HOME is not set - or empty, $HOME/.config/git/config will be used. Any single-valued - variable set in this file will be overwritten by whatever is in - ~/.gitconfig. It is a good idea not to create this file if - you sometimes use older versions of Git, as support for this - file was added fairly recently. + User-specific configuration file. Also called "global" + configuration file. -$(prefix)/etc/gitconfig +$GIT_DIR/config - System-wide configuration file. + Repository specific configuration file. @@ -436,10 +504,13 @@ files that are available. If the global or the system-wide configuration file are not available they will be ignored. If the repository configuration file is not available or readable, git config will exit with a non-zero error code. However, in neither case will an error message be issued. +The files are read in the order given above, with last value found taking +precedence over values read earlier. When multiple values are taken then all +values of a key from all files will be used. All writing options will per default write to the repository specific configuration file. Note that this also affects options like --replace-all and --unset. git config will only ever change one file at a time. -You can override these rules either by command line options or by environment +You can override these rules either by command-line options or by environment variables. The --global and the --system options will limit the file used to the global or system-wide file respectively. The GIT_CONFIG environment variable has a similar effect, but you can specify any filename you want. @@ -459,6 +530,17 @@ GIT_CONFIG + + +GIT_CONFIG_NOSYSTEM + + + + Whether to skip reading settings from the system-wide + $(prefix)/etc/gitconfig file. See for details. + + + See also . @@ -482,6 +564,12 @@ GIT_CONFIG [core] gitproxy=proxy-command for kernel.org gitproxy=default-proxy ; for all the rest +; HTTP +[http] + sslVerify +[http "https://weak.example.com"] + sslVerify = false + cookieFile = /tmp/cookie.txt you can set the filemode to true with % git config core.filemode true The hypothetical proxy command entries actually have a postfix to discern @@ -517,22 +605,32 @@ script: WS=$(git config --get-color color.diff.whitespace "blue reverse") RESET=$(git config --get-color "" "reset") echo "${WS}your whitespace color or blue reverse${RESET}" +For URLs in https://weak.example.com, http.sslVerify is set to +false, while it is set to true for all others: +% git config --bool --get-urlmatch http.sslverify https://good.example.com +true +% git config --bool --get-urlmatch http.sslverify https://weak.example.com +false +% git config --get-urlmatch http https://weak.example.com +http.cookieFile /tmp/cookie.txt +http.sslverify false CONFIGURATION FILE -The git configuration file contains a number of variables that affect -the git command's behavior. The .git/config file in each repository +The Git configuration file contains a number of variables that affect +the Git commands' behavior. The .git/config file in each repository is used to store the configuration for that repository, and $HOME/.gitconfig is used to store a per-user configuration as fallback values for the .git/config file. The file /etc/gitconfig can be used to store a system-wide default configuration. -The configuration variables are used by both the git plumbing +The configuration variables are used by both the Git plumbing and the porcelains. The variables are divided into sections, wherein the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last dot. The variable names are case-insensitive, allow only alphanumeric characters and -, and must start with an alphabetic character. Some -variables may appear multiple times. +variables may appear multiple times; we say then that the variable is +multivalued.
Syntax The syntax is fairly flexible and permissive; whitespaces are mostly @@ -540,7 +638,7 @@ ignored. The # and ; characters begin blank lines are ignored. The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next -section begins. Section names are not case sensitive. Only alphanumeric +section begins. Section names are case-insensitive. Only alphanumeric characters, - and . are allowed in section names. Each variable must belong to some section, which means that there must be a section header before the first setting of a variable. @@ -549,8 +647,8 @@ put its name in double quotes, separated by space from the section name, in the section header, like in the example below: [section "subsection"] Subsection names are case sensitive and can contain any characters except -newline (doublequote " and backslash have to be escaped as \" and \\, -respectively). Section headers cannot span multiple +newline (doublequote " and backslash can be included by escaping them +as \" and \\, respectively). Section headers cannot span multiple lines. Variables may belong directly to a section or to a given subsection. You can have [section] if you have [section "subsection"], but you don't need to. @@ -560,32 +658,23 @@ compared case sensitively. These subsection names follow the same restrictions as section names. All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form -name = value. If there is no equal sign on the line, the entire line -is taken as name and the variable is recognized as boolean "true". +name = value (or just name, which is a short-hand to say that +the variable is the boolean "true"). The variable names are case-insensitive, allow only alphanumeric characters -and -, and must start with an alphabetic character. There can be more -than one value for a given variable; we say then that the variable is -multivalued. -Leading and trailing whitespace in a variable value is discarded. -Internal whitespace within a variable value is retained verbatim. -The values following the equals sign in variable assign are all either -a string, an integer, or a boolean. Boolean values may be given as yes/no, -1/0, true/false or on/off. Case is not significant in boolean values, when -converting value to the canonical form using --bool type specifier; -git config will ensure that the output is "true" or "false". -String values may be entirely or partially enclosed in double quotes. -You need to enclose variable values in double quotes if you want to -preserve leading or trailing whitespace, or if the variable value contains -comment characters (i.e. it contains # or ;). -Double quote " and backslash \ characters in variable values must -be escaped: use \" for " and \\ for \. +and -, and must start with an alphabetic character. +A line that defines a value can be continued to the next line by +ending it with a \; the backquote and the end-of-line are +stripped. Leading whitespaces after name =, the remainder of the +line after the first comment character # or ;, and trailing +whitespaces of the line are discarded unless they are enclosed in +double quotes. Internal whitespaces within the value are retained +verbatim. +Inside double quotes, double quote " and backslash \ characters +must be escaped: use \" for " and \\ for \. The following escape sequences (beside \" and \\) are recognized: \n for newline character (NL), \t for horizontal tabulation (HT, TAB) -and \b for backspace (BS). No other char escape sequence, nor octal -char sequences are valid. -Variable values ending in a \ are continued on the next line in the -customary UNIX fashion. -Some variables may require a special value format. +and \b for backspace (BS). Other char escape sequences (including octal +escape sequences) are invalid.
Includes @@ -621,12 +710,103 @@ user's home directory. See below for examples. path = foo ; expand "foo" relative to the current file path = ~/foo ; expand "foo" in your $HOME directory
+
+Values +Values of many variables are treated as a simple string, but there +are variables that take values of specific types and there are rules +as to how to spell them. + + + +boolean + + + + When a variable is said to take a boolean value, many + synonyms are accepted for true and false; these are all + case-insensitive. + + + + +true + + + +Boolean true can be spelled as yes, on, true, + or 1. Also, a variable defined without = <value> + is taken as true. + + + + + +false + + + +Boolean false can be spelled as no, off, + false, or 0. + +When converting value to the canonical form using --bool type +specifier; git config will ensure that the output is "true" or +"false" (spelled in lowercase). + + + + + + + +integer + + + + The value for many variables that specify various sizes can + be suffixed with k, M,… to mean "scale the number by + 1024", "by 1024x1024", etc. + + + + + +color + + + + The value for a variables that takes a color is a list of + colors (at most two) and attributes (at most one), separated + by spaces. The colors accepted are normal, black, + red, green, yellow, blue, magenta, cyan and + white; the attributes are bold, dim, ul, blink and + reverse. The first color given is the foreground; the + second is the background. The position of the attribute, if + any, doesn't matter. Attributes may be turned off specifically + by prefixing them with no (e.g., noreverse, noul, etc). + +Colors (foreground and background) may also be given as numbers between +0 and 255; these use ANSI 256-color mode (but note that not all +terminals may support this). If your terminal supports it, you may also +specify 24-bit RGB values as hex, like #ff0ab3. +The attributes are meant to be reset at the beginning of each item +in the colored output, so setting color.decorate.branch to black +will paint that branch name in a plain black, even if the previous +thing on the same output line (e.g. opening parenthesis before the +list of branch names in log --decorate output) is set to be +painted with bold or some other attribute. + + + +
Variables Note that this list is non-comprehensive and not necessarily complete. For command-specific variables, you will find a more detailed description -in the appropriate manual page. You will find a description of non-core -porcelain configuration variables in the respective porcelain documentation. +in the appropriate manual page. +Other git-related tools may and do use their own variables. When +inventing new variables for use in your own tool, make sure their +names do not conflict with those that are used by Git itself and +other popular tools, and describe them in your documentation. @@ -641,13 +821,15 @@ advice.* -pushNonFastForward +pushUpdateRejected Set this variable to false if you want to disable - pushNonFFCurrent, pushNonFFDefault, and - pushNonFFMatching simultaneously. + pushNonFFCurrent, + pushNonFFMatching, pushAlreadyExists, + pushFetchFirst, and pushNeedsForce + simultaneously. @@ -664,28 +846,50 @@ pushNonFFCurrent -pushNonFFDefault +pushNonFFMatching + + + + Advice shown when you ran and pushed + matching refs explicitly (i.e. you used :, or + specified a refspec that isn't your current branch) and + it resulted in a non-fast-forward error. + + + + + +pushAlreadyExists - Advice to set push.default to upstream or current - when you ran and pushed matching - refs by default (i.e. you did not provide an explicit - refspec, and no push.default configuration was set) - and it resulted in a non-fast-forward error. + Shown when rejects an update that + does not qualify for fast-forwarding (e.g., a tag.) -pushNonFFMatching +pushFetchFirst - Advice shown when you ran and pushed - matching refs explicitly (i.e. you used :, or - specified a refspec that isn't your current branch) and - it resulted in a non-fast-forward error. + Shown when rejects an update that + tries to overwrite a remote ref that points at an + object we do not have. + + + + + +pushNeedsForce + + + + Shown when rejects an update that + tries to overwrite a remote ref that points at an + object that is not a commit-ish, or make the remote + ref point at an object that is not a commit-ish. @@ -705,6 +909,18 @@ statusHints +statusUoption + + + + Advise to consider using the -u option to + when the command takes more than 2 seconds to enumerate untracked + files. + + + + + commitBeforeMerge @@ -720,7 +936,7 @@ resolveConflict - Advices shown by various commands when conflicts + Advice shown by various commands when conflicts prevent the operation from being performed. @@ -760,73 +976,102 @@ amWorkDir - - - -core.fileMode +rmHints - If false, the executable bit differences between the index and - the working tree are ignored; useful on broken filesystems like FAT. - See . + In case of failure in the output of , + show directions on how to proceed from the current state. -The default is true, except or -will probe and set core.fileMode false if appropriate when the -repository is created. + + + -core.ignoreCygwinFSTricks +core.fileMode - This option is only used by Cygwin implementation of Git. If false, - the Cygwin stat() and lstat() functions are used. This may be useful - if your repository consists of a few separate directories joined in - one hierarchy using Cygwin mount. If true, Git uses native Win32 API - whenever it is possible and falls back to Cygwin functions only to - handle symbol links. The native mode is more than twice faster than - normal Cygwin l/stat() functions. True by default, unless core.filemode - is true, in which case ignoreCygwinFSTricks is ignored as Cygwin's - POSIX emulation is required to support core.filemode. + Tells Git if the executable bit of files in the working tree + is to be honored. +Some filesystems lose the executable bit when a file that is +marked as executable is checked out, or checks out an +non-executable file with executable bit on. + or probe the filesystem +to see if it handles the executable bit correctly +and this variable is automatically set as necessary. +A repository, however, may be on a filesystem that handles +the filemode correctly, and this variable is set to true +when created, but later may be made accessible from another +environment that loses the filemode (e.g. exporting ext4 via +CIFS mount, visiting a Cygwin created repository with +Git for Windows or Eclipse). +In such a case it may be necessary to set this variable to false. +See . +The default is true (when core.filemode is not specified in the config file). -core.ignorecase +core.ignoreCase If true, this option enables various workarounds to enable - git to work better on filesystems that are not case sensitive, + Git to work better on filesystems that are not case sensitive, like FAT. For example, if a directory listing finds - "makefile" when git expects "Makefile", git will assume + "makefile" when Git expects "Makefile", Git will assume it is really the same file, and continue to remember it as "Makefile". The default is false, except or -will probe and set core.ignorecase true if appropriate when the repository +will probe and set core.ignoreCase true if appropriate when the repository is created. -core.precomposeunicode +core.precomposeUnicode - This option is only used by Mac OS implementation of git. - When core.precomposeunicode=true, git reverts the unicode decomposition + This option is only used by Mac OS implementation of Git. + When core.precomposeUnicode=true, Git reverts the unicode decomposition of filenames done by Mac OS. This is useful when sharing a repository between Mac OS and Linux or Windows. - (Git for Windows 1.7.10 or higher is needed, or git under cygwin 1.7). - When false, file names are handled fully transparent by git, - which is backward compatible with older versions of git. + (Git for Windows 1.7.10 or higher is needed, or Git under cygwin 1.7). + When false, file names are handled fully transparent by Git, + which is backward compatible with older versions of Git. + + + + + +core.protectHFS + + + + If set to true, do not allow checkout of paths that would + be considered equivalent to .git on an HFS+ filesystem. + Defaults to true on Mac OS, and false elsewhere. + + + + + +core.protectNTFS + + + + If set to true, do not allow checkout of paths that would + cause problems with the NTFS filesystem, e.g. conflict with + 8.3 "short" names. + Defaults to true on Windows, and false elsewhere. @@ -846,7 +1091,36 @@ core.trustctime -core.quotepath +core.untrackedCache + + + + Determines what to do about the untracked cache feature of the + index. It will be kept, if this variable is unset or set to + keep. It will automatically be added if set to true. And + it will automatically be removed, if set to false. Before + setting it to true, you should check that mtime is working + properly on your system. + See . keep by default. + + + + + +core.checkStat + + + + Determines which stat fields to match between the index + and work tree. The user can set this to default or + minimal. Default (or explicitly default), is to check + all fields, including the sub-second part of mtime and ctime. + + + + + +core.quotePath @@ -884,20 +1158,20 @@ core.safecrlf - If true, makes git check if converting CRLF is reversible when + If true, makes Git check if converting CRLF is reversible when end-of-line conversion is active. Git will verify if a command modifies a file in the work tree either directly or indirectly. For example, committing a file followed by checking out the same file should yield the original file in the work tree. If this is not the case for the current setting of - core.autocrlf, git will reject the file. The variable can - be set to "warn", in which case git will only warn about an + core.autocrlf, Git will reject the file. The variable can + be set to "warn", in which case Git will only warn about an irreversible conversion but continue the operation. CRLF conversion bears a slight chance of corrupting data. -When it is enabled, git will convert CRLF to LF during commit and LF to +When it is enabled, Git will convert CRLF to LF during commit and LF to CRLF during checkout. A file that contains a mixture of LF and -CRLF before the commit cannot be recreated by git. For text +CRLF before the commit cannot be recreated by Git. For text files this is the right thing to do: it corrects line endings such that we have only LF line endings in the repository. But for binary files that are accidentally classified as text the @@ -906,7 +1180,7 @@ conversion can corrupt data. setting the conversion type explicitly in .gitattributes. Right after committing you still have the original file in your work tree and this file is not yet corrupted. You can explicitly tell -git that this file is binary and git will handle the file +Git that this file is binary and Git will handle the file appropriately. Unfortunately, the desired effect of cleaning up text files with mixed line endings and the undesired effect of corrupting binary @@ -968,7 +1242,7 @@ core.gitProxy A "proxy command" to execute (as command host port) instead of establishing direct connection to the remote server when - using the git protocol for fetching. If the variable value is + using the Git protocol for fetching. If the variable value is in the "COMMAND for DOMAIN" format, the command is applied only on hostnames ending with the specified domain string. This variable may be set multiple times and is matched in the given order; @@ -989,15 +1263,17 @@ core.ignoreStat - If true, commands which modify both the working tree and the index - will mark the updated paths with the "assume unchanged" bit in the - index. These marked files are then assumed to stay unchanged in the - working tree, until you mark them otherwise manually - Git will not - detect the file changes by lstat() calls. This is useful on systems - where those are very slow, such as Microsoft Windows. - See . - False by default. + If true, Git will avoid using lstat() calls to detect if files have + changed by setting the "assume-unchanged" bit for those tracked files + which it has updated identically in both the index and working tree. +When files are modified outside of Git, the user will need to stage +the modified files explicitly (e.g. see Examples section in +). +Git will not normally detect changes to those files. +This is useful on systems where lstat() calls are very slow, such as +CIFS/Microsoft Windows. +False by default. @@ -1038,8 +1314,10 @@ core.worktree Set the path to the root of the working tree. + If GIT_COMMON_DIR environment variable is set, core.worktree + is ignored and not used for determining the root of working tree. This can be overridden by the GIT_WORK_TREE environment - variable and the --work-tree command line option. + variable and the --work-tree command-line option. The value can be an absolute path or relative to the path to the .git directory, which is either specified by --git-dir or GIT_DIR, or automatically discovered. @@ -1052,7 +1330,7 @@ core.worktree file in a ".git" subdirectory of a directory and its value differs from the latter directory (e.g. "/path/to/.git/config" has core.worktree set to "/different/path"), which is most likely a -misconfiguration. Running git commands in the "/path/to" directory will +misconfiguration. Running Git commands in the "/path/to" directory will still use "/different/path" as the root of the work tree and can cause confusion unless you know what you are doing (e.g. you are creating a read-only snapshot of the same index to a location different from the @@ -1067,7 +1345,7 @@ core.logAllRefUpdates Enable the reflog. Updates to a ref <ref> is logged to the file "$GIT_DIR/logs/<ref>", by appending the new and old - SHA1, the date/time and the reason of the update, but + SHA-1, the date/time and the reason of the update, but only when the file exists. If this configuration variable is set to true, missing "$GIT_DIR/logs/<ref>" file is automatically created for branch heads (i.e. under @@ -1102,7 +1380,7 @@ core.sharedRepository several users in a group (making sure all the files and objects are group-writable). When all (or world or everybody), the repository will be readable by all users, additionally to being - group-shareable. When umask (or false), git will use permissions + group-shareable. When umask (or false), Git will use permissions reported by umask(2). When 0xxx, where 0xxx is an octal number, files in the repository will have this mode value. 0xxx will override user's umask value (whereas the other options will only override @@ -1120,8 +1398,8 @@ core.warnAmbiguousRefs - If true, git will warn you if the ref name you passed it is ambiguous - and might match multiple refs in the .git/refs/ tree. True by default. + If true, Git will warn you if the ref name you passed it is ambiguous + and might match multiple refs in the repository. True by default. @@ -1135,13 +1413,13 @@ core.compression -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being slowest. If set, this provides a default to other compression variables, - such as core.loosecompression and pack.compression. + such as core.looseCompression and pack.compression. -core.loosecompression +core.looseCompression @@ -1203,7 +1481,7 @@ core.deltaBaseCacheLimit to avoid unpacking and decompressing frequently used base objects multiple times. -Default is 16 MiB on all platforms. This should be reasonable +Default is 96 MiB on all platforms. This should be reasonable for all users/operating systems, except on the largest projects. You probably do not need to adjust this value. Common unit suffixes of k, m, or g are supported. @@ -1218,7 +1496,8 @@ core.bigFileThreshold Files larger than this size are stored deflated, without attempting delta compression. Storing large files without delta compression avoids excessive memory usage, at the - slight expense of increased disk usage. + slight expense of increased disk usage. Additionally files + larger than this size are always treated as binary. Default is 512 MiB on all platforms. This should be reasonable for most projects as source code and other text files can still @@ -1228,12 +1507,12 @@ be delta compressed, but larger binary media files won't be. -core.excludesfile +core.excludesFile In addition to .gitignore (per-directory) and - .git/info/exclude, git looks into this file for patterns + .git/info/exclude, Git looks into this file for patterns of files which are not meant to be tracked. "~/" is expanded to the value of $HOME and "~user/" to the specified user's home directory. Its default value is $XDG_CONFIG_HOME/git/ignore. @@ -1244,7 +1523,7 @@ core.excludesfile -core.askpass +core.askPass @@ -1254,20 +1533,20 @@ core.askpass environment variable. If not set, fall back to the value of the SSH_ASKPASS environment variable or, failing that, a simple password prompt. The external program shall be given a suitable prompt as - command line argument and write the password on its STDOUT. + command-line argument and write the password on its STDOUT. -core.attributesfile +core.attributesFile In addition to .gitattributes (per-directory) and - .git/info/attributes, git looks into this file for attributes + .git/info/attributes, Git looks into this file for attributes (see ). Path expansions are made the same - way as for core.excludesfile. Its default value is + way as for core.excludesFile. Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/attributes is used instead. @@ -1288,11 +1567,39 @@ core.editor +core.commentChar + + + + Commands such as commit and tag that lets you edit + messages consider a line that begins with this character + commented, and removes them after the editor returns + (default #). + +If set to "auto", git-commit would select a character that is not +the beginning character of any line in existing commit messages. + + + + +core.packedRefsTimeout + + + + The length of time, in milliseconds, to retry when trying to + lock the packed-refs file. Value 0 means not to retry at + all; -1 means to try indefinitely. Default is 1000 (i.e., + retry for 1 second). + + + + + sequence.editor - Text editor used by git rebase -i for editing the rebase insn file. + Text editor used by git rebase -i for editing the rebase instruction file. The value is meant to be interpreted by the shell when it is used. It can be overridden by the GIT_SEQUENCE_EDITOR environment variable. When not configured the default commit message editor is used instead. @@ -1305,23 +1612,28 @@ core.pager - The command that git will use to paginate output. Can - be overridden with the GIT_PAGER environment - variable. Note that git sets the LESS environment - variable to FRSX if it is unset when it runs the - pager. One can change these settings by setting the - LESS variable to some other value. Alternately, - these settings can be overridden on a project or - global basis by setting the core.pager option. - Setting core.pager has no effect on the LESS - environment variable behaviour above, so if you want - to override git's default settings this way, you need - to be explicit. For example, to disable the S option - in a backward compatible manner, set core.pager - to less -+S. This will be passed to the shell by - git, which will translate the final command to - LESS=FRSX less -+S. + Text viewer for use by Git commands (e.g., less). The value + is meant to be interpreted by the shell. The order of preference + is the $GIT_PAGER environment variable, then core.pager + configuration, then $PAGER, and then the default chosen at + compile time (usually less). +When the LESS environment variable is unset, Git sets it to FRX +(if LESS environment variable is set, Git does not change it at +all). If you want to selectively override Git's default setting +for LESS, you can set core.pager to e.g. less -S. This will +be passed to the shell by Git, which will translate the final +command to LESS=FRX less -S. The environment does not set the +S option but the command line does, instructing less to truncate +long lines. Similarly, setting core.pager to less -+F will +deactivate the F option specified by the environment from the +command-line, deactivating the "quit if one screen" behavior of +less. One can specifically activate some flags for particular +commands: for example, setting pager.blame to less -S enables +line truncation only for git blame. +Likewise, when the LV environment variable is unset, Git sets it +to -c. You can override this setting by exporting LV with +another value or setting core.pager to lv +c. @@ -1386,7 +1698,7 @@ core.whitespace tabwidth=<n> tells how many character positions a tab occupies; this - is relevant for indent-with-non-tab and when git fixes tab-in-indent + is relevant for indent-with-non-tab and when Git fixes tab-in-indent errors. The default tab width is 8. Allowed values are 1 to 63. @@ -1395,7 +1707,7 @@ core.whitespace -core.fsyncobjectfiles +core.fsyncObjectFiles @@ -1409,7 +1721,7 @@ and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback"). -core.preloadindex +core.preloadIndex @@ -1417,9 +1729,9 @@ core.preloadindex This can speed up operations like git diff and git status especially on filesystems like NFS that have weak caching semantics and thus -relatively high IO latencies. With this set to true, git will do the +relatively high IO latencies. When enabled, Git will do the index comparison to the filesystem data in parallel, allowing -overlapping IO's. +overlapping IO's. Defaults to true. @@ -1478,19 +1790,18 @@ core.abbrev -add.ignore-errors +add.ignoreErrors -add.ignoreErrors +add.ignore-errors (deprecated) Tells git add to continue adding files when some files cannot be added due to indexing errors. Equivalent to the --ignore-errors - option of . Older versions of git accept only - add.ignore-errors, which does not follow the usual naming - convention for configuration variables. Newer versions of git - honor add.ignoreErrors as well. + option of . add.ignore-errors is deprecated, + as it does not follow the usual naming convention for configuration + variables. @@ -1504,9 +1815,9 @@ alias.* after defining "alias.last = cat-file commit HEAD", the invocation "git last" is equivalent to "git cat-file commit HEAD". To avoid confusion and troubles with script usage, aliases that - hide existing git commands are ignored. Arguments are split by + hide existing Git commands are ignored. Arguments are split by spaces, the usual shell quoting and escaping is supported. - quote pair and a backslash can be used to quote them. + A quote pair or a backslash can be used to quote them. If the alias expansion is prefixed with an exclamation point, it will be treated as a shell command. For example, defining @@ -1535,7 +1846,22 @@ am.keepcr -apply.ignorewhitespace +am.threeWay + + + + By default, git am will fail if the patch does not apply cleanly. When + set to true, this setting tells git am to 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 available locally (equivalent to giving the --3way + option from the command line). Defaults to false. + See . + + + + + +apply.ignoreWhitespace @@ -1561,7 +1887,7 @@ apply.whitespace -branch.autosetupmerge +branch.autoSetupMerge @@ -1580,12 +1906,12 @@ branch.autosetupmerge -branch.autosetuprebase +branch.autoSetupRebase When a new branch is created with git branch or git checkout - that tracks another branch, this variable tells git to set + that tracks another branch, this variable tells Git to set up pull to rebase instead of merge (see "branch.<name>.rebase"). When never, rebase is never automatically set to true. When local, rebase is set to true for tracked branches of @@ -1594,7 +1920,7 @@ branch.autosetuprebase remote-tracking branches. When always, rebase will be set to true for all tracking branches. - See "branch.autosetupmerge" for details on how to set up a + See "branch.autoSetupMerge" for details on how to set up a branch to track another branch. This option defaults to never. @@ -1606,9 +1932,31 @@ branch.<name>.remote - When in branch <name>, it tells git fetch and git push which - remote to fetch from/push to. It defaults to origin if no remote is - configured. origin is also used if you are not on any branch. + When on branch <name>, it tells git fetch and git push + which remote to fetch from/push to. The remote to push to + may be overridden with remote.pushDefault (for all branches). + The remote to push to, for the current branch, may be further + overridden by branch.<name>.pushRemote. If no remote is + configured, or if you are not on any branch, it defaults to + origin for fetching and remote.pushDefault for pushing. + Additionally, . (a period) is the current local repository + (a dot-repository), see branch.<name>.merge's final note below. + + + + + +branch.<name>.pushRemote + + + + When on branch <name>, it overrides branch.<name>.remote for + pushing. It also overrides remote.pushDefault for pushing + from branch <name>. When you pull from one place (e.g. your + upstream) and push to another place (e.g. your own publishing + repository), you would want to set remote.pushDefault to + specify the remote to push to for all branches, and use this + option to override it for a specific branch. @@ -1632,14 +1980,14 @@ branch.<name>.merge Specify multiple values to get an octopus merge. If you wish to setup git pull so that it merges into <name> from another branch in the local repository, you can point - branch.<name>.merge to the desired branch, and use the special setting - . (a period) for branch.<name>.remote. + branch.<name>.merge to the desired branch, and use the relative path + setting . (a period) for branch.<name>.remote. -branch.<name>.mergeoptions +branch.<name>.mergeOptions @@ -1661,6 +2009,10 @@ branch.<name>.rebase "git pull" is run. See "pull.rebase" for doing this in a non branch-specific manner. +When preserve, also pass --preserve-merges along to git rebase +so that locally committed merge commits will not be flattened +by running git pull. +When the value is interactive, the rebase is run in interactive mode. NOTE: this is a possibly dangerous operation; do not use it unless you understand the implications (see for details). @@ -1668,6 +2020,19 @@ for details). +branch.<name>.description + + + + Branch description, can be edited with + git branch --edit-description. Branch description is + automatically added in the format-patch cover letter or + request-pull summary. + + + + + browser.<tool>.cmd @@ -1696,8 +2061,8 @@ clean.requireForce - A boolean to make git-clean do nothing unless given -f - or -n. Defaults to true. + A boolean to make git-clean do nothing unless given -f, + -i or -n. Defaults to true. @@ -1722,16 +2087,10 @@ color.branch.<slot> Use customized color for branch coloration. <slot> is one of current (the current branch), local (a local branch), - remote (a remote-tracking branch in refs/remotes/), plain (other + remote (a remote-tracking branch in refs/remotes/), + upstream (upstream tracking branch), plain (other refs). -The value for these configuration variables is a list of colors (at most -two) and attributes (at most one), separated by spaces. The colors -accepted are normal, black, red, green, yellow, blue, -magenta, cyan and white; the attributes are bold, dim, ul, -blink and reverse. The first color given is the foreground; the -second is the background. The position of the attribute, if any, -doesn't matter. @@ -1747,7 +2106,7 @@ color.diff commands will only use color when output is to the terminal. Defaults to false. -This does not affect nor the +This does not affect or the git-diff-* plumbing commands. Can be overridden on the command line with the --color[=<when>] option. @@ -1760,11 +2119,11 @@ color.diff.<slot> Use customized color for diff colorization. <slot> specifies which part of the patch to use the specified color, and is one - of plain (context text), meta (metainformation), frag + of context (context text - plain is a historical synonym), + meta (metainformation), frag (hunk header), func (function in hunk header), old (removed lines), new (added lines), commit (commit headers), or whitespace - (highlighting whitespace errors). The values of these variables may be - specified as in color.branch.<slot>. + (highlighting whitespace errors). @@ -1848,45 +2207,65 @@ color.grep.<slot> - matching text + matching text (same as setting matchContext and matchSelected) -selected +matchContext - non-matching text in selected lines + matching text in context lines -separator +matchSelected - separators between fields on a line (:, -, and =) - and between hunks (--) + matching text in selected lines - -The values of these variables may be specified as in color.branch.<slot>. - - -color.interactive +selected - When set to always, always use colors for interactive prompts - and displays (such as those used by "git-add --interactive"). - When false (or never), never. When set to true or auto, use - colors only when the output is to the terminal. Defaults to false. + non-matching text in selected lines + + + + + +separator + + + + separators between fields on a line (:, -, and =) + and between hunks (--) + + + + + + + + +color.interactive + + + + When set to always, always use colors for interactive prompts + and displays (such as those used by "git-add --interactive" and + "git-clean --interactive"). When false (or never), never. + When set to true or auto, use colors only when the output is + to the terminal. Defaults to false. @@ -1896,11 +2275,10 @@ color.interactive.<slot> - Use customized color for git add --interactive - output. <slot> may be prompt, header, help or error, for - four distinct types of normal output from interactive - commands. The values of these variables may be specified as - in color.branch.<slot>. + Use customized color for git add --interactive and git clean + --interactive output. <slot> may be prompt, header, help + or error, for four distinct types of normal output from + interactive commands. @@ -1917,7 +2295,7 @@ color.pager -color.showbranch +color.showBranch @@ -1951,11 +2329,11 @@ color.status.<slot> one of header (the header text of the status message), added or updated (files which are added but not committed), changed (files which are changed but not added in the index), - untracked (files which are not tracked by git), - branch (the current branch), or + untracked (files which are not tracked by Git), + branch (the current branch), nobranch (the color the no branch warning is shown in, defaulting - to red). The values of these variables may be specified as in - color.branch.<slot>. + to red), or + unmerged (files which have unmerged changes). @@ -1969,11 +2347,12 @@ color.ui as color.diff and color.grep that control the use of color per command family. Its scope will expand as more commands learn configuration to set a default for the --color option. Set it - to always if you want all output not intended for machine - consumption to use color, to true or auto if you want such - output to use color when written to the terminal, or to false or - never if you prefer git commands not to use color unless enabled - explicitly with some other configuration or the --color option. + to false or never if you prefer Git commands not to use + color unless enabled explicitly with some other configuration + or the --color option. Set it to always if you want all + output not intended for machine consumption to use color, to + true or auto (this is the default since Git 1.8.4) if you + want such output to use color when written to the terminal. @@ -1987,6 +2366,8 @@ column.ui This variable consists of a list of tokens separated by spaces or commas: +These options control when the feature should be enabled +(defaults to never): @@ -2018,13 +2399,18 @@ column.ui + +These options control layout (defaults to column). Setting any +of these implies always if none of always, never, or auto are +specified. + column - fill columns before rows (default) + fill columns before rows @@ -2048,6 +2434,10 @@ column.ui + +Finally, these options can be combined with a layout option (defaults +to nodense): + dense @@ -2069,7 +2459,6 @@ column.ui -This option defaults to never. @@ -2085,6 +2474,17 @@ column.branch +column.clean + + + + Specify the layout when list items in git clean -i, which always + shows files and directories in columns. See column.ui for details. + + + + + column.status @@ -2107,6 +2507,36 @@ column.tag +commit.cleanup + + + + This setting overrides the default of the --cleanup option in + git commit. See for details. Changing the + default can be useful when you always want to keep lines that begin + with comment character # in your log message, in which case you + would do git config commit.cleanup whitespace (note that you will + have to remove the help lines that begin with # in the commit log + template yourself, if you do this). + + + + + +commit.gpgSign + + + + A boolean to specify whether all commits should be GPG signed. + Use of this option when doing operations such as rebase can + result in a large number of commits being signed. It may be + convenient to use an agent to avoid typing your GPG passphrase + several times. + + + + + commit.status @@ -2137,8 +2567,9 @@ credential.helper Specify an external helper to be called when a username or password credential is needed; the helper may consult external - storage to avoid prompting the user for the credentials. See - for details. + storage to avoid prompting the user for the credentials. Note + that multiple helpers may be defined. See + for details. @@ -2182,7 +2613,17 @@ credential.<url>.* -diff.autorefreshindex +credentialCache.ignoreSIGHUP + + + + Tell git-credential-cache--daemon to ignore SIGHUP, instead of quitting. + + + + + +diff.autoRefreshIndex @@ -2333,13 +2774,17 @@ diff.ignoreSubmodules Sets the default value of --ignore-submodules. Note that this affects only git diff Porcelain, and not lower level diff commands such as git diff-files. git checkout also honors - this setting when reporting uncommitted changes. + this setting when reporting uncommitted changes. Setting it to + all disables the submodule summary normally shown by git commit + and git status when status.submoduleSummary is set unless it is + overridden by using the --ignore-submodules command-line option. + The git submodule commands are not affected by this setting. -diff.mnemonicprefix +diff.mnemonicPrefix @@ -2414,6 +2859,18 @@ diff.noprefix +diff.orderFile + + + + File indicating how to order files within a diff, using + one shell glob pattern per line. + Can be overridden by the -O option to . + + + + + diff.renameLimit @@ -2429,9 +2886,13 @@ diff.renames - Tells git to detect renames. If set to any boolean value, it - will enable basic rename detection. If set to "copies" or - "copy", it will detect copies, as well. + Whether and how Git detects renames. If set to "false", + rename detection is disabled. If set to "true", basic rename + detection is enabled. If set to "copies" or "copy", Git will + detect copies, as well. Defaults to true. Note that this + affects only git diff Porcelain like and + , and not lower level commands such as + . @@ -2522,7 +2983,7 @@ diff.<driver>.textconv -diff.<driver>.wordregex +diff.<driver>.wordRegex @@ -2549,15 +3010,190 @@ diff.tool - The diff tool to be used by . This - option overrides merge.tool, and has the same valid built-in - values as merge.tool minus "tortoisemerge" and plus - "kompare". Any other value is treated as a custom diff tool, - and there must be a corresponding difftool.<tool>.cmd - option. + Controls which diff tool is used by . + This variable overrides the value configured in merge.tool. + The list below shows the valid built-in values. + Any other value is treated as a custom diff tool and requires + that a corresponding difftool.<tool>.cmd variable is defined. + + + + +araxis + + + + +bc + + + + +bc3 + + + + +codecompare + + + + +deltawalker + + + + +diffmerge + + + + +diffuse + + + + +ecmerge + + + + +emerge + + + + +examdiff + + + + +gvimdiff + + + + +gvimdiff2 + + + + +gvimdiff3 + + + + +kdiff3 + + + + +kompare + + + + +meld + + + + +opendiff + + + + +p4merge + + + + +tkdiff + + + + +vimdiff + + + + +vimdiff2 + + + + +vimdiff3 + + + + +winmerge + + + + +xxdiff + + + + + + + +diff.algorithm + + + + Choose a diff algorithm. The variants are as follows: + + + + +default, myers + + + + The basic greedy diff algorithm. Currently, this is the default. + + + + + +minimal + + + + Spend extra time to make sure the smallest possible diff is + produced. + + + + + +patience + + + + Use "patience diff" algorithm when generating patches. + + + + + +histogram + + + + This algorithm extends the patience algorithm to "support + low-occurrence common elements". + + + difftool.<tool>.path @@ -2630,7 +3266,7 @@ fetch.unpackLimit - If the number of objects fetched over the git native + If the number of objects fetched over the Git native transfer is below this limit, then the objects will be unpacked into loose object files. However if the number of received objects equals or @@ -2644,6 +3280,17 @@ fetch.unpackLimit +fetch.prune + + + + If true, fetch will automatically behave as if the --prune + option was given on the command line. See also remote.<name>.prune. + + + + + format.attach @@ -2698,7 +3345,7 @@ format.cc -format.subjectprefix +format.subjectPrefix @@ -2714,7 +3361,7 @@ format.signature The default for format-patch is to output a signature containing - the git version number. Use this variable to change that default. + the Git version number. Use this variable to change that default. Set this variable to the empty string ("") to suppress signature generation. @@ -2722,6 +3369,17 @@ format.signature +format.signatureFile + + + + Works just like format.signature except the contents of the + file specified by this variable will be used as the signature. + + + + + format.suffix @@ -2763,84 +3421,161 @@ format.thread -format.signoff +format.signOff - A boolean value which lets you enable the -s/--signoff option of - format-patch by default. Note: Adding the Signed-off-by: line to a - patch should be a conscious act and means that you certify you have - the rights to submit this work under the same open source license. - Please see the SubmittingPatches document for further discussion. + A boolean value which lets you enable the -s/--signoff option of + format-patch by default. Note: Adding the Signed-off-by: line to a + patch should be a conscious act and means that you certify you have + the rights to submit this work under the same open source license. + Please see the SubmittingPatches document for further discussion. -filter.<driver>.clean +format.coverLetter - The command which is used to convert the content of a worktree - file to a blob upon checkin. See for - details. + A boolean that controls whether to generate a cover-letter when + format-patch is invoked, but in addition can be set to "auto", to + generate a cover-letter only when there's more than one patch. -filter.<driver>.smudge +format.outputDirectory - The command which is used to convert the content of a blob - object to a worktree file upon checkout. See - for details. + Set a custom directory to store the resulting files instead of the + current working directory. -gc.aggressiveWindow +filter.<driver>.clean - The window size parameter used in the delta compression - algorithm used by git gc --aggressive. This defaults - to 250. + The command which is used to convert the content of a worktree + file to a blob upon checkin. See for + details. -gc.auto +filter.<driver>.smudge - When there are approximately more than this many loose - objects in the repository, git gc --auto will pack them. - Some Porcelain commands use this command to perform a - light-weight garbage collection from time to time. The - default value is 6700. Setting this to 0 disables it. + The command which is used to convert the content of a blob + object to a worktree file upon checkout. See + for details. -gc.autopacklimit +fsck.<msg-id> - When there are more than this many packs that are not - marked with *.keep file in the repository, git gc - --auto consolidates them into one larger pack. The - default value is 50. Setting this to 0 disables it. + Allows overriding the message type (error, warn or ignore) of a + specific message ID such as missingEmail. +For convenience, fsck prefixes the error/warning with the message ID, +e.g. "missingEmail: invalid author/committer line - missing email" means +that setting fsck.missingEmail = ignore will hide that issue. +This feature is intended to support working with legacy repositories +which cannot be repaired without disruptive changes. -gc.packrefs +fsck.skipList + + + + The path to a sorted list of object names (i.e. one SHA-1 per + line) that are known to be broken in a non-fatal way and should + be ignored. This feature is useful when an established project + should be accepted despite early commits containing errors that + can be safely ignored such as invalid committer email addresses. + Note: corrupt objects cannot be skipped with this setting. + + + + + +gc.aggressiveDepth + + + + The depth parameter used in the delta compression + algorithm used by git gc --aggressive. This defaults + to 250. + + + + + +gc.aggressiveWindow + + + + The window size parameter used in the delta compression + algorithm used by git gc --aggressive. This defaults + to 250. + + + + + +gc.auto + + + + When there are approximately more than this many loose + objects in the repository, git gc --auto will pack them. + Some Porcelain commands use this command to perform a + light-weight garbage collection from time to time. The + default value is 6700. Setting this to 0 disables it. + + + + + +gc.autoPackLimit + + + + When there are more than this many packs that are not + marked with *.keep file in the repository, git gc + --auto consolidates them into one larger pack. The + default value is 50. Setting this to 0 disables it. + + + + + +gc.autoDetach + + + + Make git gc --auto return immediately and run in background + if the system supports it. Default is true. + + + + + +gc.packRefs @@ -2855,28 +3590,46 @@ gc.packrefs -gc.pruneexpire +gc.pruneExpire When git gc is run, it will call prune --expire 2.weeks.ago. Override the grace period with this config variable. The value - "now" may be used to disable this grace period and always prune - unreachable objects immediately. + "now" may be used to disable this grace period and always prune + unreachable objects immediately, or "never" may be used to + suppress pruning. -gc.reflogexpire +gc.worktreePruneExpire + + + + When git gc is run, it calls + git worktree prune --expire 3.months.ago. + This config variable can be used to set a different grace + period. The value "now" may be used to disable the grace + period and prune $GIT_DIR/worktrees immediately, or "never" + may be used to suppress pruning. + + + + + +gc.reflogExpire -gc.<pattern>.reflogexpire +gc.<pattern>.reflogExpire git reflog expire removes reflog entries older than - this time; defaults to 90 days. With "<pattern>" (e.g. + this time; defaults to 90 days. The value "now" expires all + entries immediately, and "never" suppresses expiration + altogether. With "<pattern>" (e.g. "refs/stash") in the middle the setting applies only to the refs that match the <pattern>. @@ -2884,16 +3637,18 @@ gc.<pattern>.reflogexpire -gc.reflogexpireunreachable +gc.reflogExpireUnreachable -gc.<ref>.reflogexpireunreachable +gc.<pattern>.reflogExpireUnreachable git reflog expire removes reflog entries older than this time and are not reachable from the current tip; - defaults to 30 days. With "<pattern>" (e.g. "refs/stash") + defaults to 30 days. The value "now" expires all entries + immediately, and "never" suppresses expiration altogether. + With "<pattern>" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the <pattern>. @@ -2901,7 +3656,7 @@ gc.<ref>.reflogexpireunreachable -gc.rerereresolved +gc.rerereResolved @@ -2913,7 +3668,7 @@ gc.rerereresolved -gc.rerereunresolved +gc.rerereUnresolved @@ -2925,7 +3680,7 @@ gc.rerereunresolved -gitcvs.commitmsgannotation +gitcvs.commitMsgAnnotation @@ -2947,7 +3702,7 @@ gitcvs.enabled -gitcvs.logfile +gitcvs.logFile @@ -2964,19 +3719,19 @@ gitcvs.usecrlfattr If true, the server will look up the end-of-line conversion attributes for files to determine the -k modes to use. If - the attributes force git to treat a file as text, + the attributes force Git to treat a file as text, the -k mode will be left blank so CVS clients will treat it as text. If they suppress text conversion, the file will be set with -kb mode, which suppresses any newline munging the client might otherwise do. If the attributes do not allow - the file type to be determined, then gitcvs.allbinary is + the file type to be determined, then gitcvs.allBinary is used. See . -gitcvs.allbinary +gitcvs.allBinary @@ -2993,12 +3748,12 @@ gitcvs.allbinary -gitcvs.dbname +gitcvs.dbName Database used by git-cvsserver to cache revision information - derived from the git repository. The exact meaning depends on the + derived from the Git repository. The exact meaning depends on the used database driver, for SQLite (which is the default driver) this is a filename. Supports variable substitution (see for details). May not contain semicolons (;). @@ -3008,7 +3763,7 @@ gitcvs.dbname -gitcvs.dbdriver +gitcvs.dbDriver @@ -3023,13 +3778,13 @@ gitcvs.dbdriver -gitcvs.dbuser, gitcvs.dbpass +gitcvs.dbUser, gitcvs.dbPass - Database user and password. Only useful if setting gitcvs.dbdriver, + Database user and password. Only useful if setting gitcvs.dbDriver, since SQLite has no concept of database users and/or passwords. - gitcvs.dbuser supports variable substitution (see + gitcvs.dbUser supports variable substitution (see for details). @@ -3050,7 +3805,7 @@ gitcvs.dbTableNamePrefix All gitcvs variables except for gitcvs.usecrlfattr and -gitcvs.allbinary can also be specified as +gitcvs.allBinary can also be specified as gitcvs.<access_method>.<varname> (where access_method is one of "ext" and "pserver") to make them apply only for the given access method. @@ -3097,7 +3852,7 @@ gitweb.pickaxe gitweb.remote_heads -gitweb.showsizes +gitweb.showSizes gitweb.snapshot @@ -3145,16 +3900,38 @@ grep.extendedRegexp +grep.threads + + + + Number of grep worker threads to use. + See grep.threads in for more information. + + + + + +grep.fallbackToNoIndex + + + + If set to true, fall back to git grep --no-index if git grep + is executed outside of a git repository. Defaults to false. + + + + + gpg.program Use this custom program instead of "gpg" found on $PATH when making or verifying a PGP signature. The program must support the - same command line interface as GPG, namely, to verify a detached + same command-line interface as GPG, namely, to verify a detached signature, "gpg --verify $file - <$signature" is run, and the program is expected to signal a good signature by exiting with - code 0, and to generate an ascii-armored detached signature, the + code 0, and to generate an ASCII-armored detached signature, the standard input of "gpg -bsau $key" is fed with the contents to be signed, and the program is expected to send the result to its standard output. @@ -3163,7 +3940,7 @@ gpg.program -gui.commitmsgwidth +gui.commitMsgWidth @@ -3174,7 +3951,7 @@ gui.commitmsgwidth -gui.diffcontext +gui.diffContext @@ -3185,6 +3962,17 @@ gui.diffcontext +gui.displayUntracked + + + + Determines if shows untracked files + in the file list. The default is "true". + + + + + gui.encoding @@ -3200,7 +3988,7 @@ gui.encoding -gui.matchtrackingbranch +gui.matchTrackingBranch @@ -3212,7 +4000,7 @@ gui.matchtrackingbranch -gui.newbranchtemplate +gui.newBranchTemplate @@ -3223,7 +4011,7 @@ gui.newbranchtemplate -gui.pruneduringfetch +gui.pruneDuringFetch @@ -3245,7 +4033,7 @@ gui.trustmtime -gui.spellingdictionary +gui.spellingDictionary @@ -3257,7 +4045,7 @@ gui.spellingdictionary -gui.fastcopyblame +gui.fastCopyBlame @@ -3269,7 +4057,7 @@ gui.fastcopyblame -gui.copyblamethreshold +gui.copyBlameThreshold @@ -3310,7 +4098,7 @@ guitool.<name>.cmd -guitool.<name>.needsfile +guitool.<name>.needsFile @@ -3321,7 +4109,7 @@ guitool.<name>.needsfile -guitool.<name>.noconsole +guitool.<name>.noConsole @@ -3332,7 +4120,7 @@ guitool.<name>.noconsole -guitool.<name>.norescan +guitool.<name>.noRescan @@ -3353,7 +4141,7 @@ guitool.<name>.confirm -guitool.<name>.argprompt +guitool.<name>.argPrompt @@ -3368,23 +4156,23 @@ guitool.<name>.argprompt -guitool.<name>.revprompt +guitool.<name>.revPrompt Request a single valid revision from the user, and set the REVISION environment variable. In other aspects this option - is similar to argprompt, and can be used together with it. + is similar to argPrompt, and can be used together with it. -guitool.<name>.revunmerged +guitool.<name>.revUnmerged - Show only unmerged branches in the revprompt subdialog. + Show only unmerged branches in the revPrompt subdialog. This is useful for tools similar to merge or rebase, but not for things like checkout or reset. @@ -3408,7 +4196,7 @@ guitool.<name>.prompt Specifies the general prompt string to display at the top of - the dialog, before subsections for argprompt and revprompt. + the dialog, before subsections for argPrompt and revPrompt. The default value includes the actual command. @@ -3438,7 +4226,7 @@ help.format -help.autocorrect +help.autoCorrect @@ -3454,30 +4242,190 @@ help.autocorrect +help.htmlPath + + + + Specify the path where the HTML documentation resides. File system paths + and URLs are supported. HTML pages will be prefixed with this path when + help is displayed in the web format. This defaults to the documentation + path of your Git installation. + + + + + http.proxy Override the HTTP proxy, normally configured using the http_proxy, - https_proxy, and all_proxy environment variables (see - curl(1)). This can be overridden on a per-remote basis; see - remote.<name>.proxy + https_proxy, and all_proxy environment variables (see curl(1)). In + addition to the syntax understood by curl, it is possible to specify a + proxy string with a user name but no password, in which case git will + attempt to acquire one in the same way it does for other credentials. See + for more information. The syntax thus is + [protocol://][user[:password]@]proxyhost[:port]. This can be overridden + on a per-remote basis; see remote.<name>.proxy + + + + + +http.proxyAuthMethod + + + + Set the method with which to authenticate against the HTTP proxy. This + only takes effect if the configured proxy string contains a user name part + (i.e. is of the form user@host or user@host:port). This can be + overridden on a per-remote basis; see remote.<name>.proxyAuthMethod. + Both can be overridden by the GIT_HTTP_PROXY_AUTHMETHOD environment + variable. Possible values are: + + + + +anyauth - Automatically pick a suitable authentication method. It is + assumed that the proxy answers an unauthenticated request with a 407 + status code and one or more Proxy-authenticate headers with supported + authentication methods. This is the default. + + + + +basic - HTTP Basic authentication + + + + +digest - HTTP Digest authentication; this prevents the password from being + transmitted to the proxy in clear text + + + + +negotiate - GSS-Negotiate authentication (compare the --negotiate option + of curl(1)) + + + + +ntlm - NTLM authentication (compare the --ntlm option of curl(1)) + + + + + + + +http.emptyAuth + + + + Attempt authentication without seeking a username or password. This + can be used to attempt GSS-Negotiate authentication without specifying + a username in the URL, as libcurl normally requires a username for + authentication. -http.cookiefile +http.cookieFile File containing previously stored cookie lines which should be used - in the git http session, if they match the server. The file format + in the Git http session, if they match the server. The file format of the file to read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie file format (see ). - NOTE that the file specified with http.cookiefile is only used as - input. No cookies will be stored in the file. + NOTE that the file specified with http.cookieFile is only used as + input unless http.saveCookies is set. + + + + + +http.saveCookies + + + + If set, store cookies received during requests to the file specified by + http.cookieFile. Has no effect if http.cookieFile is unset. + + + + + +http.sslVersion + + + + The SSL version to use when negotiating an SSL connection, if you + want to force the default. The available and default version + depend on whether libcurl was built against NSS or OpenSSL and the + particular configuration of the crypto library in use. Internally + this sets the CURLOPT_SSL_VERSION option; see the libcurl + documentation for more details on the format of this option and + for the ssl version supported. Actually the possible values of + this option are: + + + + +sslv2 + + + + +sslv3 + + + + +tlsv1 + + + + +tlsv1.0 + + + + +tlsv1.1 + + + + +tlsv1.2 + + + +Can be overridden by the GIT_SSL_VERSION environment variable. +To force git to use libcurl's default ssl version and ignore any +explicit http.sslversion option, set GIT_SSL_VERSION to the +empty string. + + + + +http.sslCipherList + + + + A list of SSL ciphers to use when negotiating an SSL connection. + The available ciphers depend on whether libcurl was built against + NSS or OpenSSL and the particular configuration of the crypto + library in use. Internally this sets the CURLOPT_SSL_CIPHER_LIST + option; see the libcurl documentation for more details on the format + of this list. +Can be overridden by the GIT_SSL_CIPHER_LIST environment variable. +To force git to use libcurl's default cipher list and ignore any +explicit http.sslCipherList option, set GIT_SSL_CIPHER_LIST to the +empty string. @@ -3522,7 +4470,7 @@ http.sslCertPasswordProtected - Enable git's password prompt for the SSL certificate. Otherwise + Enable Git's password prompt for the SSL certificate. Otherwise OpenSSL will prompt the user, possibly many times, if the certificate or private key is encrypted. Can be overridden by the GIT_SSL_CERT_PASSWORD_PROTECTED environment variable. @@ -3555,6 +4503,36 @@ http.sslCAPath +http.pinnedpubkey + + + + Public key of the https service. It may either be the filename of + a PEM or DER encoded public key file or a string starting with + sha256// followed by the base64 encoded sha256 hash of the + public key. See also libcurl CURLOPT_PINNEDPUBLICKEY. git will + exit with an error if this option is set but not supported by + cURL. + + + + + +http.sslTry + + + + Attempt to use AUTH SSL/TLS and encrypted data transfers + when connecting via regular FTP protocol. This might be needed + if the FTP server requires it for security reasons or you wish + to connect securely whenever remote FTP server supports it. + Default is false since it might trigger certificate verification + errors on misconfigured servers. + + + + + http.maxRequests @@ -3620,12 +4598,12 @@ http.noEPSV -http.useragent +http.userAgent The HTTP USER_AGENT string presented to an HTTP server. The default - value represents the version of the client git such as git/1.7.1. + value represents the version of the client Git such as git/1.7.1. This option allows you to override this value to a more common value such as Mozilla/4.0. This may be necessary, for instance, if connecting through a firewall that restricts HTTP connections to a set @@ -3636,11 +4614,76 @@ http.useragent +http.<url>.* + + + + Any of the http.* options above can be applied selectively to some URLs. + For a config key to match a URL, each element of the config key is + compared to that of the URL, in the following order: + + + + +Scheme (e.g., https in https://example.com/). This field + must match exactly between the config key and the URL. + + + + +Host/domain name (e.g., example.com in https://example.com/). + This field must match exactly between the config key and the URL. + + + + +Port number (e.g., 8080 in http://example.com:8080/). + This field must match exactly between the config key and the URL. + Omitted port numbers are automatically converted to the correct + default for the scheme before matching. + + + + +Path (e.g., repo.git in https://example.com/repo.git). The + path field of the config key must match the path field of the URL + either exactly or as a prefix of slash-delimited path elements. This means + a config key with path foo/ matches URL path foo/bar. A prefix can only + match on a slash (/) boundary. Longer matches take precedence (so a config + key with path foo/bar is a better match to URL path foo/bar than a config + key with just path foo/). + + + + +User name (e.g., user in https://user@example.com/repo.git). If + the config key has a user name it must match the user name in the + URL exactly. If the config key does not have a user name, that + config key will match a URL with any user name (including none), + but at a lower precedence than a config key with a user name. + + + +The list above is ordered by decreasing precedence; a URL that matches +a config key's path is preferred to one that matches its user name. For example, +if the URL is https://user@example.com/foo/bar a config key match of +https://example.com/foo will be preferred over a config key match of +https://user@example.com. +All URLs are normalized before attempting any matching (the password part, +if embedded in the URL, is always ignored for matching purposes) so that +equivalent URLs that are simply spelled differently will match properly. +Environment variable settings always override any matches. The URLs that are +matched against are those given directly to Git commands. This means any URLs +visited as a result of a redirection do not participate in matching. + + + + i18n.commitEncoding - Character encoding the commit messages are stored in; git itself + Character encoding the commit messages are stored in; Git itself does not care per se, but this information is necessary e.g. when importing commits from emails or in the gitk graphical history browser (and possibly at other places in the future or in other @@ -3672,7 +4715,18 @@ imap -init.templatedir +index.version + + + + Specify the version with which new index files should be + initialized. This does not affect existing repositories. + + + + + +init.templateDir @@ -3716,7 +4770,7 @@ instaweb.local -instaweb.modulepath +instaweb.modulePath @@ -3739,7 +4793,7 @@ instaweb.port -interactive.singlekey +interactive.singleKey @@ -3749,7 +4803,22 @@ interactive.singlekey , , , , and . Note that this setting is silently ignored if portable keystroke input - is not available. + is not available; requires the Perl module Term::ReadKey. + + + + + +interactive.diffFilter + + + + When an interactive command (such as git add --patch) shows + a colorized diff, git will pipe the diff through the shell + command defined by this configuration variable. The command may + mark up the diff further for human consumption, provided that it + retains a one-to-one correspondence with the lines in the + original diff. Defaults to disabled (no filtering). @@ -3773,9 +4842,7 @@ log.date Set the default date-time mode for the log command. Setting a value for log.date is similar to using git log's - --date option. Possible values are relative, local, - default, iso, rfc, and short; see - for details. + --date option. See for details. @@ -3795,11 +4862,24 @@ log.decorate -log.showroot +log.follow - If true, the initial commit will be shown as a big creation event. + If true, git log will act as if the --follow option was used when + a single <path> is given. This has the same limitations as --follow, + i.e. it cannot be used to follow multiple files and does not work well + on non-linear history. + + + + + +log.showRoot + + + + If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. Tools like or , which normally hide the root commit will now show it. True by default. @@ -3808,6 +4888,31 @@ log.showroot +log.mailmap + + + + If true, makes , , and + assume --use-mailmap. + + + + + +mailinfo.scissors + + + + If true, makes (and therefore + ) act by default as if the --scissors option + was provided on the command-line. When active, this features + removes everything from the message body before a scissors + line (i.e. consisting mainly of ">8", "8<" and "-"). + + + + + mailmap.file @@ -3823,6 +4928,21 @@ mailmap.file +mailmap.blob + + + + Like mailmap.file, but consider the value as a reference to a + blob in the repository. If both mailmap.file and + mailmap.blob are given, both are parsed, with entries from + mailmap.file taking precedence. In a bare repository, this + defaults to HEAD:.mailmap. In a non-bare repository, it + defaults to empty. + + + + + man.viewer @@ -3857,7 +4977,7 @@ man.<tool>.path -merge.conflictstyle +merge.conflictStyle @@ -3893,10 +5013,10 @@ merge.ff - By default, git does not create an extra merge commit when merging + By default, Git does not create an extra merge commit when merging a commit that is a descendant of the current commit. Instead, the tip of the current branch is fast-forwarded. When set to false, - this variable tells git to create an extra merge commit in such + this variable tells Git to create an extra merge commit in such a case (equivalent to giving the --no-ff option from the command line). When set to only, only such fast-forward merges are allowed (equivalent to giving the --ff-only option from the @@ -3906,6 +5026,18 @@ merge.ff +merge.branchdesc + + + + In addition to branch names, populate the log message with + the branch description text associated with them. Defaults + to false. + + + + + merge.log @@ -3935,10 +5067,10 @@ merge.renormalize - Tell git that canonical representation of files in the + Tell Git that canonical representation of files in the repository has changed over time (e.g. earlier commits record text files with CRLF line endings, but recent ones use LF line - endings). In such a repository, git can convert the data + endings). In such a repository, Git can convert the data recorded in commits to a canonical form before performing a merge to reduce unnecessary conflicts. For more information, see section "Merging branches with differing checkin/checkout @@ -3963,14 +5095,134 @@ merge.tool - Controls which merge resolution program is used by - . Valid built-in values are: "araxis", - "bc3", "diffuse", "ecmerge", "emerge", "gvimdiff", "kdiff3", "meld", - "opendiff", "p4merge", "tkdiff", "tortoisemerge", "vimdiff" - and "xxdiff". Any other value is treated is custom merge tool - and there must be a corresponding mergetool.<tool>.cmd option. + Controls which merge tool is used by . + The list below shows the valid built-in values. + Any other value is treated as a custom merge tool and requires + that a corresponding mergetool.<tool>.cmd variable is defined. + + + + +araxis + + + + +bc + + + + +bc3 + + + + +codecompare + + + + +deltawalker + + +diffmerge + + + + +diffuse + + + + +ecmerge + + + + +emerge + + + + +examdiff + + + + +gvimdiff + + + + +gvimdiff2 + + + + +gvimdiff3 + + + + +kdiff3 + + + + +meld + + + + +opendiff + + + + +p4merge + + + + +tkdiff + + + + +tortoisemerge + + + + +vimdiff + + + + +vimdiff2 + + + + +vimdiff3 + + + + +winmerge + + + + +xxdiff + + + + @@ -4067,6 +5319,22 @@ mergetool.<tool>.trustExitCode +mergetool.meld.hasOutput + + + + Older versions of meld do not support the --output option. + Git will attempt to detect whether meld supports --output + by inspecting the output of meld --help. Configuring + mergetool.meld.hasOutput will make Git skip these checks and + use the configured value instead. Setting mergetool.meld.hasOutput + to true tells Git to unconditionally use the --output option, + and false avoids using --output. + + + + + mergetool.keepBackup @@ -4084,7 +5352,7 @@ mergetool.keepTemporaries - When invoking a custom merge tool, git uses a set of temporary + When invoking a custom merge tool, Git uses a set of temporary files to pass to the tool. If the tool returns an error and this variable is set to true, then these temporary files will be preserved, otherwise they will be removed after the tool has @@ -4094,6 +5362,19 @@ mergetool.keepTemporaries +mergetool.writeToTemp + + + + Git writes temporary BASE, LOCAL, and REMOTE versions of + conflicting files in the worktree by default. Git will attempt + to use a temporary directory for these files when set true. + Defaults to false. + + + + + mergetool.prompt @@ -4104,6 +5385,32 @@ mergetool.prompt +notes.mergeStrategy + + + + Which merge strategy to choose by default when resolving notes + conflicts. Must be one of manual, ours, theirs, union, or + cat_sort_uniq. Defaults to manual. See "NOTES MERGE STRATEGIES" + section of for more information on each strategy. + + + + + +notes.<name>.mergeStrategy + + + + Which merge strategy to choose when doing a notes merge into + refs/notes/<name>. This overrides the more general + "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in + for more information on the available strategies. + + + + + notes.displayRef @@ -4131,7 +5438,7 @@ notes.rewrite.<command> When rewriting commits with <command> (currently amend or - rebase) and this variable is set to true, git + rebase) and this variable is set to true, Git automatically copies your notes from the original to the rewritten commit. Defaults to true, but see "notes.rewriteRef" below. @@ -4147,8 +5454,8 @@ notes.rewriteMode When copying notes during a rewrite (see the "notes.rewrite.<command>" option), determines what to do if the target commit already has a note. Must be one of - overwrite, concatenate, or ignore. Defaults to - concatenate. + overwrite, concatenate, cat_sort_uniq, or ignore. + Defaults to concatenate. This setting can be overridden with the GIT_NOTES_REWRITE_MODE environment variable. @@ -4201,10 +5508,11 @@ pack.windowMemory - The window memory size limit used by - when no limit is given on the command line. The value can be - suffixed with "k", "m", or "g". Defaults to 0, meaning no - limit. + The maximum size of memory that is consumed by each thread + in for pack window memory when + no limit is given on the command line. The value can be + suffixed with "k", "m", or "g". When left unconfigured (or + set explicitly to 0), there will be no limit. @@ -4270,7 +5578,7 @@ pack.threads warning. This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. - Specifying 0 will cause git to auto-detect the number of CPU's + Specifying 0 will cause Git to auto-detect the number of CPU's and set the number of threads accordingly. @@ -4289,11 +5597,11 @@ pack.indexVersion and this config option ignored whenever the corresponding pack is larger than 2 GB. -If you have an old git that does not understand the version 2 *.idx file, -cloning or fetching over a non native protocol (e.g. "http" and "rsync") +If you have an old Git that does not understand the version 2 *.idx file, +cloning or fetching over a non native protocol (e.g. "http") that will copy both *.pack file and corresponding *.idx file from the other side may give you a repository that cannot be accessed with your -older version of git. If the *.pack file is smaller than 2 GB, however, +older version of Git. If the *.pack file is smaller than 2 GB, however, you can use on the *.pack file to regenerate the *.idx file. @@ -4316,12 +5624,53 @@ pack.packSizeLimit +pack.useBitmaps + + + + When true, git will use pack bitmaps (if available) when packing + to stdout (e.g., during the server side of a fetch). Defaults to + true. You should not generally need to turn this off unless + you are debugging pack bitmaps. + + + + + +pack.writeBitmaps (deprecated) + + + + This is a deprecated synonym for repack.writeBitmaps. + + + + + +pack.writeBitmapHashCache + + + + When true, git will include a "hash cache" section in the bitmap + index (if one is written). This cache can be used to feed git's + delta heuristics, potentially leading to better deltas between + bitmapped and non-bitmapped objects (e.g., when serving a fetch + between an older, bitmapped pack and objects that have been + pushed since the last gc). The downside is that it consumes 4 + bytes per object of disk space, and that JGit's bitmap + implementation does not understand it, causing it to complain if + Git and JGit are used on the same repository. Defaults to false. + + + + + pager.<cmd> If the value is boolean, turns on or off pagination of the - output of a particular git subcommand when writing to a tty. + output of a particular Git subcommand when writing to a tty. Otherwise, turns on pagination for the subcommand using the pager specified by the value of pager.<cmd>. If --paginate or --no-pager is specified on the command line, it takes @@ -4349,6 +5698,23 @@ pretty.<name> +pull.ff + + + + By default, Git does not create an extra merge commit when merging + a commit that is a descendant of the current commit. Instead, the + tip of the current branch is fast-forwarded. When set to false, + this variable tells Git to create an extra merge commit in such + a case (equivalent to giving the --no-ff option from the command + line). When set to only, only such fast-forward merges are + allowed (equivalent to giving the --ff-only option from the + command line). This setting overrides merge.ff when pulling. + + + + + pull.rebase @@ -4358,6 +5724,10 @@ pull.rebase pull" is run. See "branch.<name>.rebase" for setting this on a per-branch basis. +When preserve, also pass --preserve-merges along to git rebase +so that locally committed merge commits will not be flattened +by running git pull. +When the value is interactive, the rebase is run in interactive mode. NOTE: this is a possibly dangerous operation; do not use it unless you understand the implications (see for details). @@ -4390,57 +5760,118 @@ push.default - Defines the action git push should take if no refspec is given - on the command line, no refspec is configured in the remote, and - no refspec is implied by any of the options given on the command - line. Possible values are: + Defines the action git push should take if no refspec is + explicitly given. Different values are well-suited for + specific workflows; for instance, in a purely central workflow + (i.e. the fetch source is equal to the push destination), + upstream is probably what you want. Possible values are: -nothing - do not push anything. +nothing - do not push anything (error out) unless a refspec is + explicitly given. This is primarily meant for people who want to + avoid mistakes by always being explicit. -matching - push all branches having the same name in both ends. - This is for those who prepare all the branches into a publishable - shape and then push them out with a single command. It is not - appropriate for pushing into a repository shared by multiple users, - since locally stalled branches will attempt a non-fast forward push - if other users updated the branch. - - This is currently the default, but Git 2.0 will change the default - to simple. +current - push the current branch to update a branch with the same + name on the receiving end. Works in both central and non-central + workflows. -upstream - push the current branch to its upstream branch. - With this, git push will update the same remote ref as the one which - is merged by git pull, making push and pull symmetrical. - See "branch.<name>.merge" for how to configure the upstream branch. +upstream - push the current branch back to the branch whose + changes are usually integrated into the current branch (which is + called @{upstream}). This mode only makes sense if you are + pushing to the same repository you would normally pull from + (i.e. central workflow). -simple - like upstream, but refuses to push if the upstream - branch's name is different from the local one. This is the safest - option and is well-suited for beginners. It will become the default - in Git 2.0. +simple - in centralized workflow, work like upstream with an + added safety to refuse to push if the upstream branch's name is + different from the local one. +When pushing to a remote that is different from the remote you normally +pull from, work as current. This is the safest option and is suited +for beginners. +This mode has become the default in Git 2.0. -current - push the current branch to a branch of the same name. +matching - push all branches having the same name on both ends. + This makes the repository you are pushing to remember the set of + branches that will be pushed out (e.g. if you always push maint + and master there and no other branches, the repository you push + to will have these two branches, and your local maint and + master will be pushed there). +To use this mode effectively, you have to make sure all the +branches you would push out are ready to be pushed out before +running git push, as the whole point of this mode is to allow you +to push all of the branches in one go. If you usually finish work +on only one branch and push out the result, while other branches are +unfinished, this mode is not for you. Also this mode is not +suitable for pushing into a shared central repository, as other +people may add new branches there, or update the tip of existing +branches outside your control. +This used to be the default, but not since Git 2.0 (simple is the +new default). -The simple, current and upstream modes are for those who want to -push out a single branch after finishing work, even when the other -branches are not yet ready to be pushed out. If you are working with -other people to push into the same shared repository, you would want -to use one of these. + + + + +push.followTags + + + + If set to true enable --follow-tags option by default. You + may override this configuration at time of push by specifying + --no-follow-tags. + + + + + +push.gpgSign + + + + May be set to a boolean value, or the string if-asked. A true + value causes all pushes to be GPG signed, as if --signed is + passed to . The string if-asked causes + pushes to be signed if the server supports it, as if + --signed=if-asked is passed to git push. A false value may + override a value from a lower-priority config file. An explicit + command-line flag always overrides this config option. + + + + + +push.recurseSubmodules + + + + Make sure all submodule commits used by the revisions to be pushed + are available on a remote-tracking branch. If the value is check + then Git will verify that all submodule commits that changed in the + revisions to be pushed are available on at least one remote of the + submodule. If any commits are missing, the push will be aborted and + exit with non-zero status. If the value is on-demand then all + submodules that changed in the revisions to be pushed will be + pushed. If on-demand was not able to push all necessary revisions + it will also be aborted and exit with non-zero status. If the value + is no then default behavior of ignoring submodules when pushing + is retained. You may override this configuration at time of push by + specifying --recurse-submodules=check|on-demand|no. + @@ -4456,7 +5887,7 @@ rebase.stat -rebase.autosquash +rebase.autoSquash @@ -4466,6 +5897,57 @@ rebase.autosquash +rebase.autoStash + + + + When set to true, automatically create a temporary stash + before the operation begins, and apply it after the operation + ends. This means that you can run rebase on a dirty worktree. + However, use with care: the final stash application after a + successful rebase might result in non-trivial conflicts. + Defaults to false. + + + + + +rebase.missingCommitsCheck + + + + If set to "warn", git rebase -i will print a warning if some + commits are removed (e.g. a line was deleted), however the + rebase will still proceed. If set to "error", it will print + the previous warning and stop the rebase, git rebase + --edit-todo can then be used to correct the error. If set to + "ignore", no checking is done. + To drop a commit without warning or error, use the drop + command in the todo-list. + Defaults to "ignore". + + + + +rebase.instructionFormat + A format string, as specified in , to be used for + the instruction list during an interactive rebase. The format will automatically + have the long commit hash prepended to the format. + + + +receive.advertiseAtomic + + + + By default, git-receive-pack will advertise the atomic push + capability to its clients. If you don't want to this capability + to be advertised, set this variable to false. + + + + + receive.autogc @@ -4478,6 +5960,39 @@ receive.autogc +receive.certNonceSeed + + + + By setting this variable to a string, git receive-pack + will accept a git push --signed and verifies it by using + a "nonce" protected by HMAC using this string as a secret + key. + + + + + +receive.certNonceSlop + + + + When a git push --signed sent a push certificate with a + "nonce" that was issued by a receive-pack serving the same + repository within this many seconds, export the "nonce" + found in the certificate to GIT_PUSH_CERT_NONCE to the + hooks (instead of what the receive-pack asked the sending + side to include). This may allow writing checks in + pre-receive and post-receive a bit easier. Instead of + checking GIT_PUSH_CERT_NONCE_SLOP environment variable + that records by how many seconds the nonce is stale to + decide if they want to accept the certificate, they only + can check GIT_PUSH_CERT_NONCE_STATUS is OK. + + + + + receive.fsckObjects @@ -4492,6 +6007,41 @@ receive.fsckObjects +receive.fsck.<msg-id> + + + + When receive.fsckObjects is set to true, errors can be switched + to warnings and vice versa by configuring the receive.fsck.<msg-id> + setting where the <msg-id> is the fsck message ID and the value + is one of error, warn or ignore. For convenience, fsck prefixes + the error/warning with the message ID, e.g. "missingEmail: invalid + author/committer line - missing email" means that setting + receive.fsck.missingEmail = ignore will hide that issue. + +This feature is intended to support working with legacy repositories +which would not pass pushing when receive.fsckObjects = true, allowing +the host to accept repositories with certain known issues but still catch +other issues. + + + + +receive.fsck.skipList + + + + The path to a sorted list of object names (i.e. one SHA-1 per + line) that are known to be broken in a non-fatal way and should + be ignored. This feature is useful when an established project + should be accepted despite early commits containing errors that + can be safely ignored such as invalid committer email addresses. + Note: corrupt objects cannot be skipped with this setting. + + + + + receive.unpackLimit @@ -4543,6 +6093,15 @@ receive.denyCurrentBranch proceed. If set to false or "ignore", allow such pushes with no message. Defaults to "refuse". +Another option is "updateInstead" which will update the working +tree if pushing into the current branch. This option is +intended for synchronizing working directories when one side is not easily +accessible via interactive ssh (e.g. a live web site, hence the requirement +that the working directory be clean). This mode also comes in handy when +developing inside a VM to test and fix code on different Operating Systems. +By default, "updateInstead" will refuse the push if the working tree or +the index have any difference from the HEAD, but the push-to-checkout +hook can be used to customize this. See . @@ -4560,7 +6119,20 @@ receive.denyNonFastForwards -receive.updateserverinfo +receive.hideRefs + + + + This variable is the same as transfer.hideRefs, but applies + only to receive-pack (and so affects pushes, but not fetches). + An attempt to update or delete a hidden ref by git push is + rejected. + + + + + +receive.updateServerInfo @@ -4571,6 +6143,29 @@ receive.updateserverinfo +receive.shallowUpdate + + + + If set to true, .git/shallow can be updated when new refs + require new shallow roots. Otherwise those refs are rejected. + + + + + +remote.pushDefault + + + + The remote to push to by default. Overrides + branch.<name>.remote for all branches, and is overridden by + branch.<name>.pushRemote for specific branches. + + + + + remote.<name>.url @@ -4604,6 +6199,18 @@ remote.<name>.proxy +remote.<name>.proxyAuthMethod + + + + For remotes that require curl (http, https and ftp), the method to use for + authenticating against the proxy in use (probably set in + remote.<name>.proxy). See http.proxyAuthMethod. + + + + + remote.<name>.fetch @@ -4683,7 +6290,7 @@ remote.<name>.uploadpack -remote.<name>.tagopt +remote.<name>.tagOpt @@ -4702,13 +6309,26 @@ remote.<name>.vcs - Setting this to a value <vcs> will cause git to interact with + Setting this to a value <vcs> will cause Git to interact with the remote with the git-remote-<vcs> helper. +remote.<name>.prune + + + + When set to true, fetching from this remote by default will also + remove any remote-tracking references that no longer exist on the + remote (as if the --prune option was given on the command line). + Overrides fetch.prune settings, if any. + + + + + remotes.<group> @@ -4720,22 +6340,51 @@ remotes.<group> -repack.usedeltabaseoffset +repack.useDeltaBaseOffset By default, creates packs that use delta-base offset. If you need to share your repository with - git older than version 1.4.4, either directly or via a dumb + Git older than version 1.4.4, either directly or via a dumb protocol such as http, then you need to set this option to - "false" and repack. Access from old git versions over the + "false" and repack. Access from old Git versions over the native protocol are unaffected by this option. -rerere.autoupdate +repack.packKeptObjects + + + + If set to true, makes git repack act as if + --pack-kept-objects was passed. See for + details. Defaults to false normally, but true if a bitmap + index is being written (either via --write-bitmap-index or + repack.writeBitmaps). + + + + + +repack.writeBitmaps + + + + When true, git will write a bitmap index when packing all + objects to disk (e.g., when git repack -a is run). This + index can speed up the "counting objects" phase of subsequent + packs created for clones and fetches, at the cost of some disk + space and extra time spent on the initial repack. Defaults to + false. + + + + + +rerere.autoUpdate @@ -4775,7 +6424,7 @@ sendemail.identity -sendemail.smtpencryption +sendemail.smtpEncryption @@ -4786,11 +6435,22 @@ sendemail.smtpencryption -sendemail.smtpssl +sendemail.smtpssl (deprecated) - Deprecated alias for sendemail.smtpencryption = ssl. + Deprecated alias for sendemail.smtpEncryption = ssl. + + + + + +sendemail.smtpsslcertpath + + + + Path to ca-certificates (either a directory or a single file). + Set it to an empty string to disable certificate verification. @@ -4809,10 +6469,13 @@ sendemail.<identity>.* -sendemail.aliasesfile +sendemail.aliasesFile + + +sendemail.aliasFileType -sendemail.aliasfiletype +sendemail.annotate sendemail.bcc @@ -4821,59 +6484,65 @@ sendemail.bcc sendemail.cc -sendemail.cccmd +sendemail.ccCmd -sendemail.chainreplyto +sendemail.chainReplyTo sendemail.confirm -sendemail.envelopesender +sendemail.envelopeSender sendemail.from -sendemail.multiedit +sendemail.multiEdit sendemail.signedoffbycc -sendemail.smtppass +sendemail.smtpPass sendemail.suppresscc -sendemail.suppressfrom +sendemail.suppressFrom sendemail.to -sendemail.smtpdomain +sendemail.smtpDomain -sendemail.smtpserver +sendemail.smtpServer -sendemail.smtpserverport +sendemail.smtpServerPort -sendemail.smtpserveroption +sendemail.smtpServerOption -sendemail.smtpuser +sendemail.smtpUser sendemail.thread +sendemail.transferEncoding + + sendemail.validate + +sendemail.xmailer + See for description. @@ -4882,7 +6551,7 @@ sendemail.validate -sendemail.signedoffcc +sendemail.signedoffcc (deprecated) @@ -4909,13 +6578,49 @@ status.relativePaths By default, shows paths relative to the current directory. Setting this variable to false shows paths - relative to the repository root (this was the default for git + relative to the repository root (this was the default for Git prior to v1.5.4). +status.short + + + + Set to true to enable --short by default in . + The option --no-short takes precedence over this variable. + + + + + +status.branch + + + + Set to true to enable --branch by default in . + The option --no-branch takes precedence over this variable. + + + + + +status.displayCommentPrefix + + + + If set to true, will insert a comment + prefix before each output line (starting with + core.commentChar, i.e. # by default). This was the + behavior of in Git 1.8.4 and previous. + Defaults to false. + + + + + status.showUntrackedFiles @@ -4924,7 +6629,7 @@ status.showUntrackedFiles files which are not currently tracked by Git. Directories which contain only untracked files, are shown with the directory name only. Showing untracked files means that Git needs to lstat() all - all the files in the whole repository, which might be slow on some + the files in the whole repository, which might be slow on some systems. So, this variable controls how the commands displays the untracked files. Possible values are: @@ -4952,7 +6657,7 @@ of and . -status.submodulesummary +status.submoduleSummary @@ -4960,7 +6665,40 @@ status.submodulesummary If this is set to a non zero number or true (identical to -1 or an unlimited number), the submodule summary will be enabled and a summary of commits for modified submodules will be shown (see - --summary-limit option of ). + --summary-limit option of ). Please note + that the summary output command will be suppressed for all + submodules when diff.ignoreSubmodules is set to all or only + for those submodules where submodule.<name>.ignore=all. The only + exception to that rule is that status and commit will show staged + submodule changes. To + also view the summary for ignored submodules you can either use + the --ignore-submodules=dirty command-line option or the git + submodule summary command, which shows a similar output but does + not honor these settings. + + + + + +stash.showPatch + + + + If this is set to true, the git stash show command without an + option will show the stash in patch form. Defaults to false. + See description of show command in . + + + + + +stash.showStat + + + + If this is set to true, the git stash show command without an + option will show diffstat of the stash. Defaults to true. + See description of show command in . @@ -4971,16 +6709,38 @@ submodule.<name>.path submodule.<name>.url + + + The path within this project and URL for a submodule. These + variables are initially populated by git submodule init. See + and for + details. + + + + submodule.<name>.update - The path within this project, URL, and the updating strategy - for a submodule. These variables are initially populated - by git submodule init; edit them to override the - URL and other values found in the .gitmodules file. See - and for details. + The default update procedure for a submodule. This variable + is populated by git submodule init from the + file. See description of update + command in . + + + + + +submodule.<name>.branch + + + + The remote branch name for a submodule, used by git submodule + update --remote. Set this option to override the value found in + the .gitmodules file. See and + for details. @@ -4992,7 +6752,7 @@ submodule.<name>.fetchRecurseSubmodules This option can be used to control recursive fetching of this submodule. It can be overridden by using the --[no-]recurse-submodules - command line option to "git fetch" and "git pull". + command-line option to "git fetch" and "git pull". This setting will override that from in the file. @@ -5006,7 +6766,9 @@ submodule.<name>.ignore Defines under what circumstances "git status" and the diff family show a submodule as modified. When set to "all", it will never be considered - modified, "dirty" will ignore all changes to the submodules work tree and + modified (but it will nonetheless show up in the output of status and + commit when it has been staged), "dirty" will ignore all changes + to the submodules work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account. "untracked" will additionally let submodules with modified tracked files in their work tree show up. @@ -5014,7 +6776,45 @@ submodule.<name>.ignore submodules that have untracked files in their work tree as changed. This setting overrides any setting made in .gitmodules for this submodule, both settings can be overridden on the command line by using the - "--ignore-submodules" option. + "--ignore-submodules" option. The git submodule commands are not + affected by this setting. + + + + + +submodule.fetchJobs + + + + Specifies how many submodules are fetched/cloned at the same time. + A positive integer allows up to that number of submodules fetched + in parallel. A value of 0 will give some reasonable default. + If unset, it defaults to 1. + + + + + +tag.forceSignAnnotated + + + + A boolean to specify whether annotated tags created should be GPG signed. + If --annotate is specified on the command line, it takes + precedence over this option. + + + + + +tag.sort + + + + This variable controls the sort ordering of tags when displayed by + . Without the "--sort=<value>" option provided, the + value of this variable will be used as the default. @@ -5046,6 +6846,34 @@ transfer.fsckObjects +transfer.hideRefs + + + + String(s) receive-pack and upload-pack use to decide which + refs to omit from their initial advertisements. Use more than + one definition to specify multiple prefix strings. A ref that is + under the hierarchies listed in the value of this variable is + excluded, and is hidden when responding to git push or git + fetch. See receive.hideRefs and uploadpack.hideRefs for + program-specific versions of this config. + +You may also include a ! in front of the ref name to negate the entry, +explicitly exposing it, even if an earlier entry marked it as hidden. +If you have multiple hideRefs values, later entries override earlier ones +(and entries in more-specific config files override less-specific ones). +If a namespace is in use, the namespace prefix is stripped from each +reference before it is matched against transfer.hiderefs patterns. +For example, if refs/heads/master is specified in transfer.hideRefs and +the current namespace is foo, then refs/namespaces/foo/refs/heads/master +is omitted from the advertisements but refs/heads/master and +refs/namespaces/bar/refs/heads/master are still advertised as so-called +"have" lines. In order to match refs before stripping, add a ^ in front of +the ref name. If you combine ! and ^, ! must be specified first. + + + + transfer.unpackLimit @@ -5058,6 +6886,77 @@ transfer.unpackLimit +uploadarchive.allowUnreachable + + + + If true, allow clients to use git archive --remote to request + any tree, whether reachable from the ref tips or not. See the + discussion in the SECURITY section of + for more details. Defaults to + false. + + + + + +uploadpack.hideRefs + + + + This variable is the same as transfer.hideRefs, but applies + only to upload-pack (and so affects only fetches, not pushes). + An attempt to fetch a hidden ref by git fetch will fail. See + also uploadpack.allowTipSHA1InWant. + + + + + +uploadpack.allowTipSHA1InWant + + + + When uploadpack.hideRefs is in effect, allow upload-pack + to accept a fetch request that asks for an object at the tip + of a hidden ref (by default, such a request is rejected). + see also uploadpack.hideRefs. + + + + + +uploadpack.allowReachableSHA1InWant + + + + Allow upload-pack to accept a fetch request that asks for an + object that is reachable from any ref tip. However, note that + calculating object reachability is computationally expensive. + Defaults to false. + + + + + +uploadpack.keepAlive + + + + When upload-pack has started pack-objects, there may be a + quiet period while pack-objects prepares the pack. Normally + it would output progress information, but if --quiet was used + for the fetch, pack-objects will output nothing at all until + the pack data begins. Some clients and networks may consider + the server to be hung and give up. Setting this option instructs + upload-pack to send an empty keepalive packet every + uploadpack.keepAlive seconds. Setting this option to 0 + disables keepalive packets entirely. The default is 5 seconds. + + + + + url.<base>.insteadOf @@ -5067,7 +6966,7 @@ url.<base>.insteadOf large number of repositories, and serves them with multiple access methods, and some users need to use different access methods, this feature allows people to specify any of the - equivalent URLs and have git automatically rewrite the URL to + equivalent URLs and have Git automatically rewrite the URL to the best alternative for the particular user, even for a never-before-seen repository on the site. When more than one insteadOf strings match a given URL, the longest match is used. @@ -5085,11 +6984,11 @@ url.<base>.pushInsteadOf resulting URL will be pushed to. In cases where some site serves a large number of repositories, and serves them with multiple access methods, some of which do not allow push, this feature - allows people to specify a pull-only URL and have git + allows people to specify a pull-only URL and have Git automatically use an appropriate URL to push, even for a never-before-seen repository on the site. When more than one pushInsteadOf strings match a given URL, the longest match is - used. If a remote has an explicit pushurl, git will ignore this + used. If a remote has an explicit pushurl, Git will ignore this setting for that remote. @@ -5120,16 +7019,51 @@ user.name -user.signingkey +user.useConfigOnly + + + + Instruct Git to avoid trying to guess defaults for user.email + and user.name, and instead retrieve the values only from the + configuration. For example, if you have multiple email addresses + and would like to use a different one for each repository, then + with this configuration option set to true in the global config + along with a name, Git will prompt you to set up an email before + making new commits in a newly cloned repository. + Defaults to false. + + + + + +user.signingKey + + + + If or is not selecting the + key you want it to automatically when creating a signed tag or + commit, you can override the default selection with this variable. + This option is passed unchanged to gpg's --local-user parameter, + so you may specify a key using any method that gpg supports. + + + + + +versionsort.prereleaseSuffix - If is not selecting the key you want it to - automatically when creating a signed tag, you can override the - default selection with this variable. This option is passed - unchanged to gpg's --local-user parameter, so you may specify a key - using any method that gpg supports. + When version sort is used in , prerelease + tags (e.g. "1.0-rc1") may appear after the main release + "1.0". By specifying the suffix "-rc" in this variable, + "1.0-rc1" will appear before "1.0". +This variable can be specified multiple times, once per suffix. The +order of suffixes in the config file determines the sorting order +(e.g. if "-pre" appears before "-rc" in the config file then 1.0-preXX +is sorted before 1.0-rcXX). The sorting order between different +suffixes is undefined if they are in multiple config files. diff --git a/doc/source/en/TortoiseGit/git_doc/git-count-objects.xml b/doc/source/en/TortoiseGit/git_doc/git-count-objects.xml index 04f2c3fbe..22c613f6b 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-count-objects.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-count-objects.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git count-objects [-v] +git count-objects [-v] [-H | --human-readable]
@@ -33,11 +33,30 @@ them, to help you decide when it is a good time to repack. - In addition to the number of loose objects and disk - space consumed, it reports the number of in-pack - objects, number of packs, disk space consumed by those packs, - and number of objects that can be removed by running - git prune-packed. + Report in more detail: + +count: the number of loose objects +size: disk space consumed by loose objects, in KiB (unless -H is specified) +in-pack: the number of in-pack objects +size-pack: disk space consumed by the packs, in KiB (unless -H is specified) +prune-packable: the number of loose objects that are also present in +the packs. These objects could be pruned using git prune-packed. +garbage: the number of files in object database that are neither valid loose +objects nor valid packs +size-garbage: disk space consumed by garbage files, in KiB (unless -H is +specified) + + + + +-H + + +--human-readable + + + +Print sizes in human readable format diff --git a/doc/source/en/TortoiseGit/git_doc/git-credential-cache--daemon.xml b/doc/source/en/TortoiseGit/git_doc/git-credential-cache--daemon.xml index 1c93fd31a..e4b4b80be 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-credential-cache--daemon.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-credential-cache--daemon.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git credential-cache--daemon <socket> +git credential-cache--daemon [--debug] <socket>
@@ -24,6 +24,9 @@ started automatically when you use .git-credential-cache clients. Clients may store and retrieve credentials. Each credential is held for a timeout specified by the client; once no credentials are held, the daemon exits. +If the --debug option is specified, the daemon does not close its +stderr stream, and may output extra diagnostics to it even after it has +begun listening for clients. GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-credential-cache.xml b/doc/source/en/TortoiseGit/git_doc/git-credential-cache.xml index 08f15300d..b84e6620e 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-credential-cache.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-credential-cache.xml @@ -16,12 +16,12 @@ DESCRIPTION -This command caches credentials in memory for use by future git +This command caches credentials in memory for use by future Git programs. The stored credentials never touch the disk, and are forgotten after a configurable timeout. The cache is accessible over a Unix domain socket, restricted to the current user by filesystem permissions. You probably don't want to invoke this command directly; it is meant to -be used as a credential helper by other parts of git. See +be used as a credential helper by other parts of Git. See or EXAMPLES below. @@ -47,7 +47,7 @@ be used as a credential helper by other parts of git. See cache daemon if one is not started). Defaults to ~/.git-credential-cache/socket. If your home directory is on a network-mounted filesystem, you may need to change this to a - local filesystem. + local filesystem. You must specify an absolute path. diff --git a/doc/source/en/TortoiseGit/git_doc/git-credential-store.xml b/doc/source/en/TortoiseGit/git_doc/git-credential-store.xml index cff85d897..c986434d8 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-credential-store.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-credential-store.xml @@ -21,7 +21,7 @@ protected only by filesystem permissions. If this is not an acceptable security tradeoff, try , or find a helper that integrates with secure storage provided by your operating system. This command stores credentials indefinitely on disk for use by future -git programs. +Git programs. You probably don't want to invoke this command directly; it is meant to be used as a credential helper by other parts of git. See or EXAMPLES below. @@ -31,19 +31,61 @@ be used as a credential helper by other parts of git. See ---store=<path> +--file=<path> - Use <path> to store credentials. The file will have its + Use <path> to lookup and store credentials. The file will have its filesystem permissions set to prevent other users on the system from reading it, but will not be encrypted or otherwise - protected. Defaults to ~/.git-credentials. + protected. If not specified, credentials will be searched for from + ~/.git-credentials and $XDG_CONFIG_HOME/git/credentials, and + credentials will be written to ~/.git-credentials if it exists, or + $XDG_CONFIG_HOME/git/credentials if it exists and the former does + not. See also . + +FILES +If not set explicitly with --file, there are two files where +git-credential-store will search for credentials in order of precedence: + + + +~/.git-credentials + + + + User-specific credentials file. + + + + + +$XDG_CONFIG_HOME/git/credentials + + + + Second user-specific credentials file. If $XDG_CONFIG_HOME is not set + or empty, $HOME/.config/git/credentials will be used. Any credentials + stored in this file will not be used if ~/.git-credentials has a + matching credential as well. It is a good idea not to create this file + if you sometimes use older versions of Git that do not support it. + + + + +For credential lookups, the files are read in the order given above, with the +first matching credential found taking precedence over credentials found in +files further down the list. +Credential storage will by default write to the first existing file in the +list. If none of these files exist, ~/.git-credentials will be created and +written to. +When erasing credentials, matching credentials will be erased from all files. + EXAMPLES The point of this helper is to reduce the number of times you must type @@ -62,11 +104,11 @@ $ git push http://example.com/repo.git The .git-credentials file is stored in plaintext. Each credential is stored on its own line as a URL like: https://user:pass@example.com -When git needs authentication for a particular URL context, +When Git needs authentication for a particular URL context, credential-store will consider that context a pattern to match against each entry in the credentials file. If the protocol, hostname, and username (if we already have one) match, then the password is returned -to git. See the discussion of configuration in +to Git. See the discussion of configuration in for more information. diff --git a/doc/source/en/TortoiseGit/git_doc/git-credential.xml b/doc/source/en/TortoiseGit/git_doc/git-credential.xml index e7688835b..b143484a5 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-credential.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-credential.xml @@ -20,9 +20,9 @@ from system-specific helpers, as well as prompting the user for usernames and passwords. The git-credential command exposes this interface to scripts which may want to retrieve, store, or prompt for -credentials in the same manner as git. The design of this scriptable +credentials in the same manner as Git. The design of this scriptable interface models the internal C API; see -link:technical/api-credentials.txt[the git credential API] for more +link:technical/api-credentials.html[the Git credential API] for more background on the concepts. git-credential takes an "action" option on the command-line (one of fill, approve, or reject) and reads a credential description @@ -54,7 +54,7 @@ Generate a credential description based on the context. https://example.com/foo.git, we might generate the following credential description (don't forget the blank line at the end; it tells git credential that the application finished feeding all the -infomation it has): +information it has): protocol=https host=example.com path=foo.git @@ -72,7 +72,7 @@ host=example.com username=bob password=secr3t In most cases, this means the attributes given in the input will be -repeated in the output, but git may also modify the credential +repeated in the output, but Git may also modify the credential description, for example by removing the path attribute when the protocol is HTTP(s) and credential.useHttpPath is false. If the git credential knew about the password, this step may diff --git a/doc/source/en/TortoiseGit/git_doc/git-cvsexportcommit.xml b/doc/source/en/TortoiseGit/git_doc/git-cvsexportcommit.xml index 06e21919a..0e6af05b5 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-cvsexportcommit.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-cvsexportcommit.xml @@ -19,8 +19,8 @@ DESCRIPTION -Exports a commit from GIT to a CVS checkout, making it easier -to merge patches from a git repository into a CVS repository. +Exports a commit from Git to a CVS checkout, making it easier +to merge patches from a Git repository into a CVS repository. Specify the name of a CVS checkout using the -w switch or execute it from the root of the CVS working copy. In the latter case GIT_DIR must be defined. See examples below. @@ -139,7 +139,7 @@ parent the changeset should be done against. Specify the location of the CVS checkout to use for the export. This option does not require GIT_DIR to be set before execution if the - current directory is within a git repository. The default is the + current directory is within a Git repository. The default is the value of cvsexportcommit.cvsdir. diff --git a/doc/source/en/TortoiseGit/git_doc/git-cvsimport.xml b/doc/source/en/TortoiseGit/git_doc/git-cvsimport.xml index 3efa5c3e8..2bbda84e7 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-cvsimport.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-cvsimport.xml @@ -22,7 +22,12 @@ DESCRIPTION -Imports a CVS repository into git. It will either create a new +WARNING: git cvsimport uses cvsps version 2, which is considered +deprecated; it does not work with cvsps version 3 and later. If you are +performing a one-shot import of a CVS repository consider using +http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or +https://github.com/BartMassey/parsecvs[parsecvs]. +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. @@ -85,7 +90,7 @@ See . - The git repository to import to. If the directory doesn't + The Git repository to import to. If the directory doesn't exist, it will be created. Default is the current directory. @@ -96,7 +101,7 @@ See . - The git remote to import this CVS repository into. + The Git remote to import this CVS repository into. Moves all CVS branches into remotes/<remote>/<branch> akin to the way git clone uses origin by default. @@ -109,8 +114,8 @@ See . When no remote is specified (via -r) the HEAD branch - from CVS is imported to the origin branch within the git - repository, as HEAD already has a special meaning for git. + from CVS is imported to the origin branch within the Git + repository, as HEAD already has a special meaning for Git. When a remote is specified the HEAD branch is named remotes/<remote>/master mirroring git clone behaviour. Use this option if you want to import into a different @@ -265,13 +270,13 @@ the old cvs2git tool. CVS by default uses the Unix username when writing its commit logs. Using this option and an author-conv-file maps the name recorded in CVS to author name, e-mail and - optional timezone: + optional time zone: exon=Andreas Ericsson <ae@op5.se> spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago git cvsimport will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly -all along. If a timezone is specified, GIT_AUTHOR_DATE will +all along. If a time zone is specified, GIT_AUTHOR_DATE will have the corresponding offset applied. For convenience, this data is saved to $GIT_DIR/cvs-authors each time the -A option is provided and read from that same @@ -372,17 +377,11 @@ Multiple tags on the same revision are not imported. If you suspect that any of these issues may apply to the repository you -want to import consider using these alternative tools which proved to be -more stable in practice: +want to import, consider using cvs2git: -cvs2git (part of cvs2svn), http://cvs2svn.tigris.org - - - - -parsecvs, http://cgit.freedesktop.org/~keithp/parsecvs +cvs2git (part of cvs2svn), http://subversion.apache.org/ diff --git a/doc/source/en/TortoiseGit/git_doc/git-cvsserver.xml b/doc/source/en/TortoiseGit/git_doc/git-cvsserver.xml index 35f8adc4e..a2d9c9ddc 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-cvsserver.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-cvsserver.xml @@ -8,7 +8,7 @@ NAME -git-cvsserver - A CVS server emulator for git +git-cvsserver - A CVS server emulator for Git SYNOPSIS @@ -109,7 +109,7 @@ unless --export-all was given, too. DESCRIPTION -This application is a CVS emulation layer for git. +This application is a CVS emulation layer for Git. It is highly functional. However, not all methods are implemented, and for those methods that are implemented, not all switches are implemented. @@ -118,8 +118,8 @@ plugin. Most functionality works fine with both of these clients. LIMITATIONS -CVS clients cannot tag, branch or perform GIT merges. -git-cvsserver maps GIT branches to CVS modules. This is very different +CVS clients cannot tag, branch or perform Git merges. +git-cvsserver maps Git branches to CVS modules. This is very different from what most CVS users would expect since in CVS modules usually represent one or more directories. @@ -143,7 +143,7 @@ setting in the config file of the repositories you want the cvsserver to allow writes to, for example: [gitcvs] authdb = /etc/cvsserver/passwd -The format of these files is username followed by the crypted password, +The format of these files is username followed by the encrypted password, for example: myuser:$1Oyx5r9mdGZ2 myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./ @@ -154,7 +154,7 @@ library's crypt() function, so don't use the -m option. perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password Then provide your password via the pserver method, for example: cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name> -No special setup is needed for SSH access, other than having GIT tools +No special setup is needed for SSH access, other than having Git tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename git-cvsserver to cvs. Note: Newer CVS versions (>= 1.12.11) also support specifying @@ -174,12 +174,12 @@ For each repo that you want accessible from CVS you need to edit config in [gitcvs] enabled=1 # optional for debugging - logfile=/path/to/logfile + logFile=/path/to/logfile Note: you need to ensure each user that is going to invoke git-cvsserver has write access to the log file and to the database (see Database Backend. If you want to offer write access over -SSH, the users of course also need write access to the git repository itself. -You also need to ensure that each repository is "bare" (without a git index +SSH, the users of course also need write access to the Git repository itself. +You also need to ensure that each repository is "bare" (without a Git index file) for cvs commit to work. See . All configuration variables can also be overridden for a specific method of access. Valid method names are "ext" (for SSH access) and "pserver". The @@ -196,7 +196,7 @@ allowing access over SSH. If you didn't specify the CVSROOT/CVS_SERVER directly in the checkout command, automatically saving it in your CVS/Root files, then you need to set them explicitly in your environment. CVSROOT should be set as per normal, but the - directory should point at the appropriate git repo. As above, for SSH clients + directory should point at the appropriate Git repo. As above, for SSH clients not restricted to git-shell, CVS_SERVER should be set to git-cvsserver. export CVSROOT=:ext:user@server:/var/git/project.git @@ -214,7 +214,7 @@ For SSH clients that will make commits, make sure their server-side Clients should now be able to check out the project. Use the CVS module - name to indicate what GIT head you want to check out. This also sets the + name to indicate what Git head you want to check out. This also sets the name of your newly checked-out directory, unless you tell it otherwise with -d <dir_name>. For example, this checks out master branch to the project-master directory: @@ -225,7 +225,7 @@ Clients should now be able to check out the project. Use the CVS modul Database Backend -git-cvsserver uses one database per git head (i.e. CVS module) to +git-cvsserver uses one database per Git head (i.e. CVS module) to store information about the repository to maintain consistent CVS revision numbers. The database needs to be updated (i.e. written to) after every commit. @@ -237,7 +237,7 @@ access method and requested operation. the pserver method), git-cvsserver should have write access to the database to work reliably (otherwise you need to make sure that the database is up-to-date any time git-cvsserver is executed). -By default it uses SQLite databases in the git directory, named +By default it uses SQLite databases in the Git directory, named gitcvs.<module_name>.sqlite. Note that the SQLite backend creates temporary files in the same directory as the database file on write so it might not be enough to grant the users using @@ -264,7 +264,7 @@ about DBI->connect(). -gitcvs.dbname +gitcvs.dbName @@ -278,7 +278,7 @@ gitcvs.dbname -gitcvs.dbdriver +gitcvs.dbDriver @@ -298,7 +298,7 @@ gitcvs.dbuser - Database user. Only useful if setting dbdriver, since + Database user. Only useful if setting dbDriver, since SQLite has no concept of database users. Supports variable substitution (see below). @@ -306,11 +306,11 @@ gitcvs.dbuser -gitcvs.dbpass +gitcvs.dbPass - Database password. Only useful if setting dbdriver, since + Database password. Only useful if setting dbDriver, since SQLite has no concept of database passwords. @@ -331,7 +331,7 @@ gitcvs.dbTableNamePrefix All variables can also be set per access method, see above.
Variable substitution -In dbdriver and dbuser you can use the following variables: +In dbDriver and dbUser you can use the following variables: @@ -339,7 +339,7 @@ gitcvs.dbTableNamePrefix - git directory name + Git directory name @@ -349,7 +349,7 @@ gitcvs.dbTableNamePrefix - git directory name, where all characters except for + Git directory name, where all characters except for alpha-numeric ones, ., and - are replaced with _ (this should make it easier to use the directory name in a filename if wanted) @@ -362,7 +362,7 @@ gitcvs.dbTableNamePrefix - CVS module/git head name + CVS module/Git head name @@ -470,8 +470,41 @@ TortoiseCVS Operations supported All the operations required for normal use are supported, including -checkout, diff, status, update, log, add, remove, commit. -Legacy monitoring operations are not supported (edit, watch and related). +checkout, diff, status, update, log, add, remove, commit. +Most CVS command arguments that read CVS tags or revision numbers +(typically -r) work, and also support any git refspec +(tag, branch, commit ID, etc). +However, CVS revision numbers for non-default branches are not well +emulated, and cvs log does not show tags or branches at +all. (Non-main-branch CVS revision numbers superficially resemble CVS +revision numbers, but they actually encode a git commit ID directly, +rather than represent the number of revisions since the branch point.) +Note that there are two ways to checkout a particular branch. +As described elsewhere on this page, the "module" parameter +of cvs checkout is interpreted as a branch name, and it becomes +the main branch. It remains the main branch for a given sandbox +even if you temporarily make another branch sticky with +cvs update -r. Alternatively, the -r argument can indicate +some other branch to actually checkout, even though the module +is still the "main" branch. Tradeoffs (as currently +implemented): Each new "module" creates a new database on disk with +a history for the given module, and after the database is created, +operations against that main branch are fast. Or alternatively, +-r doesn't take any extra disk space, but may be significantly slower for +many operations, like cvs update. +If you want to refer to a git refspec that has characters that are +not allowed by CVS, you have two options. First, it may just work +to supply the git refspec directly to the appropriate CVS -r argument; +some CVS clients don't seem to do much sanity checking of the argument. +Second, if that fails, you can use a special character escape mechanism +that only uses characters that are valid in CVS tags. A sequence +of 4 or 5 characters of the form (underscore ("_"), dash ("-"), +one or two characters, and dash ("-")) can encode various characters based +on the one or two letters: "s" for slash ("/"), "p" for +period ("."), "u" for underscore ("_"), or two hexadecimal digits +for any byte value at all (typically an ASCII number, or perhaps a part +of a UTF-8 encoded character). +Legacy monitoring operations are not supported (edit, watch and related). Exports and tagging (tags and branches) are not supported at this stage.
CRLF Line Ending Conversions @@ -484,15 +517,15 @@ config variable. See for more information about end-of-line conversion. Alternatively, if gitcvs.usecrlfattr config is not enabled or the attributes do not allow automatic detection for a filename, then -the server uses the gitcvs.allbinary config for the default setting. -If gitcvs.allbinary is set, then file not otherwise +the server uses the gitcvs.allBinary config for the default setting. +If gitcvs.allBinary is set, then file not otherwise specified will default to -kb mode. Otherwise the -k mode -is left blank. But if gitcvs.allbinary is set to "guess", then +is left blank. But if gitcvs.allBinary is set to "guess", then the correct -k mode will be guessed based on the contents of the file. For best consistency with cvs, it is probably best to override the defaults by setting gitcvs.usecrlfattr to true, -and gitcvs.allbinary to "guess". +and gitcvs.allBinary to "guess".
diff --git a/doc/source/en/TortoiseGit/git_doc/git-daemon.xml b/doc/source/en/TortoiseGit/git_doc/git-daemon.xml index 820cdda3b..438cd14d2 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-daemon.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-daemon.xml @@ -8,7 +8,7 @@ NAME -git-daemon - A really simple server for git repositories +git-daemon - A really simple server for Git repositories SYNOPSIS @@ -21,18 +21,20 @@ [--reuseaddr] [--detach] [--pid-file=<file>] [--enable=<service>] [--disable=<service>] [--allow-override=<service>] [--forbid-override=<service>] - [--access-hook=<path>] - [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]] + [--access-hook=<path>] [--[no-]informative-errors] + [--inetd | + [--listen=<host_or_ipaddr>] [--port=<n>] + [--user=<user> [--group=<group>]]] [<directory>…]
DESCRIPTION -A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT" +A really simple TCP Git daemon that normally listens on port "DEFAULT_GIT_PORT" aka 9418. It waits for a connection asking for a service, and will serve that service if it is enabled. 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 +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. @@ -40,7 +42,7 @@ the offers to a whitelist comprising of those. git fetch-pack and git ls-remote clients, which are invoked from git fetch, git pull, and git clone. This is ideally suited for read-only updates, i.e., pulling from -git repositories. +Git repositories. An upload-archive also exists to serve git archive. @@ -66,7 +68,7 @@ git repositories. Remap all the path requests as relative to the given path. - This is sort of "GIT root" - if you run git daemon with + 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. @@ -109,7 +111,7 @@ git repositories. - Allow pulling from all directories that look like GIT repositories + 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. @@ -278,6 +280,12 @@ git repositories. Giving these options is an error when used with --inetd; use the facility of inet daemon to achieve the same before spawning git daemon if needed. +Like many programs that switch user id, the daemon does not reset +environment variables such as $HOME when it runs git programs, +e.g. upload-pack and receive-pack. When using this option, you +may also want to set and export HOME to point at the home +directory of <user> before starting the daemon, and make sure any +Git configuration files in that directory are readable by <user>. @@ -308,16 +316,13 @@ the facility of inet daemon to achieve the same before spawning Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services - are overridable. + may be overridden. ---informative-errors - - ---no-informative-errors +--[no-]informative-errors @@ -340,7 +345,7 @@ the facility of inet daemon to achieve the same before spawning Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), path to the repository, hostname (%H), canonical hostname - (%CH), ip address (%IP), and tcp port (%P) as its command line + (%CH), IP address (%IP), and TCP port (%P) as its command-line arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR @@ -369,7 +374,7 @@ it declines the service. SERVICES These services can be globally enabled/disabled using the -command line options of this command. If a finer-grained +command-line options of this command. If finer-grained control is desired (e.g. to allow git archive to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or diff --git a/doc/source/en/TortoiseGit/git_doc/git-describe.xml b/doc/source/en/TortoiseGit/git_doc/git-describe.xml index d09f9ecf6..c1ecb5498 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-describe.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-describe.xml @@ -8,12 +8,12 @@ NAME -git-describe - Show the most recent tag that is reachable from a commit +git-describe - Describe a commit using the most recent tag reachable from it SYNOPSIS
-git describe [--all] [--tags] [--contains] [--abbrev=<n>] <committish>… +git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…] git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
@@ -33,11 +33,11 @@ see the -a and -s options to . -<committish>… +<commit-ish>… - Committish object names to describe. + Commit-ish object names to describe. Defaults to HEAD if omitted. @@ -109,7 +109,7 @@ see the -a and -s options to . Instead of considering only the 10 most recent tags as - candidates to describe the input committish consider + candidates to describe the input commit-ish consider up to <n> candidates. Increasing <n> above 10 will take slightly longer but may produce a more accurate result. An <n> of 0 will cause only exact matches to be output. @@ -161,8 +161,9 @@ see the -a and -s options to . - Only consider tags matching the given pattern (can be used to avoid - leaking private tags made from the repository). + Only consider tags matching the given glob(7) pattern, + excluding the "refs/tags/" prefix. This can be used to avoid + leaking private tags from the repository. @@ -176,6 +177,18 @@ see the -a and -s options to . + + +--first-parent + + + + Follow only the first parent commit upon seeing a merge commit. + This is useful when you wish to not match tags on branches merged + in the history of the target commit. + + + @@ -210,13 +223,13 @@ closest tagname without any suffix: tags/v1.0.0 Note that the suffix you get if you type these commands today may be longer than what Linus saw above when he ran these commands, as your -git repository may have new commits whose object names begin with +Git repository may have new commits whose object names begin with 975b that did not exist back then, and "-g975b" suffix alone may not be sufficient to disambiguate these commits. SEARCH STRATEGY -For each committish supplied, git describe will first look for +For each commit-ish supplied, git describe will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match @@ -224,9 +237,11 @@ is found, its name will be output and searching will stop. If an exact match was not found, git describe will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an -abbreviation of the input committish's SHA1. +abbreviation of the input commit-ish's SHA-1. If --first-parent was +specified then the walk will only consider the first parent of each +commit. If multiple tags were found during the walk then the tag which -has the fewest commits different from the input committish will be +has the fewest commits different from the input commit-ish will be selected and output. Here fewest commits different is defined as the number of commits which would be shown by git log tag..input will be the smallest number of commits possible. diff --git a/doc/source/en/TortoiseGit/git_doc/git-diff-files.xml b/doc/source/en/TortoiseGit/git_doc/git-diff-files.xml index 2ed00ef1d..a2ef19647 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-diff-files.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-diff-files.xml @@ -39,7 +39,20 @@ same as for git diff-index and git diff-tree Generate patch (see section on generating patches). - + + + + + +-s + + +--no-patch + + + + Suppress diff output. Useful for commands like git show that + show the patch by default, or to cancel the effect of --patch. @@ -64,8 +77,8 @@ same as for git diff-index and git diff-tree - Generate the raw format. - This is the default. + Generate the diff in raw format. + This is the default. @@ -112,6 +125,63 @@ same as for git diff-index and git diff-tree +--diff-algorithm={patience|minimal|histogram|myers} + + + + Choose a diff algorithm. The variants are as follows: + + + + +default, myers + + + + The basic greedy diff algorithm. Currently, this is the default. + + + + + +minimal + + + + Spend extra time to make sure the smallest possible diff is + produced. + + + + + +patience + + + + Use "patience diff" algorithm when generating patches. + + + + + +histogram + + + + This algorithm extends the patience algorithm to "support + low-occurrence common elements". + + + + +For instance, if you configured diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option. + + + + --stat[=<width>[,<name-width>[,<count>]]] @@ -329,8 +399,8 @@ any of those replacements occurred. Show colored diff. - The value must be always (the default for <when>), never, or auto. - The default value is never. + --color (i.e. without =<when>) is the same as --color=always. + <when> can be one of always, never, or auto. @@ -426,6 +496,8 @@ differences. You may want to append |[^[:space:]] to your expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline. +For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character. The regex can also be set via a diff driver or configuration option, see or . Giving it explicitly overrides any diff driver or configuration setting. Diff drivers @@ -460,8 +532,8 @@ override configuration settings. - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by core.whitespace + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the @@ -473,6 +545,22 @@ override configuration settings. +--ws-error-highlight=<kind> + + + + Highlight whitespace errors on lines specified by <kind> + in the color specified by color.diff.whitespace. <kind> + is a comma separated list of old, new, context. When + this option is not given, only whitespace errors in new + lines are highlighted. E.g. --ws-error-highlight=new,old + highlights whitespace errors on both deleted and added lines. + all can be used as a short-hand for old,new,context. + + + + + --full-index @@ -527,7 +615,7 @@ few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for git to consider it a total +original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines). When used with -M, a totally-rewritten file is also considered as the @@ -551,13 +639,13 @@ another file. Detect renames. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the - file's size). For example, -M90% means git should consider a + file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use - -M100%. + -M100%. The default similarity index is 50%. @@ -602,7 +690,7 @@ another file. Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch - is not meant to be applied with patch nor git apply; this is + is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, @@ -651,11 +739,15 @@ of a delete/create pair. - Look for differences that introduce or remove an instance of - <string>. Note that this is different than the string simply - appearing in diff output; see the pickaxe entry in - for more details. + Look for differences that change the number of occurrences of + the specified string (i.e. addition/deletion) in a file. + Intended for the scripter's use. +It is useful when you're looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block. @@ -664,9 +756,20 @@ of a delete/create pair. - Look for differences whose added or removed line matches - the given <regex>. + Look for differences whose patch text contains added/removed + lines that match <regex>. +To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file: ++ return !regexec(regexp, two->ptr, 1, &regmatch, 0); +... +- hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0); +While git log -G"regexec\(regexp" will show this commit, git log +-S"regexec\(regexp" --pickaxe-regex will not (because the number of +occurrences of that string did not change). +See the pickaxe entry in for more +information. @@ -687,8 +790,8 @@ of a delete/create pair. - Make the <string> not a plain string but an extended POSIX - regex to match. + Treat the <string> given to -S as an extended POSIX regular + expression to match. @@ -700,6 +803,9 @@ of a delete/create pair. Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. + This overrides the diff.orderFile configuration variable + (see ). To cancel diff.orderFile, + use -O/dev/null. @@ -784,6 +890,16 @@ of a delete/create pair. +--ignore-blank-lines + + + + Ignore changes whose lines are all blank. + + + + + --inter-hunk-context=<lines> @@ -877,7 +993,7 @@ of a delete/create pair. Ignore changes to submodules in the diff generation. <when> can be - either "none", "untracked", "dirty" or "all", which is the default + either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the @@ -1158,7 +1274,8 @@ X: "unknown" change type (most probably a bug, please report it) Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or -copy), and are the only ones to be so. +copy). Status letter M may be followed by a score (denoting the +percentage of dissimilarity) for file rewrites. <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: @@ -1282,10 +1399,10 @@ rename to a combined diff format -Any diff-generating command can take the -c` or --cc option to +Any diff-generating command can take the -c or --cc option to produce a combined diff when showing a merge. This is the default format when showing merges with or -. Note also that you can give the `-m option to any +. Note also that you can give the -m option to any of these commands to force generation of diffs with individual parents of a merge. A combined diff format looks like this: @@ -1380,7 +1497,7 @@ added, from the point of view of that parent). 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 eight other lines are the same +in either file1 or file2). Also eight 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 diff --git a/doc/source/en/TortoiseGit/git_doc/git-diff-index.xml b/doc/source/en/TortoiseGit/git_doc/git-diff-index.xml index 6446f992a..dd2bb8aaa 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-diff-index.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-diff-index.xml @@ -8,7 +8,7 @@ NAME -git-diff-index - Compares content and mode of blobs between the index and repository +git-diff-index - Compare a tree to the working tree or index SYNOPSIS @@ -18,11 +18,11 @@ 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. +Compares the content and mode of the blobs found in a tree object +with the corresponding tracked files in the working tree, or with the +corresponding paths in the index. When <path> arguments are present, +compares only paths matching those patterns. Otherwise all tracked +files are compared. OPTIONS @@ -40,7 +40,20 @@ entries in the index are compared. Generate patch (see section on generating patches). - + + + + + +-s + + +--no-patch + + + + Suppress diff output. Useful for commands like git show that + show the patch by default, or to cancel the effect of --patch. @@ -65,8 +78,8 @@ entries in the index are compared. - Generate the raw format. - This is the default. + Generate the diff in raw format. + This is the default. @@ -113,6 +126,63 @@ entries in the index are compared. +--diff-algorithm={patience|minimal|histogram|myers} + + + + Choose a diff algorithm. The variants are as follows: + + + + +default, myers + + + + The basic greedy diff algorithm. Currently, this is the default. + + + + + +minimal + + + + Spend extra time to make sure the smallest possible diff is + produced. + + + + + +patience + + + + Use "patience diff" algorithm when generating patches. + + + + + +histogram + + + + This algorithm extends the patience algorithm to "support + low-occurrence common elements". + + + + +For instance, if you configured diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option. + + + + --stat[=<width>[,<name-width>[,<count>]]] @@ -330,8 +400,8 @@ any of those replacements occurred. Show colored diff. - The value must be always (the default for <when>), never, or auto. - The default value is never. + --color (i.e. without =<when>) is the same as --color=always. + <when> can be one of always, never, or auto. @@ -427,6 +497,8 @@ differences. You may want to append |[^[:space:]] to your expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline. +For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character. The regex can also be set via a diff driver or configuration option, see or . Giving it explicitly overrides any diff driver or configuration setting. Diff drivers @@ -461,8 +533,8 @@ override configuration settings. - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by core.whitespace + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the @@ -474,6 +546,22 @@ override configuration settings. +--ws-error-highlight=<kind> + + + + Highlight whitespace errors on lines specified by <kind> + in the color specified by color.diff.whitespace. <kind> + is a comma separated list of old, new, context. When + this option is not given, only whitespace errors in new + lines are highlighted. E.g. --ws-error-highlight=new,old + highlights whitespace errors on both deleted and added lines. + all can be used as a short-hand for old,new,context. + + + + + --full-index @@ -528,7 +616,7 @@ few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for git to consider it a total +original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines). When used with -M, a totally-rewritten file is also considered as the @@ -552,13 +640,13 @@ another file. Detect renames. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the - file's size). For example, -M90% means git should consider a + file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use - -M100%. + -M100%. The default similarity index is 50%. @@ -603,7 +691,7 @@ another file. Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch - is not meant to be applied with patch nor git apply; this is + is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, @@ -652,11 +740,15 @@ of a delete/create pair. - Look for differences that introduce or remove an instance of - <string>. Note that this is different than the string simply - appearing in diff output; see the pickaxe entry in - for more details. + Look for differences that change the number of occurrences of + the specified string (i.e. addition/deletion) in a file. + Intended for the scripter's use. +It is useful when you're looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block. @@ -665,9 +757,20 @@ of a delete/create pair. - Look for differences whose added or removed line matches - the given <regex>. + Look for differences whose patch text contains added/removed + lines that match <regex>. +To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file: ++ return !regexec(regexp, two->ptr, 1, &regmatch, 0); +... +- hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0); +While git log -G"regexec\(regexp" will show this commit, git log +-S"regexec\(regexp" --pickaxe-regex will not (because the number of +occurrences of that string did not change). +See the pickaxe entry in for more +information. @@ -688,8 +791,8 @@ of a delete/create pair. - Make the <string> not a plain string but an extended POSIX - regex to match. + Treat the <string> given to -S as an extended POSIX regular + expression to match. @@ -701,6 +804,9 @@ of a delete/create pair. Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. + This overrides the diff.orderFile configuration variable + (see ). To cancel diff.orderFile, + use -O/dev/null. @@ -785,6 +891,16 @@ of a delete/create pair. +--ignore-blank-lines + + + + Ignore changes whose lines are all blank. + + + + + --inter-hunk-context=<lines> @@ -878,7 +994,7 @@ of a delete/create pair. Ignore changes to submodules in the diff generation. <when> can be - either "none", "untracked", "dirty" or "all", which is the default + either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the @@ -1142,7 +1258,8 @@ X: "unknown" change type (most probably a bug, please report it) Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or -copy), and are the only ones to be so. +copy). Status letter M may be followed by a score (denoting the +percentage of dissimilarity) for file rewrites. <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: @@ -1266,10 +1383,10 @@ rename to a combined diff format -Any diff-generating command can take the -c` or --cc option to +Any diff-generating command can take the -c or --cc option to produce a combined diff when showing a merge. This is the default format when showing merges with or -. Note also that you can give the `-m option to any +. Note also that you can give the -m option to any of these commands to force generation of diffs with individual parents of a merge. A combined diff format looks like this: @@ -1364,7 +1481,7 @@ added, from the point of view of that parent). 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 eight other lines are the same +in either file1 or file2). Also eight 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 diff --git a/doc/source/en/TortoiseGit/git_doc/git-diff-tree.xml b/doc/source/en/TortoiseGit/git_doc/git-diff-tree.xml index 31a797357..f8aa81b43 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-diff-tree.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-diff-tree.xml @@ -41,7 +41,20 @@ Generate patch (see section on generating patches). - + + + + + +-s + + +--no-patch + + + + Suppress diff output. Useful for commands like git show that + show the patch by default, or to cancel the effect of --patch. @@ -66,8 +79,8 @@ - Generate the raw format. - This is the default. + Generate the diff in raw format. + This is the default. @@ -114,6 +127,63 @@ +--diff-algorithm={patience|minimal|histogram|myers} + + + + Choose a diff algorithm. The variants are as follows: + + + + +default, myers + + + + The basic greedy diff algorithm. Currently, this is the default. + + + + + +minimal + + + + Spend extra time to make sure the smallest possible diff is + produced. + + + + + +patience + + + + Use "patience diff" algorithm when generating patches. + + + + + +histogram + + + + This algorithm extends the patience algorithm to "support + low-occurrence common elements". + + + + +For instance, if you configured diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option. + + + + --stat[=<width>[,<name-width>[,<count>]]] @@ -331,8 +401,8 @@ any of those replacements occurred. Show colored diff. - The value must be always (the default for <when>), never, or auto. - The default value is never. + --color (i.e. without =<when>) is the same as --color=always. + <when> can be one of always, never, or auto. @@ -428,6 +498,8 @@ differences. You may want to append |[^[:space:]] to your expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline. +For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character. The regex can also be set via a diff driver or configuration option, see or . Giving it explicitly overrides any diff driver or configuration setting. Diff drivers @@ -462,8 +534,8 @@ override configuration settings. - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by core.whitespace + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the @@ -475,6 +547,22 @@ override configuration settings. +--ws-error-highlight=<kind> + + + + Highlight whitespace errors on lines specified by <kind> + in the color specified by color.diff.whitespace. <kind> + is a comma separated list of old, new, context. When + this option is not given, only whitespace errors in new + lines are highlighted. E.g. --ws-error-highlight=new,old + highlights whitespace errors on both deleted and added lines. + all can be used as a short-hand for old,new,context. + + + + + --full-index @@ -529,7 +617,7 @@ few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for git to consider it a total +original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines). When used with -M, a totally-rewritten file is also considered as the @@ -553,13 +641,13 @@ another file. Detect renames. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the - file's size). For example, -M90% means git should consider a + file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use - -M100%. + -M100%. The default similarity index is 50%. @@ -604,7 +692,7 @@ another file. Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch - is not meant to be applied with patch nor git apply; this is + is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, @@ -653,11 +741,15 @@ of a delete/create pair. - Look for differences that introduce or remove an instance of - <string>. Note that this is different than the string simply - appearing in diff output; see the pickaxe entry in - for more details. + Look for differences that change the number of occurrences of + the specified string (i.e. addition/deletion) in a file. + Intended for the scripter's use. +It is useful when you're looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block. @@ -666,9 +758,20 @@ of a delete/create pair. - Look for differences whose added or removed line matches - the given <regex>. + Look for differences whose patch text contains added/removed + lines that match <regex>. +To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file: ++ return !regexec(regexp, two->ptr, 1, &regmatch, 0); +... +- hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0); +While git log -G"regexec\(regexp" will show this commit, git log +-S"regexec\(regexp" --pickaxe-regex will not (because the number of +occurrences of that string did not change). +See the pickaxe entry in for more +information. @@ -689,8 +792,8 @@ of a delete/create pair. - Make the <string> not a plain string but an extended POSIX - regex to match. + Treat the <string> given to -S as an extended POSIX regular + expression to match. @@ -702,6 +805,9 @@ of a delete/create pair. Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. + This overrides the diff.orderFile configuration variable + (see ). To cancel diff.orderFile, + use -O/dev/null. @@ -786,6 +892,16 @@ of a delete/create pair. +--ignore-blank-lines + + + + Ignore changes whose lines are all blank. + + + + + --inter-hunk-context=<lines> @@ -879,7 +995,7 @@ of a delete/create pair. Ignore changes to submodules in the diff generation. <when> can be - either "none", "untracked", "dirty" or "all", which is the default + either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the @@ -1053,10 +1169,13 @@ commits (but not trees). Pretty-print the contents of the commit logs in a given format, where <format> can be one of oneline, short, medium, - full, fuller, email, raw and format:<string>. See - the "PRETTY FORMATS" section for some additional details for each - format. When omitted, the format defaults to medium. + full, fuller, email, raw, format:<string> + and tformat:<string>. When <format> is none of the above, + and has %placeholder in it, it acts as if + --pretty=tformat:<format> were given. +See the "PRETTY FORMATS" section for some additional details for each +format. When =<format> part is omitted, it defaults to medium. Note: you can specify the default pretty format in the repository configuration (see ). @@ -1101,7 +1220,7 @@ people using 80-column terminals. ---encoding[=<encoding>] +--encoding=<encoding> @@ -1109,28 +1228,56 @@ people using 80-column terminals. in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this - defaults to UTF-8. + defaults to UTF-8. Note that if an object claims to be encoded + in X and we are outputting in X, we will output the object + verbatim; this means that invalid sequences in the original + commit may be copied to the output. ---notes[=<ref>] +--expand-tabs=<n> + + +--expand-tabs + + +--no-expand-tabs + + + + Perform a tab expansion (replace each tab with enough spaces + to fill to the next display column that is multiple of <n>) + in the log message before showing it in the output. + --expand-tabs is a short-hand for --expand-tabs=8, and + --no-expand-tabs is a short-hand for --expand-tabs=0, + which disables tab expansion. + +By default, tabs are expanded in pretty formats that indent the log +message by 4 spaces (i.e. medium, which is the default, full, +and fuller). + + + + +--notes[=<treeish>] Show the notes (see ) that annotate the commit, when showing the commit log message. This is the default for git log, git show and git whatchanged commands when - there is no --pretty, --format nor --oneline option given + there is no --pretty, --format, or --oneline option given on the command line. By default, the notes shown are from the notes refs listed in the core.notesRef and notes.displayRef variables (or corresponding environment overrides). See for more details. -With an optional <ref> argument, show this notes ref instead of the -default notes ref(s). The ref is taken to be in refs/notes/ if it -is not qualified. +With an optional <treeish> argument, use the treeish to find the notes +to display. The treeish can specify the full refname when it begins +with refs/notes/; when it begins with notes/, refs/ and otherwise +refs/notes/ is prefixed to form a full name of the ref. Multiple --notes options can be combined to control which notes are being displayed. Examples: "--notes=foo" will show only notes from "refs/notes/foo"; "--notes=foo --notes" will show both notes from @@ -1153,7 +1300,7 @@ being displayed. Examples: "--notes=foo" will show only notes from ---show-notes[=<ref>] +--show-notes[=<treeish>] --[no-]standard-notes @@ -1314,11 +1461,14 @@ Subject: [PATCH] <title line> raw The raw format shows the entire commit exactly as -stored in the commit object. Notably, the SHA1s are +stored in the commit object. Notably, the SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and parents information show the -true parent commits, without taking grafts nor history -simplification into account. +true parent commits, without taking grafts or history +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +git log --raw. To get full object names in a raw diff format, +use --no-abbrev. @@ -1371,7 +1521,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%aN: author name (respecting .mailmap, see or ) +%aN: author name (respecting .mailmap, see + or ) @@ -1381,7 +1532,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%aE: author email (respecting .mailmap, see or ) +%aE: author email (respecting .mailmap, see + or ) @@ -1406,7 +1558,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%ai: author date, ISO 8601 format +%ai: author date, ISO 8601-like format + + + + +%aI: author date, strict ISO 8601 format @@ -1416,7 +1573,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%cN: committer name (respecting .mailmap, see or ) +%cN: committer name (respecting .mailmap, see + or ) @@ -1426,12 +1584,13 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%cE: committer email (respecting .mailmap, see or ) +%cE: committer email (respecting .mailmap, see + or ) -%cd: committer date +%cd: committer date (format respects --date= option) @@ -1451,7 +1610,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%ci: committer date, ISO 8601 format +%ci: committer date, ISO 8601-like format + + + + +%cI: committer date, strict ISO 8601 format @@ -1461,6 +1625,11 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff +%D: ref names without the " (", ")" wrapping. + + + + %e: encoding @@ -1496,7 +1665,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%G?: show either "G" for Good or "B" for Bad for a signed commit +%G?: show "G" for a Good signature, "B" for a Bad signature, "U" for a good, + untrusted signature and "N" for no signature @@ -1506,6 +1676,11 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff +%GK: show the key used to sign a signed commit + + + + %gD: reflog selector, e.g., refs/stash@{1} @@ -1521,7 +1696,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%gN: reflog identity name (respecting .mailmap, see or ) +%gN: reflog identity name (respecting .mailmap, see + or ) @@ -1531,7 +1707,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%gE: reflog identity email (respecting .mailmap, see or ) +%gE: reflog identity email (respecting .mailmap, see + or ) @@ -1561,7 +1738,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%C(…): color specification, as described in color.branch.* config option +%C(…): color specification, as described in color.branch.* config option; + adding auto, at the beginning will emit color only when colors are + enabled for log output (by color.diff, color.ui, or --color, and + respecting the auto settings of the former if we are going to a + terminal). auto alone (i.e. %C(auto)) will turn on auto coloring + on the next placeholders until the color is switched again. @@ -1590,14 +1772,49 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff . + + +%<(<N>[,trunc|ltrunc|mtrunc]): make the next placeholder take at + least N columns, padding spaces on the right if necessary. + Optionally truncate at the beginning (ltrunc), the middle (mtrunc) + or the end (trunc) if the output is longer than N columns. + Note that truncating only works correctly with N >= 2. + + + + +%<|(<N>): make the next placeholder take at least until Nth + columns, padding spaces on the right if necessary + + + + +%>(<N>), %>|(<N>): similar to %<(<N>), %<|(<N>) + respectively, but padding spaces on the left + + + + +%>>(<N>), %>>|(<N>): similar to %>(<N>), %>|(<N>) + respectively, except that if the next placeholder takes more spaces + than given and there are spaces on its left, use those spaces + + + + +%><(<N>), %><|(<N>): similar to % <(<N>), %<|(<N>) + respectively, but padding both sides (i.e. the text is centered) + + Some placeholders may depend on other options given to the revision traversal engine. For example, the %g* reflog options will insert an empty string unless we are traversing reflog entries (e.g., by -git log -g). The %d placeholder will use the "short" decoration -format if --decorate was not already provided on the command line. +git log -g). The %d and %D placeholders will use the "short" +decoration format if --decorate was not already provided on the command +line. If you add a + (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string. @@ -1848,7 +2065,8 @@ X: "unknown" change type (most probably a bug, please report it) Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or -copy), and are the only ones to be so. +copy). Status letter M may be followed by a score (denoting the +percentage of dissimilarity) for file rewrites. <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: @@ -1972,10 +2190,10 @@ rename to a combined diff format -Any diff-generating command can take the -c` or --cc option to +Any diff-generating command can take the -c or --cc option to produce a combined diff when showing a merge. This is the default format when showing merges with or -. Note also that you can give the `-m option to any +. Note also that you can give the -m option to any of these commands to force generation of diffs with individual parents of a merge. A combined diff format looks like this: @@ -2070,7 +2288,7 @@ added, from the point of view of that parent). 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 eight other lines are the same +in either file1 or file2). Also eight 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 diff --git a/doc/source/en/TortoiseGit/git_doc/git-diff.xml b/doc/source/en/TortoiseGit/git_doc/git-diff.xml index a42a6ac8d..453dd7742 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-diff.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-diff.xml @@ -23,8 +23,8 @@ DESCRIPTION Show changes between the working tree and the index or a tree, changes -between the index and a tree, changes between two trees, or changes -between two files on disk. +between the index and a tree, changes between two trees, changes between +two blob objects, or changes between two files on disk. @@ -34,13 +34,25 @@ between two files on disk. This form is to view the changes you made relative to the index (staging area for the next commit). In other - words, the differences are what you could tell git to + words, the differences are what you could tell Git to further add to the index but you still haven't. You can stage these changes by using . -If exactly two paths are given and at least one points outside -the current repository, git diff will compare the two files / -directories. This behavior can be forced by --no-index. + + + + +git diff --no-index [--options] [--] [<path>…] + + + + This form is to compare the given two paths on the + filesystem. You can omit the --no-index option when + running the command in a working tree controlled by Git and + at least one of the paths points outside the working tree, + or when running the command outside a working tree + controlled by Git. + @@ -53,7 +65,7 @@ directories. This behavior can be forced by --no-index. commit relative to the named <commit>. Typically you would want comparison with the latest commit, so if you do not give <commit>, it defaults to HEAD. - If HEAD does not exist (e.g. unborned branches) and + If HEAD does not exist (e.g. unborn branches) and <commit> is not given, it shows all staged changes. --staged is a synonym of --cached. @@ -86,17 +98,6 @@ directories. This behavior can be forced by --no-index. -git diff [options] <blob> <blob> - - - - This form is to view the differences between the raw - contents of two blob objects. - - - - - git diff [--options] <commit>..<commit> [--] [<path>…] @@ -132,6 +133,19 @@ However, "diff" is about comparing two endpoints, not range and the range notations ("<commit>..<commit>" and "<commit>...<commit>") do not mean a range as defined in the "SPECIFYING RANGES" section in . + + + +git diff [options] <blob> <blob> + + + + This form is to view the differences between the raw + contents of two blob objects. + + + + OPTIONS @@ -149,7 +163,21 @@ and the range notations ("<commit>..<commit>" and Generate patch (see section on generating patches). - This is the default. + This is the default. + + + + + +-s + + +--no-patch + + + + Suppress diff output. Useful for commands like git show that + show the patch by default, or to cancel the effect of --patch. @@ -174,8 +202,7 @@ and the range notations ("<commit>..<commit>" and - Generate the raw format. - + Generate the diff in raw format. @@ -222,6 +249,63 @@ and the range notations ("<commit>..<commit>" and +--diff-algorithm={patience|minimal|histogram|myers} + + + + Choose a diff algorithm. The variants are as follows: + + + + +default, myers + + + + The basic greedy diff algorithm. Currently, this is the default. + + + + + +minimal + + + + Spend extra time to make sure the smallest possible diff is + produced. + + + + + +patience + + + + Use "patience diff" algorithm when generating patches. + + + + + +histogram + + + + This algorithm extends the patience algorithm to "support + low-occurrence common elements". + + + + +For instance, if you configured diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option. + + + + --stat[=<width>[,<name-width>[,<count>]]] @@ -439,8 +523,8 @@ any of those replacements occurred. Show colored diff. - The value must be always (the default for <when>), never, or auto. - The default value is never. + --color (i.e. without =<when>) is the same as --color=always. + <when> can be one of always, never, or auto. It can be changed by the color.ui and color.diff configuration settings. @@ -539,6 +623,8 @@ differences. You may want to append |[^[:space:]] to your expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline. +For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character. The regex can also be set via a diff driver or configuration option, see or . Giving it explicitly overrides any diff driver or configuration setting. Diff drivers @@ -573,8 +659,8 @@ override configuration settings. - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by core.whitespace + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the @@ -586,6 +672,22 @@ override configuration settings. +--ws-error-highlight=<kind> + + + + Highlight whitespace errors on lines specified by <kind> + in the color specified by color.diff.whitespace. <kind> + is a comma separated list of old, new, context. When + this option is not given, only whitespace errors in new + lines are highlighted. E.g. --ws-error-highlight=new,old + highlights whitespace errors on both deleted and added lines. + all can be used as a short-hand for old,new,context. + + + + + --full-index @@ -640,7 +742,7 @@ few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for git to consider it a total +original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines). When used with -M, a totally-rewritten file is also considered as the @@ -664,13 +766,13 @@ another file. Detect renames. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the - file's size). For example, -M90% means git should consider a + file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use - -M100%. + -M100%. The default similarity index is 50%. @@ -715,7 +817,7 @@ another file. Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch - is not meant to be applied with patch nor git apply; this is + is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, @@ -764,11 +866,15 @@ of a delete/create pair. - Look for differences that introduce or remove an instance of - <string>. Note that this is different than the string simply - appearing in diff output; see the pickaxe entry in - for more details. + Look for differences that change the number of occurrences of + the specified string (i.e. addition/deletion) in a file. + Intended for the scripter's use. +It is useful when you're looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block. @@ -777,9 +883,20 @@ of a delete/create pair. - Look for differences whose added or removed line matches - the given <regex>. + Look for differences whose patch text contains added/removed + lines that match <regex>. +To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file: ++ return !regexec(regexp, two->ptr, 1, &regmatch, 0); +... +- hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0); +While git log -G"regexec\(regexp" will show this commit, git log +-S"regexec\(regexp" --pickaxe-regex will not (because the number of +occurrences of that string did not change). +See the pickaxe entry in for more +information. @@ -800,8 +917,8 @@ of a delete/create pair. - Make the <string> not a plain string but an extended POSIX - regex to match. + Treat the <string> given to -S as an extended POSIX regular + expression to match. @@ -813,6 +930,9 @@ of a delete/create pair. Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. + This overrides the diff.orderFile configuration variable + (see ). To cancel diff.orderFile, + use -O/dev/null. @@ -897,6 +1017,16 @@ of a delete/create pair. +--ignore-blank-lines + + + + Ignore changes whose lines are all blank. + + + + + --inter-hunk-context=<lines> @@ -990,7 +1120,7 @@ of a delete/create pair. Ignore changes to submodules in the diff generation. <when> can be - either "none", "untracked", "dirty" or "all", which is the default + either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the @@ -1233,7 +1363,8 @@ X: "unknown" change type (most probably a bug, please report it) Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or -copy), and are the only ones to be so. +copy). Status letter M may be followed by a score (denoting the +percentage of dissimilarity) for file rewrites. <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: @@ -1357,10 +1488,10 @@ rename to a combined diff format -Any diff-generating command can take the -c` or --cc option to +Any diff-generating command can take the -c or --cc option to produce a combined diff when showing a merge. This is the default format when showing merges with or -. Note also that you can give the `-m option to any +. Note also that you can give the -m option to any of these commands to force generation of diffs with individual parents of a merge. A combined diff format looks like this: @@ -1455,7 +1586,7 @@ added, from the point of view of that parent). 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 eight other lines are the same +in either file1 or file2). Also eight 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 @@ -1671,8 +1802,8 @@ $ git diff arch/i386 include/asm-i386 -Show only modification, rename and copy, but not addition -nor deletion. +Show only modification, rename, and copy, but not addition +or deletion. diff --git a/doc/source/en/TortoiseGit/git_doc/git-difftool.xml b/doc/source/en/TortoiseGit/git_doc/git-difftool.xml index 3a902a4be..2d6b92733 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-difftool.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-difftool.xml @@ -18,7 +18,7 @@ DESCRIPTION -git difftool is a git command that allows you to compare and edit files +git difftool is a Git command that allows you to compare and edit files between revisions using common diff tools. git difftool is a frontend to git diff and accepts the same options and arguments. See . @@ -115,18 +115,17 @@ with custom merge tool commands and has the same value as $MERGED ---symlinks - - ---no-symlinks +--[no-]symlinks git difftool's default behavior is create symlinks to the - working tree when run in --dir-diff mode. + working tree when run in --dir-diff mode and the right-hand + side of the comparison yields the same content as the file in + the working tree. -Specifying `--no-symlinks` instructs 'git difftool' to create -copies instead. `--no-symlinks` is the default on Windows. +Specifying --no-symlinks instructs git difftool to create copies +instead. --no-symlinks is the default on Windows. @@ -160,6 +159,21 @@ copies instead. `--no-symlinks` is the default on Windows. + + +--[no-]trust-exit-code + + + + git-difftool invokes a diff tool individually on each file. + Errors reported by the diff tool are ignored by default. + Use --trust-exit-code to make git-difftool exit when an + invoked diff tool returns a non-zero exit code. + +git-difftool will forward the exit code of the invoked tool when +--trust-exit-code is used. + + See for the full list of supported options. @@ -220,6 +234,17 @@ difftool.prompt + + +difftool.trustExitCode + + + + Exit difftool if the invoked diff tool returns a non-zero exit status. + +See the --trust-exit-code option above for more details. + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-doc.xml b/doc/source/en/TortoiseGit/git_doc/git-doc.xml index 3e75b7bbc..a31203f67 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-doc.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-doc.xml @@ -12,7 +12,7 @@ - + Git Command Reference @@ -29,6 +29,8 @@ + + @@ -80,8 +82,8 @@ + - @@ -106,7 +108,6 @@ - @@ -119,12 +120,10 @@ - - @@ -151,7 +150,6 @@ - @@ -160,10 +158,12 @@ + + @@ -177,6 +177,7 @@ + diff --git a/doc/source/en/TortoiseGit/git_doc/git-fast-export.xml b/doc/source/en/TortoiseGit/git_doc/git-fast-export.xml index b62b30aad..cad2daf1d 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-fast-export.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-fast-export.xml @@ -40,7 +40,7 @@ into git fast-import. ---signed-tags=(verbatim|warn|strip|abort) +--signed-tags=(verbatim|warn|warn-strip|strip|abort) @@ -49,9 +49,11 @@ into git fast-import. when excluding revisions) the signatures will not match. When asking to abort (which is the default), this program will die -when encountering a signed tag. With strip, the tags will be made -unsigned, with verbatim, they will be silently exported -and with warn, they will be exported, but you will see a warning. +when encountering a signed tag. With strip, the tags will silently +be made unsigned, with warn-strip they will be made unsigned but a +warning will be displayed, with verbatim, they will be silently +exported and with warn, they will be exported, but you will see a +warning. @@ -102,6 +104,8 @@ produced incorrect results if you gave these options. incremental runs. As <file> is only opened and truncated at completion, the same path can also be safely given to --import-marks. + The file will not be written if no new object has been + marked/exported. @@ -175,15 +179,38 @@ marks the same across runs. +--anonymize + + + + Anonymize the contents of the repository while still retaining + the shape of the history and stored tree. See the section on + ANONYMIZING below. + + + + + +--refspec + + + + Apply the specified refspec to each ref exported. Multiple of them can + be specified. + + + + + [<git-rev-list-args>…] - A list of arguments, acceptable to git rev-parse and - git rev-list, that specifies the specific objects and references - to export. For example, master~10..master causes the - current master reference to be exported along with all objects - added since its 10th ancestor commit. + A list of arguments, acceptable to git rev-parse and + git rev-list, that specifies the specific objects and references + to export. For example, master~10..master causes the + current master reference to be exported along with all objects + added since its 10th ancestor commit. @@ -204,12 +231,56 @@ UTF-8, it would be a one-to-one mirror. referenced by that revision range contains the string refs/heads/master. + +ANONYMIZING +If the --anonymize option is given, git will attempt to remove all +identifying information from the repository while still retaining enough +of the original tree and history patterns to reproduce some bugs. The +goal is that a git bug which is found on a private repository will +persist in the anonymized repository, and the latter can be shared with +git developers to help solve the bug. +With this option, git will replace all refnames, paths, blob contents, +commit and tag messages, names, and email addresses in the output with +anonymized data. Two instances of the same string will be replaced +equivalently (e.g., two commits with the same author will have the same +anonymized author in the output, but bear no resemblance to the original +author string). The relationship between commits, branches, and tags is +retained, as well as the commit timestamps (but the commit messages and +refnames bear no resemblance to the originals). The relative makeup of +the tree is retained (e.g., if you have a root tree with 10 files and 3 +trees, so will the output), but their names and the contents of the +files will be replaced. +If you think you have found a git bug, you can start by exporting an +anonymized stream of the whole repository: +$ git fast-export --anonymize --all >anon-stream +Then confirm that the bug persists in a repository created from that +stream (many bugs will not, as they really do depend on the exact +repository contents): +$ git init anon-repo +$ cd anon-repo +$ git fast-import <../anon-stream +$ ... test your bug ... +If the anonymized repository shows the bug, it may be worth sharing +anon-stream along with a regular bug report. Note that the anonymized +stream compresses very well, so gzipping it is encouraged. If you want +to examine the stream to see that it does not contain any private data, +you can peruse it directly before sending. You may also want to try: +$ perl -pe 's/\d+/X/g' <anon-stream | sort -u | less +which shows all of the unique lines (with numbers converted to "X", to +collapse "User 0", "User 1", etc into "User X"). This produces a much +smaller output, and it is usually easy to quickly confirm that there is +no private data in the stream. + Limitations Since git fast-import cannot tag trees, you will not be -able to export the linux-2.6.git repository completely, as it contains +able to export the linux.git repository completely, as it contains a tag referencing a tree instead of a commit. + +SEE ALSO + + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-fast-import.xml b/doc/source/en/TortoiseGit/git_doc/git-fast-import.xml index 2efce1f12..70d0b86e8 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-fast-import.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-fast-import.xml @@ -38,86 +38,89 @@ the frontend program in use. ---date-format=<fmt> - - - - Specify the type of dates the frontend will supply to - fast-import within author, committer and tagger commands. - See Date Formats below for details about which formats - are supported, and their syntax. - - - - - --- done +--force - Terminate with error if there is no done command at the - end of the stream. + Force updating modified existing branches, even if doing + so would cause commits to be lost (as the new commit does + not contain the old commit). ---force +--quiet - Force updating modified existing branches, even if doing - so would cause commits to be lost (as the new commit does - not contain the old commit). + Disable all non-fatal output, making fast-import silent when it + is successful. This option disables the output shown by + --stats. ---max-pack-size=<n> +--stats - Maximum size of each output packfile. - The default is unlimited. + Display some basic statistics about the objects fast-import has + created, the packfiles they were stored into, and the + memory used by fast-import during this run. Showing this output + is currently the default, but can be disabled with --quiet. + +
+Options for Frontends + ---big-file-threshold=<n> +--cat-blob-fd=<fd> - Maximum size of a blob that fast-import will attempt to - create a delta for, expressed in bytes. The default is 512m - (512 MiB). Some importers may wish to lower this on systems - with constrained memory. + Write responses to get-mark, cat-blob, and ls queries to the + file descriptor <fd> instead of stdout. Allows progress + output intended for the end-user to be separated from other + output. ---depth=<n> +--date-format=<fmt> - Maximum delta depth, for blob and tree deltification. - Default is 10. + Specify the type of dates the frontend will supply to + fast-import within author, committer and tagger commands. + See Date Formats below for details about which formats + are supported, and their syntax. ---active-branches=<n> +--done - Maximum number of branches to maintain active at once. - See Memory Utilization below for details. Default is 5. + Terminate with error if there is no done command at the end of + the stream. This option might be useful for detecting errors + that cause the frontend to terminate before it has started to + write a stream. + +
+
+Locations of Marks Files + --export-marks=<file> @@ -162,7 +165,7 @@ the frontend program in use. ---relative-marks +--[no-]relative-marks @@ -173,44 +176,47 @@ the frontend program in use. to the .git/info/fast-import directory. However, other importers may use a different location. +Relative and non-relative marks may be combined by interweaving +--(no-)-relative-marks with the --(import|export)-marks= options. + +
+
+Performance and Compression Tuning + ---no-relative-marks +--active-branches=<n> - Negates a previous --relative-marks. Allows for combining - relative and non-relative marks by interweaving - --(no-)-relative-marks with the --(import|export)-marks= - options. + Maximum number of branches to maintain active at once. + See Memory Utilization below for details. Default is 5. ---cat-blob-fd=<fd> +--big-file-threshold=<n> - Write responses to cat-blob and ls queries to the - file descriptor <fd> instead of stdout. Allows progress - output intended for the end-user to be separated from other - output. + Maximum size of a blob that fast-import will attempt to + create a delta for, expressed in bytes. The default is 512m + (512 MiB). Some importers may wish to lower this on systems + with constrained memory. ---done +--depth=<n> - Require a done command at the end of the stream. - This option might be useful for detecting errors that - cause the frontend to terminate before it has started to - write a stream. + Maximum delta depth, for blob and tree deltification. + Default is 10. @@ -232,30 +238,17 @@ the frontend program in use. ---quiet - - - - Disable all non-fatal output, making fast-import silent when it - is successful. This option disables the output shown by - --stats. - - - - - ---stats +--max-pack-size=<n> - Display some basic statistics about the objects fast-import has - created, the packfiles they were stored into, and the - memory used by fast-import during this run. Showing this output - is currently the default, but can be disabled with --quiet. + Maximum size of each output packfile. + The default is unlimited. +
 Performance @@ -342,7 +335,7 @@ frontend and useful when inspecting a fast-import data stream. Date Formats The following date formats are supported. A frontend should select the format it will use for this import by passing the format name -in the --date-format=<fmt> command line option. +in the --date-format=<fmt> command-line option. @@ -365,7 +358,7 @@ advisement to help formatting routines display the timestamp. If the local offset is not available in the source material, use +0000, or the most common local offset. For example many organizations have a CVS repository which has only ever been accessed -by users who are located in the same location and timezone. In this +by users who are located in the same location and time zone. In this case a reasonable offset from UTC could be assumed. Unlike the rfc2822 format, this format is very strict. Any variation in formatting will cause fast-import to reject the value. @@ -388,7 +381,7 @@ these cases Git will still be able to obtain the correct date from the malformed string. There are also some types of malformed strings which Git will parse wrong, and yet consider valid. Seriously malformed strings will be rejected. -Unlike the raw format above, the timezone/UTC offset information +Unlike the raw format above, the time zone/UTC offset information contained in an RFC 2822 date string is used to adjust the date value to UTC prior to storage. Therefore it is important that this information be as accurate as possible. @@ -408,13 +401,13 @@ ambiguity in parsing. - Always use the current time and timezone. The literal + Always use the current time and time zone. The literal now must always be supplied for <when>. -This is a toy format. The current time and timezone of this system +This is a toy format. The current time and time zone of this system is always copied into the identity string at the time it is being created by fast-import. There is no way to specify a different time or -timezone. +time zone. This particular format is supplied as it's short to implement and may be useful to a process that wants to create a new commit right now, without needing to use a working directory or @@ -517,7 +510,19 @@ and control the current import process. More detailed discussion Marks the end of the stream. This command is optional unless the done feature was requested using the - --done command line option or feature done command. + --done command-line option or feature done command. + + + + + +get-mark + + + + Causes fast-import to print the SHA-1 corresponding to a mark + to the file descriptor set with --cat-blob-fd, or stdout if + unspecified. @@ -551,8 +556,8 @@ and control the current import process. More detailed discussion - Require that fast-import supports the specified feature, or - abort if it does not. + Enable the specified feature. This requires that fast-import + supports the specified feature, and aborts if it does not. @@ -579,8 +584,8 @@ change to the project. ('author' (SP <name>)? SP LT <email> GT SP <when> LF)? 'committer' (SP <name>)? SP LT <email> GT SP <when> LF data - ('from' SP <committish> LF)? - ('merge' SP <committish> LF)? + ('from' SP <commit-ish> LF)? + ('merge' SP <commit-ish> LF)? (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)* LF? where <ref> is the name of the branch to make the commit on. @@ -627,7 +632,7 @@ the email address from the other fields in the line. Note that <name> and <email> are free-form and may contain any sequence of bytes, except LT, GT and LF. <name> is typically UTF-8 encoded. The time of the change is specified by <when> using the date format -that was selected by the --date-format=<fmt> command line option. +that was selected by the --date-format=<fmt> command-line option. See Date Formats above for the set of supported formats, and their syntax. @@ -648,8 +653,8 @@ Omitting the from command on existing branches is usually d as the current commit on that branch is automatically assumed to be the first ancestor of the new commit. As LF is not valid in a Git refname or SHA-1 expression, no -quoting or escaping syntax is supported within <committish>. -Here <committish> is any of the following: +quoting or escaping syntax is supported within <commit-ish>. +Here <commit-ish> is any of the following: @@ -680,6 +685,12 @@ Any valid Git SHA-1 expression that resolves to a commit. See SPECIFYING REVISIONS in for details. + + +The special null SHA-1 (40 zeros) specifies that the branch is to be + removed. + + The special case of restarting an incremental import from the current branch value should be written as: @@ -699,12 +710,8 @@ If the from command is omitted when creating a new branch, the first merge commit will be the first ancestor of the current commit, and the branch will start out with no files. An unlimited number of merge commands per -commit are permitted by fast-import, thereby establishing an n-way merge. -However Git's other tools never create commits with more than 15 -additional ancestors (forming a 16-way merge). For this reason -it is suggested that frontends do not use more than 15 merge -commands per commit; 16, if starting a new, empty branch. -Here <committish> is any of the commit specification expressions +commit are permitted by fast-import, thereby establishing an n-way merge. +Here <commit-ish> is any of the commit specification expressions also accepted by from (see above).
@@ -891,8 +898,8 @@ paths for a commit are encouraged to do so.
<emphasis>notemodify</emphasis> Included in a commit <notes_ref> command to add a new note -annotating a <committish> or change this annotation contents. -Internally it is similar to filemodify 100644 on <committish> +annotating a <commit-ish> or change this annotation contents. +Internally it is similar to filemodify 100644 on <commit-ish> path (maybe split into subdirectories). It's not advised to use any other commands to write to the <notes_ref> tree except filedeleteall to delete all existing notes in this tree. @@ -909,7 +916,7 @@ External data format blob command. The frontend just needs to connect it to the commit that is to be annotated. - 'N' SP <dataref> SP <committish> LF + 'N' SP <dataref> SP <commit-ish> LF Here <dataref> can be either a mark reference (:<idnum>) set by a prior blob command, or a full 40-byte SHA-1 of an existing Git blob object. @@ -925,13 +932,13 @@ Inline data format The frontend wants to supply it as part of this modify command. - 'N' SP 'inline' SP <committish> LF + 'N' SP 'inline' SP <commit-ish> LF data See below for a detailed description of the data command. -In both formats <committish> is any of the commit specification +In both formats <commit-ish> is any of the commit specification expressions also accepted by from (see above).
@@ -956,7 +963,7 @@ to another object simply by reusing the same <idnum> Creates an annotated tag referring to a specific commit. To create lightweight (non-annotated) tags see the reset command below. 'tag' SP <name> LF - 'from' SP <committish> LF + 'from' SP <commit-ish> LF 'tagger' (SP <name>)? SP LT <email> GT SP <when> LF data where <name> is the name of the tag to create. @@ -991,9 +998,9 @@ a specific revision. The reset command allows a frontend to issue a new from command for an existing branch, or to create a new branch from an existing commit without creating a new commit. 'reset' SP <ref> LF - ('from' SP <committish> LF)? + ('from' SP <commit-ish> LF)? LF? -For a detailed description of <ref> and <committish> see above +For a detailed description of <ref> and <commit-ish> see above under commit and from. The LF after the command is optional (it used to be required). The reset command can also be used to create lightweight @@ -1118,6 +1125,20 @@ remove the leading part of the line, for example: inform the reader when the checkpoint has been completed and it can safely access the refs that fast-import updated. +
+<emphasis>get-mark</emphasis> +Causes fast-import to print the SHA-1 corresponding to a mark to +stdout or to the file descriptor previously arranged with the +--cat-blob-fd argument. The command otherwise has no impact on the +current import; its purpose is to retrieve SHA-1s that later commits +might want to refer to in their commit messages. + 'get-mark' SP ':' <idnum> LF +This command can be used anywhere in the stream that comments are +accepted. In particular, the get-mark command can be used in the +middle of a commit but not in the middle of a data command. +See Responses To Commands below for details about how to read +this output safely. +
<emphasis>cat-blob</emphasis> Causes fast-import to print a blob to a file descriptor previously @@ -1185,7 +1206,8 @@ Reading from a named tree <mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF The <dataref> represents the blob, tree, or commit object at <path> -and can be used in later cat-blob, filemodify, or ls commands. +and can be used in later get-mark, cat-blob, filemodify, or +ls commands. If there is no file or subtree at that path, git fast-import will instead report @@ -1246,6 +1268,9 @@ import-marks-if-exists +get-mark + + cat-blob @@ -1253,7 +1278,8 @@ ls - Require that the backend support the cat-blob or ls command. + Require that the backend support the get-mark, cat-blob, + or ls command respectively. Versions of fast-import not supporting the specified command will exit with a message indicating so. This lets the import error out early with a clear message, @@ -1305,7 +1331,7 @@ without the leading -- and is treated in the same way.Option commands must be the first commands on the input (not counting feature commands), to give an option command after any non-option command is an error. -The following commandline options change import semantics and may therefore +The following command-line options change import semantics and may therefore not be passed as option: @@ -1339,7 +1365,7 @@ force <emphasis>done</emphasis> If the done feature is not in use, treated as if EOF was read. This can be used to tell fast-import to finish early. -If the --done command line option or feature done command is +If the --done command-line option or feature done command is in use, the done command is mandatory and marks the end of the stream.
@@ -1363,10 +1389,10 @@ bidirectional pipes: frontend <fast-import-output | git fast-import >fast-import-output -A frontend set up this way can use progress, ls, and cat-blob -commands to read information from the import in progress. +A frontend set up this way can use progress, get-mark, ls, and +cat-blob commands to read information from the import in progress. To avoid deadlock, such frontends must completely consume any -pending output from progress, ls, and cat-blob before +pending output from progress, ls, get-mark, and cat-blob before performing writes to fast-import that might block. @@ -1643,6 +1669,10 @@ operator can use this facility to peek at the objects and refs from an import in progress, at the cost of some added running time and worse compression. + +SEE ALSO + + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-fetch-pack.xml b/doc/source/en/TortoiseGit/git_doc/git-fetch-pack.xml index b50e6fe07..6b31c77ee 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-fetch-pack.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-fetch-pack.xml @@ -14,9 +14,9 @@ SYNOPSIS
git fetch-pack [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] - [--upload-pack=<git-upload-pack>] - [--depth=<n>] [--no-progress] - [-v] [<host>:]<directory> [<refs>…] + [--upload-pack=<git-upload-pack>] + [--depth=<n>] [--no-progress] + [-v] <repository> [<refs>…]
@@ -151,6 +151,8 @@ be in a separate packet, and the list must end with a flush packet. Limit fetching to ancestor-chains not longer than n. + git-upload-pack treats the special depth 2147483647 as + infinite even if there is an ancestor-chain that long. @@ -166,33 +168,32 @@ be in a separate packet, and the list must end with a flush packet. --v +--check-self-contained-and-connected - Run verbosely. + Output "connectivity-ok" if the received pack is + self-contained and connected. -<host> +-v - A remote host that houses the repository. When this - part is specified, git-upload-pack is invoked via - ssh. + Run verbosely. -<directory> +<repository> - The repository to sync from. + The URL to the remote repository. @@ -206,10 +207,17 @@ be in a separate packet, and the list must end with a flush packet. $GIT_DIR (e.g. "HEAD", "refs/heads/master"). When unspecified, update from all heads the remote side has. +If the remote has enabled the options uploadpack.allowTipSHA1InWant or +uploadpack.allowReachableSHA1InWant, they may alternatively be 40-hex +sha1s present on the remote. + +SEE ALSO + + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-fetch.xml b/doc/source/en/TortoiseGit/git_doc/git-fetch.xml index 06cd6bf3c..d25fc3de1 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-fetch.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-fetch.xml @@ -21,22 +21,26 @@ DESCRIPTION -Fetches named heads or tags from one or more other repositories, -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. -When <refspec> stores the fetched result in remote-tracking branches, -the tags that point at these branches are automatically -followed. This is done by first fetching from the remote using -the given <refspec>s, and if the repository has objects that are -pointed by remote tags that it does not yet have, then fetch -those missing tags. If the other end has tags that point at -branches you are not interested in, you will not get them. -git fetch can fetch from either a single named repository, +Fetch branches and/or tags (collectively, "refs") from one or more +other repositories, along with the objects necessary to complete their +histories. Remote-tracking branches are updated (see the description +of <refspec> below for ways to control this behavior). +By default, any tag that points into the histories being fetched is +also fetched; the effect is to fetch tags that +point at branches that you are interested in. This default behavior +can be changed by using the --tags or --no-tags options or by +configuring remote.<name>.tagOpt. By using a refspec that fetches tags +explicitly, you can fetch tags that do not point into branches you +are interested in as well. +git fetch can fetch from either a single named repository or URL, or from several repositories at once if <group> is given and there is a remotes.<group> entry in the configuration file. (See ). +When no remote is specified, by default the origin remote will be used, +unless there's an upstream branch configured for the current branch. +The names of refs that are fetched, together with the object names +they point at, are written to .git/FETCH_HEAD. This information +may be used by scripts or other git commands, such as . OPTIONS @@ -72,10 +76,38 @@ there is a remotes.<group> entry in the configuration file. - Deepen the history of a shallow repository created by - git clone with --depth=<depth> option (see ) - to the specified number of commits from the tip of each remote - branch history. Tags for the deepened commits are not fetched. + Limit fetching to the specified number of commits from the tip of + each remote branch history. If fetching to a shallow repository + created by git clone with --depth=<depth> option (see + ), deepen or shorten the history to the specified + number of commits. Tags for the deepened commits are not fetched. + + + + + +--unshallow + + + + If the source repository is complete, convert a shallow + repository to a complete one, removing all the limitations + imposed by shallow repositories. + +If the source repository is shallow, fetch as much as possible so that +the current repository has the same history as the source repository. + + + + +--update-shallow + + + + By default when fetching from a shallow repository, + git fetch refuses refs that require updating + .git/shallow. This option updates .git/shallow and accept such + refs. @@ -139,8 +171,14 @@ there is a remotes.<group> entry in the configuration file. - After fetching, remove any remote-tracking branches which - no longer exist on the remote. + After fetching, remove any remote-tracking references that no + longer exist on the remote. Tags are not subject to pruning + if they are fetched only because of the default tag + auto-following or due to a --tags option. However, if tags + are fetched due to an explicit refspec (either on the command + line or in the remote configuration, for example if the remote + was cloned with the --mirror option), then they are also + subject to pruning. @@ -156,13 +194,28 @@ there is a remotes.<group> entry in the configuration file. By default, tags that point at objects that are downloaded from the remote repository are fetched and stored locally. This option disables this automatic tag following. The default - behavior for a remote may be specified with the remote.<name>.tagopt + behavior for a remote may be specified with the remote.<name>.tagOpt setting. See . +--refmap=<refspec> + + + + When fetching refs listed on the command line, use the + specified refspec (can be given more than once) to map the + refs to remote-tracking branches, instead of the values of + remote.*.fetch configuration variables for the remote + repository. See section on "Configured Remote-tracking + Branches" for details. + + + + + -t @@ -170,11 +223,12 @@ there is a remotes.<group> entry in the configuration file. - This is a short-hand for giving "refs/tags/:refs/tags/" - refspec from the command line, to ask all tags to be fetched - and stored locally. Because this acts as an explicit - refspec, the default refspecs (configured with the - remote.$name.fetch variable) are overridden and not used. + Fetch all tags from the remote (i.e., fetch remote tags + refs/tags/* into local tags with the same name), in addition + to whatever else would otherwise be fetched. Using this + option alone does not subject tags to pruning, even if --prune + is used (though tags may be pruned anyway if they are also the + destination of an explicit refspec; see --prune). @@ -198,6 +252,22 @@ there is a remotes.<group> entry in the configuration file. +-j + + +--jobs=<n> + + + + Number of parallel children to be used for fetching submodules. + Each will fetch from different submodules, such that fetching many + submodules will be faster. By default submodules will be fetched + one at a time. + + + + + --no-recurse-submodules @@ -308,6 +378,32 @@ there is a remotes.<group> entry in the configuration file. +-4 + + +--ipv4 + + + + Use IPv4 addresses only, ignoring IPv6 addresses. + + + + + +-6 + + +--ipv6 + + + + Use IPv6 addresses only, ignoring IPv4 addresses. + + + + + <repository> @@ -337,67 +433,33 @@ there is a remotes.<group> entry in the configuration file. - The format of a <refspec> parameter is an optional plus - +, followed by the source ref <src>, followed - by a colon :, followed by the destination ref <dst>. + Specifies which refs to fetch and which local refs to update. + When no <refspec>s appear on the command line, the refs to fetch + are read from remote.<repository>.fetch variables instead + (see CONFIGURED REMOTE-TRACKING BRANCHES below). +The format of a <refspec> parameter is an optional plus ++, followed by the source ref <src>, followed +by a colon :, followed by the destination ref <dst>. +The colon can be omitted when <dst> is empty. +tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; +it requests fetching everything up to the given tag. The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast-forwarded using <src>. If the optional plus + is used, the local ref is updated even if it does not result in a fast-forward update. -If the remote branch from which you want to pull is -modified in non-linear ways such as being rewound and -rebased frequently, then a pull will attempt a merge with -an older version of itself, likely conflict, and fail. -It is under these conditions that you would want to use -the + sign to indicate non-fast-forward updates will -be needed. There is currently no easy way to determine -or declare that a branch will be made available in a -repository with this behavior; the pulling user simply +When the remote branch you want to fetch is known to +be rewound and rebased regularly, it is expected that +its new tip will not be descendant of its previous tip +(as stored in your remote-tracking branch the last time +you fetched). You would want +to use the + sign to indicate non-fast-forward updates +will be needed for such branches. There is no way to +determine or declare that a branch will be made available +in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch. -You never do your own development on branches that appear -on the right hand side of a <refspec> colon on Pull: lines; -they are to be updated by git fetch. If you intend to do -development derived from a remote branch B, have a Pull: -line to track it (i.e. Pull: B:remote-B), and have a separate -branch my-B to do your development on top of it. The latter -is created by git branch my-B remote-B (or its equivalent git -checkout -b my-B remote-B). Run git fetch to keep track of -the progress of the remote side, and when you see something new -on the remote branch, merge it into your development branch with -git pull . remote-B, while you are on my-B branch. -There is a difference between listing multiple <refspec> -directly on git pull command line and having multiple -Pull: <refspec> lines for a <repository> and running -git pull command without any explicit <refspec> parameters. -<refspec> listed explicitly on the command line are always -merged into the current branch after fetching. In other words, -if you list more than one remote refs, you would be making -an Octopus. While git pull run without any explicit <refspec> -parameter takes default <refspec>s from Pull: lines, it -merges only the first <refspec> found into the current branch, -after fetching all the remote refs. This is because making an -Octopus from remote refs is rarely done, while keeping track -of multiple remote heads in one-go by fetching more than one -is often useful. -Some short-cut notations are also supported. - - - -tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; - it requests fetching everything up to the given tag. - - - - -A parameter <ref> without a colon is equivalent to - <ref>: when pulling/fetching, so it merges <ref> into the current - branch without storing the remote branch anywhere locally - - - @@ -409,9 +471,10 @@ address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. Git supports ssh, git, http, and https protocols (in addition, ftp, -and ftps can be used for fetching and rsync can be used for fetching -and pushing, but these are inefficient and deprecated; do not use -them). +and ftps can be used for fetching, but this is inefficient and +deprecated; do not use it). +The native transport (i.e. git:// URL) does no authentication and +should be used with caution on unsecured networks. The following syntaxes may be used with them: @@ -434,11 +497,6 @@ http[s]://host.xz[:port]/path/to/repo.git/ ftp[s]://host.xz[:port]/path/to/repo.git/ - - -rsync://host.xz/path/to/repo.git/ - - An alternative scp-like syntax may also be used with the ssh protocol: @@ -448,6 +506,11 @@ rsync://host.xz/path/to/repo.git/ +This syntax is only recognized if there are no slashes before the +first colon. This helps differentiate a local path that contains a +colon. For example the local path foo:bar could be specified as an +absolute path or ./foo:bar to avoid being misinterpreted as an ssh +url. The ssh and git protocols additionally support ~username expansion: @@ -466,7 +529,7 @@ git://host.xz[:port]/~[user]/path/to/repo.git/ -For local repositories, also supported by git natively, the following +For local repositories, also supported by Git natively, the following syntaxes may be used: @@ -476,14 +539,14 @@ syntaxes may be used: -file:///path/to/repo.git/ +file:///path/to/repo.git/ These two syntaxes are mostly equivalent, except when cloning, when the former implies --local option. See for details. -When git doesn't know how to handle a certain transport protocol, it +When Git doesn't know how to handle a certain transport protocol, it attempts to use the remote-<transport> remote helper, if one exists. To explicitly request a remote helper, the following syntax may be used: @@ -496,7 +559,7 @@ may be used: where <address> may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being -invoked. See for details. +invoked. See for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you use will be rewritten into URLs that work), you can create a @@ -527,7 +590,7 @@ of a URL as <repository> argument: -a remote in the git configuration file: $GIT_DIR/config, +a remote in the Git configuration file: $GIT_DIR/config, @@ -594,6 +657,55 @@ refspecs, if you don't provide one on the command line. HEAD:refs/heads/<head> + +CONFIGURED REMOTE-TRACKING BRANCHES<anchor id="git-fetch(1)_CRTB" xreflabel="[CRTB]"/> +You often interact with the same remote repository by +regularly and repeatedly fetching from it. In order to keep track +of the progress of such a remote repository, git fetch allows you +to configure remote.<repository>.fetch configuration variables. +Typically such a variable may look like this: +[remote "origin"] + fetch = +refs/heads/*:refs/remotes/origin/* +This configuration is used in two ways: + + + +When git fetch is run without specifying what branches + and/or tags to fetch on the command line, e.g. git fetch origin + or git fetch, remote.<repository>.fetch values are used as + the refspecs--they specify which refs to fetch and which local refs + to update. The example above will fetch + all branches that exist in the origin (i.e. any ref that matches + the left-hand side of the value, refs/heads/*) and update the + corresponding remote-tracking branches in the refs/remotes/origin/* + hierarchy. + + + + +When git fetch is run with explicit branches and/or tags + to fetch on the command line, e.g. git fetch origin master, the + <refspec>s given on the command line determine what are to be + fetched (e.g. master in the example, + which is a short-hand for master:, which in turn means + "fetch the master branch but I do not explicitly say what + remote-tracking branch to update with it from the command line"), + and the example command will + fetch only the master branch. The remote.<repository>.fetch + values determine which + remote-tracking branch, if any, is updated. When used in this + way, the remote.<repository>.fetch values do not have any + effect in deciding what gets fetched (i.e. the values are not + used as refspecs when the command-line lists refspecs); they are + only used to decide where the refs that are fetched are stored + by acting as a mapping. + + + +The latter use of the remote.<repository>.fetch values can be +overridden by giving the --refmap=<refspec> parameter(s) on the +command line. + EXAMPLES @@ -618,6 +730,19 @@ the local repository by fetching from the branches (respectively) The pu branch will be updated even if it is does not fast-forward, because it is prefixed with a plus sign; tmp will not be. + + +Peek at a remote's branch, without configuring the remote in your local +repository: + +$ git fetch git://git.kernel.org/pub/scm/git/git.git maint +$ git log FETCH_HEAD +The first command fetches the maint branch from the repository at +git://git.kernel.org/pub/scm/git/git.git and the second command uses +FETCH_HEAD to examine the branch with . The fetched +objects will eventually be removed by git's built-in housekeeping (see +). + @@ -626,7 +751,7 @@ because it is prefixed with a plus sign; tmp will not be. diff --git a/doc/source/en/TortoiseGit/git_doc/git-filter-branch.xml b/doc/source/en/TortoiseGit/git_doc/git-filter-branch.xml index d47bae676..3b6b3a3b9 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-filter-branch.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-filter-branch.xml @@ -24,7 +24,7 @@ DESCRIPTION -Lets you rewrite git revision history by rewriting the branches mentioned +Lets you rewrite Git revision history by rewriting the branches mentioned in the <rev-list options>, applying custom filters on each revision. Those filters can modify each tree (e.g. removing a file or running a perl rewrite on all files) or information about each commit. @@ -34,7 +34,7 @@ information) will be preserved. command line (e.g. if you pass a..b, only b will be rewritten). If you specify no filters, the commits will be recommitted without any changes, which would normally have no effect. Nevertheless, this may be -useful in the future for compensating for some git bugs or such, +useful in the future for compensating for some Git bugs or such, therefore such a usage is permitted. NOTE: This command honors .git/info/grafts file and refs in the refs/replace/ namespace. @@ -62,9 +62,11 @@ argument is always evaluated in the shell context using the eval after the +filters have run. +If any evaluation of <command> returns a non-zero exit status, the whole operation will be aborted. A map function is available that takes an "original sha1 id" argument and outputs a "rewritten sha1 id" if the commit has been already @@ -366,6 +368,22 @@ of which is a merge), use this command: cat && echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>" ' HEAD~10..HEAD +The --env-filter option can be used to modify committer and/or author +identity. For example, if you found out that your commits have the wrong +identity due to a misconfigured user.email, you can make a correction, +before publishing the project, like this: +git filter-branch --env-filter ' + if test "$GIT_AUTHOR_EMAIL" = "root@localhost" + then + GIT_AUTHOR_EMAIL=john@example.com + export GIT_AUTHOR_EMAIL + fi + if test "$GIT_COMMITTER_EMAIL" = "root@localhost" + then + GIT_COMMITTER_EMAIL=john@example.com + export GIT_COMMITTER_EMAIL + fi +' -- --all To restrict rewriting to only part of the history, specify a revision range in addition to the new branch name. The new branch name will point to the top-most revision that a git rev-list of this range @@ -388,11 +406,11 @@ git filter-branch ... D..H --not C Checklist for Shrinking a Repository -git-filter-branch is often used to get rid of a subset of files, +git-filter-branch can be used to get rid of a subset of files, usually with some combination of --index-filter and --subdirectory-filter. People expect the resulting repository to be smaller than the original, but you need a few more steps to -actually make it smaller, because git tries hard not to lose your +actually make it smaller, because Git tries hard not to lose your objects until you tell it to. First make sure that: @@ -446,6 +464,47 @@ Garbage collect all unreferenced objects with git gc --prune=now + +Notes +git-filter-branch allows you to make complex shell-scripted rewrites +of your Git history, but you probably don't need this flexibility if +you're simply removing unwanted data like large files or passwords. +For those operations you may want to consider +http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner], +a JVM-based alternative to git-filter-branch, typically at least +10-50x faster for those use-cases, and with quite different +characteristics: + + + +Any particular version of a file is cleaned exactly once. The BFG, + unlike git-filter-branch, does not give you the opportunity to + handle a file differently based on where or when it was committed + within your history. This constraint gives the core performance + benefit of The BFG, and is well-suited to the task of cleansing bad + data - you don't care where the bad data is, you just want it + gone. + + + + +By default The BFG takes full advantage of multi-core machines, + cleansing commit file-trees in parallel. git-filter-branch cleans + commits sequentially (i.e. in a single-threaded manner), though it + is possible to write filters that include their own parallelism, + in the scripts executed against each commit. + + + + +The http://rtyley.github.io/bfg-repo-cleaner/#examples[command options] + are much more restrictive than git-filter branch, and dedicated just + to the tasks of removing unwanted data- e.g: + --strip-blobs-bigger-than 1M. + + + + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-fmt-merge-msg.xml b/doc/source/en/TortoiseGit/git_doc/git-fmt-merge-msg.xml index 28654fbd4..33fd2c55f 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-fmt-merge-msg.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-fmt-merge-msg.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git fmt-merge-msg [-m <message>] [--log[=<n>] | --no-log] <$GIT_DIR/FETCH_HEAD +git fmt-merge-msg [-m <message>] [--log[=<n>] | --no-log] git fmt-merge-msg [-m <message>] [--log[=<n>] | --no-log] -F <file>
@@ -55,10 +55,7 @@ automatically invoking git merge. ---summary - - ---no-summary +--[no-]summary @@ -138,6 +135,13 @@ merge.summary + +EXAMPLE +$ git fetch origin master +$ git fmt-merge-msg --log <$GIT_DIR/FETCH_HEAD +Print a log message describing a merge of the "master" branch from +the "origin" remote. + SEE ALSO diff --git a/doc/source/en/TortoiseGit/git_doc/git-for-each-ref.xml b/doc/source/en/TortoiseGit/git_doc/git-for-each-ref.xml index cacd5abe8..e6b76895c 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-for-each-ref.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-for-each-ref.xml @@ -14,7 +14,9 @@ SYNOPSIS
git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl] - [(--sort=<key>)…] [--format=<format>] [<pattern>…] + [(--sort=<key>)…] [--format=<format>] [<pattern>…] + [--points-at <object>] [(--merged | --no-merged) [<object>]] + [--contains [<object>]]
@@ -109,6 +111,49 @@ host language allowing their direct evaluation in that language. + + +--points-at <object> + + + + Only list refs which points at the given object. + + + + + +--merged [<object>] + + + + Only list refs whose tips are reachable from the + specified commit (HEAD if not specified). + + + + + +--no-merged [<object>] + + + + Only list refs whose tips are not reachable from the + specified commit (HEAD if not specified). + + + + + +--contains [<object>] + + + + Only list refs which contain the specified commit (HEAD if not + specified). + + + @@ -127,7 +172,11 @@ refname The name of the ref (the part after $GIT_DIR/). For a non-ambiguous short name of the ref append :short. The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. + abbreviation mode. If strip=<N> is appended, strips <N> + slash-separated path components from the front of the refname + (e.g., %(refname:strip=2) turns refs/tags/foo into foo. + <N> must be a positive integer. If a displayed ref has fewer + components than <N>, the command aborts with an error. @@ -170,7 +219,68 @@ upstream The name of a local ref which can be considered upstream from the displayed ref. Respects :short in the same way as - refname above. + refname above. Additionally respects :track to show + "[ahead N, behind M]" and :trackshort to show the terse + version: ">" (ahead), "<" (behind), "<>" (ahead and behind), + or "=" (in sync). Has no effect if the ref does not have + tracking information associated with it. + + + + + +push + + + + The name of a local ref which represents the @{push} location + for the displayed ref. Respects :short, :track, and + :trackshort options as upstream does. Produces an empty + string if no @{push} ref is configured. + + + + + +HEAD + + + + * if HEAD matches current ref (the checked out branch), ' ' + otherwise. + + + + + +color + + + + Change output color. Followed by :<colorname>, where names + are described in color.branch.*. + + + + + +align + + + + Left-, middle-, or right-align the content between + %(align:…) and %(end). The "align:" is followed by + width=<width> and position=<position> in any order + separated by a comma, where the <position> is either left, + right or middle, default being left and <width> is the total + length of the content with alignment. For brevity, the + "width=" and/or "position=" prefixes may be omitted, and bare + <width> and <position> used instead. For instance, + %(align:<width>,<position>). If the contents length is more + than the width then no alignment is performed. If used with + --quote everything in between %(align:…) and %(end) is + quoted, but if nested then only the topmost level performs + quoting. @@ -178,6 +288,10 @@ upstream In addition to the above, for commit and tag objects, the header field names (tree, parent, object, type, and tag) can be used to specify the value in the header field. +For commit and tag objects, the special creatordate and creator +fields will correspond to the appropriate date or name-email-date tuple +from the committer or tagger fields depending on the object type. +These are intended for working on a mix of annotated and lightweight tags. Fields that have name-email-date tuple as its value (author, committer, and tagger) can be suffixed with name, email, and date to extract the named component. @@ -185,17 +299,19 @@ and date to extract the named component. Its first line is contents:subject, where subject is the concatenation of all lines of the commit message up to the first blank line. The next line is contents:body, where body is all of the lines after the first -blank line. Finally, the optional GPG signature is contents:signature. -For sorting purposes, fields with numeric values sort in numeric -order (objectsize, authordate, committerdate, taggerdate). +blank line. The optional GPG signature is contents:signature. The +first N lines of the message is obtained using contents:lines=N. +For sorting purposes, fields with numeric values sort in numeric order +(objectsize, authordate, committerdate, creatordate, taggerdate). All other fields are used to sort in their byte-value order. +There is also an option to sort by versions, this can be done by using +the fieldname version:refname or its alias v:refname. In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error. It returns an empty string instead. As a special case for the date-type fields, you may specify a format for -the date by adding one of :default, :relative, :short, :local, -:iso8601 or :rfc2822 to the end of the fieldname; e.g. -%(taggerdate:relative). +the date by adding : followed by date format name (see the +values the --date option to takes). EXAMPLES @@ -271,13 +387,9 @@ eval=`git for-each-ref --shell --format="$fmt" \ refs/tags` eval "$eval" - -Author -Written by Junio C Hamano <gitster@pobox.com>. - - -Documentation -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +SEE ALSO + GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-format-patch.xml b/doc/source/en/TortoiseGit/git_doc/git-format-patch.xml index 0d07e5c7e..70165459a 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-format-patch.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-format-patch.xml @@ -18,13 +18,14 @@ [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] [--signature=<signature> | --no-signature] + [--signature-file=<file>] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] - [--subject-prefix=Subject-Prefix] + [--subject-prefix=Subject-Prefix] [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] - [--cover-letter] [--quiet] [--notes[=<ref>]] + [--[no-]cover-letter] [--quiet] [--notes[=<ref>]] [<common diff options>] [ <since> | <revision range> ] @@ -64,7 +65,11 @@ will only be numbers, without the first line of the commit appended. The names of the output files are printed to standard output, unless the --stdout option is specified. If -o is specified, output files are created in <dir>. Otherwise -they are created in the current working directory. +they are created in the current working directory. The default path +can be set with the format.outputDirectory configuration option. +The -o option takes precedence over format.outputDirectory. +To store patches in the current working directory even when +format.outputDirectory points elsewhere, use -o .. By default, the subject of a single patch is "[PATCH] " followed by the concatenation of lines from the commit message up to the first blank line (see the DISCUSSION section of ). @@ -139,6 +144,63 @@ reference. +--diff-algorithm={patience|minimal|histogram|myers} + + + + Choose a diff algorithm. The variants are as follows: + + + + +default, myers + + + + The basic greedy diff algorithm. Currently, this is the default. + + + + + +minimal + + + + Spend extra time to make sure the smallest possible diff is + produced. + + + + + +patience + + + + Use "patience diff" algorithm when generating patches. + + + + + +histogram + + + + This algorithm extends the patience algorithm to "support + low-occurrence common elements". + + + + +For instance, if you configured diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option. + + + + --stat[=<width>[,<name-width>[,<count>]]] @@ -354,7 +416,7 @@ few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for git to consider it a total +original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines). When used with -M, a totally-rewritten file is also considered as the @@ -378,13 +440,13 @@ another file. Detect renames. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the - file's size). For example, -M90% means git should consider a + file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use - -M100%. + -M100%. The default similarity index is 50%. @@ -429,7 +491,7 @@ another file. Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch - is not meant to be applied with patch nor git apply; this is + is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, @@ -461,6 +523,9 @@ of a delete/create pair. Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. + This overrides the diff.orderFile configuration variable + (see ). To cancel diff.orderFile, + use -O/dev/null. @@ -519,6 +584,16 @@ of a delete/create pair. +--ignore-blank-lines + + + + Ignore changes whose lines are all blank. + + + + + --inter-hunk-context=<lines> @@ -590,7 +665,7 @@ of a delete/create pair. Ignore changes to submodules in the diff generation. <when> can be - either "none", "untracked", "dirty" or "all", which is the default + either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the @@ -733,6 +808,7 @@ of a delete/create pair. Add Signed-off-by: line to the commit message, using the committer identity of yourself. + See the signoff option in for more information. @@ -850,6 +926,24 @@ will want to ensure that threading is disabled for git send-email +-v <n> + + +--reroll-count=<n> + + + + Mark the series as the <n>-th iteration of the topic. The + output filenames have v<n> prepended to them, and the + subject prefix ("PATCH" by default, but configurable via the + --subject-prefix option) has ` v<n>` appended to it. E.g. + --reroll-count=4 may produce v4-0001-add-makefile.patch + file that has "Subject: [PATCH v4 1/20] Add makefile" in it. + + + + + --to=<email> @@ -876,6 +970,29 @@ will want to ensure that threading is disabled for git send-email +--from + + +--from=<ident> + + + + Use ident in the From: header of each commit email. If the + author ident of the commit is not textually identical to the + provided ident, place a From: header in the body of the + message with the original author. If no ident is given, use + the committer ident. + +Note that this option is only useful if you are actually sending the +emails and want to identify yourself as the sender, but retain the +original author (and git am will correctly pick up the in-body +header). Note also that git send-email already handles this +transformation for you, and this option should not be used if you are +feeding the result to git send-email. + + + + --add-header=<header> @@ -891,12 +1008,12 @@ will want to ensure that threading is disabled for git send-email ---cover-letter +--[no-]cover-letter In addition to the patches, generate a cover letter file - containing the shortlog and the overall diffstat. You can + containing the branch description, shortlog and the overall diffstat. You can fill in a description in the file before sending it out. @@ -914,7 +1031,7 @@ will want to ensure that threading is disabled for git send-emailformat-patch has run but before sending, -keeping them as git notes allows them to be maintained between versions +keeping them as Git notes allows them to be maintained between versions of the patch series (but see the discussion of the notes.rewrite configuration options in to use this workflow). @@ -927,13 +1044,23 @@ configuration options in to use this workflow).< Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the - signature option is omitted the signature defaults to the git version + signature option is omitted the signature defaults to the Git version number. +--signature-file=<file> + + + + Works just like --signature except the signature is read from a file. + + + + + --suffix=.<sfx> @@ -949,6 +1076,9 @@ you can use --suffix=-patch to get 0001-descripti +-q + + --quiet @@ -972,6 +1102,17 @@ you can use --suffix=-patch to get 0001-descripti +--zero-commit + + + + Output an all-zero hash in each patch's From header instead + of the hash of the commit. + + + + + --root @@ -994,13 +1135,14 @@ outputting more than one patch, add "To" or "Cc:" headers, configure attachments, and sign off patches with configuration variables. [format] headers = "Organization: git-foo\n" - subjectprefix = CHANGE + subjectPrefix = CHANGE suffix = .txt numbered = auto to = <email> cc = <email> attach [ = mime-boundary-string ] - signoff = true + signOff = true + coverletter = auto DISCUSSION @@ -1142,7 +1284,7 @@ section of . Thunderbird By default, Thunderbird will both wrap emails as well as flag them as being format=flowed, both of which will make the -resulting email unusable by git. +resulting email unusable by Git. There are three different approaches: use an add-on to turn off line wraps, configure Thunderbird to not mangle patches, or use an external editor to keep Thunderbird from mangling the patches. @@ -1175,7 +1317,8 @@ Edit..Preferences..Composition, wrap plain text messages at 0 In Thunderbird 3: Edit..Preferences..Advanced..Config Editor. Search for "mail.wrap_long_lines". -Toggle it to make sure it is set to false. +Toggle it to make sure it is set to false. Also, search for +"mailnews.wraplength" and set the value to 0. @@ -1307,8 +1450,8 @@ The same as the previous one: Additionally, it detects and handles renames and complete rewrites intelligently to produce a renaming patch. A renaming patch reduces the amount of text output, and generally makes it easier to review. -Note that non-git "patch" programs won't understand renaming patches, so -use it only when you know the recipient uses git to apply your patch. +Note that non-Git "patch" programs won't understand renaming patches, so +use it only when you know the recipient uses Git to apply your patch. diff --git a/doc/source/en/TortoiseGit/git_doc/git-fsck.xml b/doc/source/en/TortoiseGit/git_doc/git-fsck.xml index fc6dff915..7b1493add 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-fsck.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-fsck.xml @@ -15,7 +15,7 @@
git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] - [--[no-]dangling] [--[no-]progress] [<object>*] + [--[no-]dangling] [--[no-]progress] [--connectivity-only] [<object>*]
@@ -34,7 +34,7 @@ An object to treat as the head of an unreachability trace. If no objects are given, git fsck defaults to using the -index file, all SHA1 references in refs namespace, and all reflogs +index file, all SHA-1 references in refs namespace, and all reflogs (unless --no-reflogs is given) as heads. @@ -51,10 +51,7 @@ index file, all SHA1 references in refs namespace, and all ---dangling - - ---no-dangling +--[no-]dangling @@ -117,7 +114,7 @@ index file, all SHA1 references in refs namespace, and all ($GIT_DIR/objects), but also the ones found in alternate object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES or $GIT_DIR/objects/info/alternates, - and in packed git archives found in $GIT_DIR/objects/pack + and in packed Git archives found in $GIT_DIR/objects/pack and corresponding pack subdirectories in alternate object pools. This is now default; you can turn it off with --no-full. @@ -126,14 +123,26 @@ index file, all SHA1 references in refs namespace, and all +--connectivity-only + + + + Check only the connectivity of tags, commits and tree objects. By + avoiding to unpack blobs, this speeds up the operation, at the + expense of missing corrupt objects or other problematic issues. + + + + + --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 + 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. @@ -164,10 +173,7 @@ index file, all SHA1 references in refs namespace, and all ---progress - - ---no-progress +--[no-]progress @@ -183,7 +189,7 @@ index file, all SHA1 references in refs namespace, and all DISCUSSION -git-fsck tests SHA1 and general object sanity, and it does full tracking +git-fsck tests SHA-1 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 diff --git a/doc/source/en/TortoiseGit/git_doc/git-gc.xml b/doc/source/en/TortoiseGit/git_doc/git-gc.xml index 79ddf8dbd..6159dca78 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-gc.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-gc.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git gc [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] +git gc [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force]
@@ -65,10 +65,10 @@ exceeds the value of the gc.auto configuration variable, th all loose objects are combined into a single pack using git repack -d -l. Setting the value of gc.auto to 0 disables automatic packing of loose objects. -If the number of packs exceeds the value of gc.autopacklimit, +If the number of packs exceeds the value of gc.autoPackLimit, then existing packs (except those marked with a .keep file) are consolidated into a single pack by using the -A option of -git repack. Setting gc.autopacklimit to 0 disables +git repack. Setting gc.autoPackLimit to 0 disables automatic consolidation of packs. @@ -79,8 +79,12 @@ automatic consolidation of packs. Prune loose objects older than date (default is 2 weeks ago, - overridable by the config variable gc.pruneExpire). This - option is on by default. + overridable by the config variable gc.pruneExpire). + --prune=all prunes loose objects regardless of their age (do + not use --prune=all unless you know exactly what you are doing. + Unless the repository is quiescent, you will lose newly created + objects that haven't been anchored with the refs and end up + corrupting your repository). --prune is on by default. @@ -104,6 +108,17 @@ automatic consolidation of packs. + + +--force + + + + Force git gc to run even if there may be another git gc + instance running on this repository. + + + @@ -126,14 +141,14 @@ example, this sets non-default expiry values only to remote-tracking branches: [gc "refs/remotes/*"] reflogExpire = never - reflogexpireUnreachable = 3 days -The optional configuration variable gc.rerereresolved indicates + reflogExpireUnreachable = 3 days +The optional configuration variable gc.rerereResolved indicates how long records of conflicted merge you resolved earlier are kept. This defaults to 60 days. -The optional configuration variable gc.rerereunresolved indicates +The optional configuration variable gc.rerereUnresolved indicates how long records of conflicted merge you have not resolved are kept. This defaults to 15 days. -The optional configuration variable gc.packrefs determines if +The optional configuration variable gc.packRefs determines if git gc runs git pack-refs. This can be set to "notbare" to enable it within all non-bare repos or it can be set to a boolean value. This defaults to true. @@ -143,6 +158,8 @@ the repository when the --aggressive option is specified. The larger the value, the more time is spent optimizing the delta compression. See the documentation for the --window' option in for more details. This defaults to 250. +Similarly, the optional configuration variable gc.aggressiveDepth +controls --depth option in . This defaults to 250. The optional configuration variable gc.pruneExpire controls how old the unreferenced loose objects have to be before they are pruned. The default is "2 weeks ago". diff --git a/doc/source/en/TortoiseGit/git_doc/git-get-tar-commit-id.xml b/doc/source/en/TortoiseGit/git_doc/git-get-tar-commit-id.xml index 7afd9db49..85401689d 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-get-tar-commit-id.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-get-tar-commit-id.xml @@ -13,16 +13,17 @@ SYNOPSIS
-git get-tar-commit-id < <tarfile> +git get-tar-commit-id
DESCRIPTION -Acts as a filter, extracting the commit ID stored in archives created by -git archive. It reads only the first 1024 bytes of input, thus its -runtime is not influenced by the size of <tarfile> very much. +Read a tar archive created by git archive from the standard input +and extract the commit ID stored in it. It reads only the first +1024 bytes of input, thus its runtime is not influenced by the size +of the tar archive 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 +return code of 1. This can happen if the archive had not been created using git archive or if the first parameter of git archive had been a tree ID instead of a commit ID or tag. diff --git a/doc/source/en/TortoiseGit/git_doc/git-grep.xml b/doc/source/en/TortoiseGit/git_doc/git-grep.xml index 54bbd678c..8e0b6f816 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-grep.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-grep.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git grep [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp] +git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp] [-v | --invert-match] [-h|-H] [--full-name] [-E | --extended-regexp] [-G | --basic-regexp] [-P | --perl-regexp] @@ -27,9 +27,10 @@ [--break] [--heading] [-p | --show-function] [-A <post-context>] [-B <pre-context>] [-C <context>] [-W | --function-context] + [--threads <num>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>…] - [ [--exclude-standard] [--cached | --no-index | --untracked] | <tree>…] + [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>…] [--] [<pathspec>…]
@@ -78,6 +79,38 @@ grep.extendedRegexp + + +grep.threads + + + + Number of grep worker threads to use. If unset (or set to 0), + 8 threads are used by default (for now). + + + + + +grep.fullName + + + + If set to true, enable --full-name option by default. + + + + + +grep.fallbackToNoIndex + + + + If set to true, fall back to git grep --no-index if git grep + is executed outside of a git repository. Defaults to false. + + + @@ -100,7 +133,7 @@ grep.extendedRegexp - Search files in the current directory that is not managed by git. + Search files in the current directory that is not managed by Git. @@ -153,6 +186,27 @@ grep.extendedRegexp +--textconv + + + + Honor textconv filter settings. + + + + + +--no-textconv + + + + Do not honor textconv filter settings. + This is the default. + + + + + -i @@ -335,17 +389,20 @@ grep.extendedRegexp --O [<pager>] +-O[<pager>] ---open-files-in-pager [<pager>] +--open-files-in-pager[=<pager>] Open the matching files in the pager (not the output of grep). If the pager happens to be "less" or "vi", and the user specified only one pattern, the first file is positioned at - the first match automatically. + the first match automatically. The pager argument is + optional; if specified, it must be stuck to the option + without a space. If pager is unspecified, the default pager + will be used (see core.pager in ). @@ -501,6 +558,17 @@ grep.extendedRegexp +--threads <num> + + + + Number of grep worker threads to use. + See grep.threads in CONFIGURATION for more information. + + + + + -f <file> diff --git a/doc/source/en/TortoiseGit/git_doc/git-gui.xml b/doc/source/en/TortoiseGit/git_doc/git-gui.xml index 2ecaeb3c4..0e641accb 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-gui.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-gui.xml @@ -193,7 +193,7 @@ version - The git repository browser. Shows branches, commit history + The Git repository browser. Shows branches, commit history and file differences. gitk is the utility started by git gui's Repository Visualize actions. diff --git a/doc/source/en/TortoiseGit/git_doc/git-hash-object.xml b/doc/source/en/TortoiseGit/git_doc/git-hash-object.xml index 750616497..8ffe5e913 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-hash-object.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-hash-object.xml @@ -13,8 +13,8 @@ SYNOPSIS
-git hash-object [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>… -git hash-object [-t <type>] [-w] --stdin-paths [--no-filters] < <list-of-paths> +git hash-object [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>… +git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]
@@ -66,7 +66,8 @@ specified, it defaults to "blob". - Read file names from stdin instead of from the command-line. + Read file names from the standard input, one per line, instead + of from the command-line. @@ -78,7 +79,7 @@ specified, it defaults to "blob". Hash object as it were located at the given path. The location of file does not directly influence on the hash value, but path is - used to determine what git filters should be applied to the object + used to determine what Git filters should be applied to the object before it can be placed to the object database, and, as result of applying filters, the actual blob put into the object database may differ from the given file. This option is mainly useful for hashing @@ -96,7 +97,20 @@ specified, it defaults to "blob". Hash the contents as is, ignoring any input filter that would have been chosen by the attributes mechanism, including the end-of-line conversion. If the file is read from standard input then this - is always implied, unless the --path option is given. + is always implied, unless the --path option is given. + + + + + +--literally + + + + Allow --stdin to hash any garbage into a loose object which might not + otherwise pass standard object parsing or git-fsck checks. Useful for + stress-testing Git itself or reproducing characteristics of corrupt or + bogus objects encountered in the wild. diff --git a/doc/source/en/TortoiseGit/git_doc/git-help.xml b/doc/source/en/TortoiseGit/git_doc/git-help.xml index a670f3683..fe736bf9e 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-help.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-help.xml @@ -8,26 +8,32 @@ NAME -git-help - display help information about git +git-help - Display help information about Git SYNOPSIS
-git help [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND] +git help [-a|--all] [-g|--guide] + [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]
DESCRIPTION -With no options and no COMMAND given, the synopsis of the git -command and a list of the most commonly used git commands are printed +With no options and no COMMAND or GUIDE given, the synopsis of the git +command and a list of the most commonly used Git commands are printed on the standard output. -If the option --all or -a is given, then all available commands are +If the option --all or -a is given, all available commands are printed on the standard output. -If a git command is named, a manual page for that command is brought -up. The man program is used by default for this purpose, but this -can be overridden by other options or configuration variables. +If the option --guide or -g is given, a list of the useful +Git guides is also printed on the standard output. +If a command, or a guide, is given, a manual page for that command or +guide is brought up. The man program is used by default for this +purpose, but this can be overridden by other options or configuration +variables. Note that git --help ... is identical to git help ... because the former is internally converted into the latter. +To display the man page, use git help git. +This page can be displayed with git help help or git help --help OPTIONS @@ -42,7 +48,21 @@ former is internally converted into the latter. Prints all the available commands on the standard output. This - option supersedes any other option. + option overrides any given command or guide name. + + + + + +-g + + +--guides + + + + Prints a list of useful guides on the standard output. This + option overrides any given command or guide name. @@ -103,9 +123,9 @@ these config variables is set, the git web--browse CONFIGURATION VARIABLES
help.format -If no command line option is passed, the help.format configuration +If no command-line option is passed, the help.format configuration variable will be checked. The following values are supported for this -variable; they make git help behave as their corresponding command +variable; they make git help behave as their corresponding command- line option: @@ -128,14 +148,14 @@ line option:
help.browser, web.browser and browser.<tool>.path The help.browser, web.browser and browser.<tool>.path will also -be checked if the web format is chosen (either by command line +be checked if the web format is chosen (either by command-line option or configuration variable). See -w|--web in the OPTIONS section above and .
man.viewer -The man.viewer config variable will be checked if the man format -is chosen. The following values are currently supported: +The man.viewer configuration variable will be checked if the man +format is chosen. The following values are currently supported: @@ -164,7 +184,7 @@ listed in the configuration file. [man] viewer = konqueror viewer = woman -will try to use konqueror first. But this may fail (for example if +will try to use konqueror first. But this may fail (for example, if DISPLAY is not set) and in that case emacs' woman mode will be tried. If everything fails, or if no viewer is configured, the viewer specified in the GIT_MAN_VIEWER environment variable will be tried. If that diff --git a/doc/source/en/TortoiseGit/git_doc/git-http-backend.xml b/doc/source/en/TortoiseGit/git_doc/git-http-backend.xml index 66fdd8bbf..060f03fe0 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-http-backend.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-http-backend.xml @@ -24,7 +24,7 @@ The program supports clients fetching using both the smart HTTP protocol and the backwards-compatible dumb HTTP protocol, as well as clients pushing using the smart HTTP protocol. It verifies that the directory has the magic file -"git-daemon-export-ok", and it will refuse to export any git directory +"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 GIT_HTTP_EXPORT_ALL environmental variable is set). By default, only the upload-pack service is enabled, which serves @@ -109,13 +109,40 @@ Apache 2.x SetEnv GIT_HTTP_EXPORT_ALL ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ To enable anonymous read access but authenticated write access, -require authorization with a LocationMatch directive: +require authorization for both the initial ref advertisement (which we +detect as a push via the service parameter in the query string), and the +receive-pack invocation itself: +RewriteCond %{QUERY_STRING} service=git-receive-pack [OR] +RewriteCond %{REQUEST_URI} /git-receive-pack$ +RewriteRule ^/git/ - [E=AUTHREQUIRED:yes] + +<LocationMatch "^/git/"> + Order Deny,Allow + Deny from env=AUTHREQUIRED + + AuthType Basic + AuthName "Git Access" + Require group committers + Satisfy Any + ... +</LocationMatch> +If you do not have mod_rewrite available to match against the query +string, it is sufficient to just protect git-receive-pack itself, +like: <LocationMatch "^/git/.*/git-receive-pack$"> AuthType Basic AuthName "Git Access" Require group committers ... </LocationMatch> +In this mode, the server will not request authentication until the +client actually starts the object negotiation phase of the push, rather +than during the initial contact. For this reason, you must also enable +the http.receivepack config option in any repositories that should +accept a push. The default behavior, if http.receivepack is not set, +is to reject any pushes by unauthenticated users; the initial request +will therefore report 403 Forbidden to the client, without even giving +an opportunity for authentication. To require authentication for both reads and writes, use a Location directive around the repository, or one of its parent directories: <Location /git/private> @@ -173,6 +200,46 @@ ScriptAliasMatch \ ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ + + +Lighttpd + + + + Ensure that mod_cgi, mod_alias, mod_auth, mod_setenv are + loaded, then set GIT_PROJECT_ROOT appropriately and redirect + all requests to the CGI: + +alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" ) +$HTTP["url"] =~ "^/git" { + cgi.assign = ("" => "") + setenv.add-environment = ( + "GIT_PROJECT_ROOT" => "/var/www/git", + "GIT_HTTP_EXPORT_ALL" => "" + ) +} +To enable anonymous read access but authenticated write access: +$HTTP["querystring"] =~ "service=git-receive-pack" { + include "git-auth.conf" +} +$HTTP["url"] =~ "^/git/.*/git-receive-pack$" { + include "git-auth.conf" +} +where git-auth.conf looks something like: +auth.require = ( + "/" => ( + "method" => "basic", + "realm" => "Git Access", + "require" => "valid-user" + ) +) +# ...and set up auth.backend here +To require authentication for both reads and writes: +$HTTP["url"] =~ "^/git/private" { + include "git-auth.conf" +} + + @@ -214,6 +281,14 @@ REQUEST_METHOD The GIT_HTTP_EXPORT_ALL environmental variable may be passed to git-http-backend to bypass the check for the "git-daemon-export-ok" file in each repository before allowing export of that repository. +The GIT_HTTP_MAX_REQUEST_BUFFER environment variable (or the +http.maxRequestBuffer config variable) may be set to change the +largest ref negotiation request that git will handle during a fetch; any +fetch requiring a larger buffer will not succeed. This value should not +normally need to be changed, but may be helpful if you are fetching from +a repository with an extremely large number of refs. The value can be +specified with a unit (e.g., 100M for 100 megabytes). The default is +10 megabytes. The backend process sets GIT_COMMITTER_NAME to $REMOTE_USER and GIT_COMMITTER_EMAIL to ${REMOTE_USER}@http.${REMOTE_ADDR}, ensuring that any reflogs created by git-receive-pack contain some @@ -221,14 +296,6 @@ identifying information of the remote user who performed the push. All CGI environment variables are available to each of the hooks invoked by the git-receive-pack. - -Author -Written by Shawn O. Pearce <spearce@spearce.org>. - - -Documentation -Documentation by Shawn O. Pearce <spearce@spearce.org>. - GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-http-fetch.xml b/doc/source/en/TortoiseGit/git_doc/git-http-fetch.xml index 68d2ad94f..f0b9605a4 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-http-fetch.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-http-fetch.xml @@ -8,7 +8,7 @@ NAME -git-http-fetch - Download from a remote git repository via HTTP +git-http-fetch - Download from a remote Git repository via HTTP SYNOPSIS @@ -18,7 +18,7 @@ DESCRIPTION -Downloads a remote git repository via HTTP. +Downloads a remote Git repository via HTTP. NOTE: use of this command without -a is deprecated. The -a behaviour will become the default in a future release. diff --git a/doc/source/en/TortoiseGit/git_doc/git-imap-send.xml b/doc/source/en/TortoiseGit/git_doc/git-imap-send.xml index bb89f0d16..44fb80f37 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-imap-send.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-imap-send.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git imap-send +git imap-send [-v] [-q] [--[no-]curl]
@@ -27,6 +27,61 @@ that order. Typical usage is something like: git format-patch --signoff --stdout --attach origin | git imap-send + +OPTIONS + + + +-v + + +--verbose + + + + Be verbose. + + + + + +-q + + +--quiet + + + + Be quiet. + + + + + +--curl + + + + Use libcurl to communicate with the IMAP server, unless tunneling + into it. Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND + option set. + + + + + +--no-curl + + + + Talk to the IMAP server using git's own IMAP routines instead of + using libcurl. Ignored if Git was built with the NO_OPENSSL option + set. + + + + + CONFIGURATION To use the tool, imap.folder and either imap.tunnel or imap.host must be set @@ -42,7 +97,7 @@ imap.folder The folder to drop the mails into, which is typically the Drafts folder. For example: "INBOX.Drafts", "INBOX/Drafts" or - "[Gmail]/Drafts". Required to use imap-send. + "[Gmail]/Drafts". Required. @@ -54,7 +109,7 @@ imap.tunnel Command used to setup a tunnel to the IMAP server through which commands will be piped instead of using a direct network connection - to the server. Required when imap.host is not set to use imap-send. + to the server. Required when imap.host is not set. @@ -66,8 +121,7 @@ imap.host A URL identifying the server. Use a imap:// prefix for non-secure connections and a imaps:// prefix for secure connections. - Ignored when imap.tunnel is set, but required to use imap-send - otherwise. + Ignored when imap.tunnel is set, but required otherwise. @@ -136,7 +190,10 @@ imap.authMethod Specify authenticate method for authentication with IMAP server. - Current supported method is CRAM-MD5 only. + If Git was built with the NO_CURL option, or if your curl version is older + than 7.34.0, or if you're running git-imap-send with the --no-curl + option, the only supported method is CRAM-MD5. If this is not set + then git imap-send uses the basic IMAP plaintext LOGIN command. diff --git a/doc/source/en/TortoiseGit/git_doc/git-index-pack.xml b/doc/source/en/TortoiseGit/git_doc/git-index-pack.xml index 13c3318e4..f7dbb6e82 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-index-pack.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-index-pack.xml @@ -23,7 +23,7 @@ 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. +objects/pack/ directory of a Git repository. OPTIONS @@ -62,7 +62,7 @@ objects/pack/ directory of a git repository. When this flag is provided, the pack is read from stdin instead and a copy is then written to <pack-file>. If <pack-file> is not specified, the pack is written to - objects/pack/ directory of the current git repository with + objects/pack/ directory of the current Git repository with a default name determined from the pack content. If <pack-file> is not specified consider using --keep to prevent a race condition between this process and @@ -136,6 +136,16 @@ objects/pack/ directory of a git repository. +--check-self-contained-and-connected + + + + Die if the pack contains broken links. For internal use only. + + + + + --threads=<n> @@ -146,7 +156,7 @@ objects/pack/ directory of a git repository. This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. - Specifying 0 will cause git to auto-detect the number of CPU's + Specifying 0 will cause Git to auto-detect the number of CPU's and use maximum 3 threads. @@ -156,7 +166,7 @@ objects/pack/ directory of a git repository. Note Once the index has been created, the list of object names is sorted -and the SHA1 hash of that list is printed to stdout. If --stdin was +and the SHA-1 hash of that list is printed to stdout. If --stdin was also used then this is prefixed by either "pack\t", or "keep\t" if a new .keep file was successfully created. This is useful to remove a .keep file used as a lock to prevent the race with git repack diff --git a/doc/source/en/TortoiseGit/git_doc/git-init-db.xml b/doc/source/en/TortoiseGit/git_doc/git-init-db.xml index 70b92bdde..05610457e 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-init-db.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-init-db.xml @@ -8,7 +8,7 @@ NAME -git-init-db - Creates an empty git repository +git-init-db - Creates an empty Git repository SYNOPSIS diff --git a/doc/source/en/TortoiseGit/git_doc/git-init.xml b/doc/source/en/TortoiseGit/git_doc/git-init.xml index 138a3c279..2a354138f 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-init.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-init.xml @@ -8,7 +8,7 @@ NAME -git-init - Create an empty git repository or reinitialize an existing one +git-init - Create an empty Git repository or reinitialize an existing one SYNOPSIS @@ -20,7 +20,7 @@ DESCRIPTION -This command creates an empty git repository - basically a .git +This command creates an empty Git repository - basically a .git directory with subdirectories for objects, refs/heads, refs/tags, and template files. An initial HEAD file that references the HEAD of the master branch is also created. @@ -47,7 +47,7 @@ the repository to another place if --separate-git-dir is given). -Only print error and warning messages, all other output will be suppressed. +Only print error and warning messages; all other output will be suppressed. @@ -79,13 +79,12 @@ DIRECTORY" section below.) -Instead of initializing the repository where it is supposed to be, -place a filesytem-agnostic git symbolic link there, pointing to the -specified git path, and initialize a git repository at the path. The -result is git repository can be separated from working tree. If this -is reinitialization, the repository will be moved to the specified -path. +Instead of initializing the repository as a directory to either $GIT_DIR or +./.git/, create a text file there containing the path to the actual +repository. This file acts as filesystem-agnostic Git symbolic link to the +repository. +If this is reinitialization, the repository will be moved to the specified path. @@ -94,110 +93,132 @@ path. -Specify that the git repository is to be shared amongst several users. This +Specify that the Git repository is to be shared amongst several users. This allows users belonging to the same group to push into that repository. When specified, the config variable "core.sharedRepository" is set so that files and directories under $GIT_DIR are created with the -requested permissions. When not specified, git will use permissions reported +requested permissions. When not specified, Git will use permissions reported by umask(2). - - - The option can have the following values, defaulting to group if no value is given: - + + + +umask (or false) + -umask (or false): Use permissions reported by umask(2). The default, - when --shared is not specified. +Use permissions reported by umask(2). The default, when --shared is not +specified. + + + +group (or true) + -group (or true): Make the repository group-writable, (and g+sx, since - the git group may be not the primary group of all users). - This is used to loosen the permissions of an otherwise safe umask(2) value. - Note that the umask still applies to the other permission bits (e.g. if - umask is 0022, using group will not remove read privileges from other - (non-group) users). See 0xxx for how to exactly specify the repository - permissions. +Make the repository group-writable, (and g+sx, since the git group may be not +the primary group of all users). This is used to loosen the permissions of an +otherwise safe umask(2) value. Note that the umask still applies to the other +permission bits (e.g. if umask is 0022, using group will not remove read +privileges from other (non-group) users). See 0xxx for how to exactly specify +the repository permissions. + + + +all (or world or everybody) + -all (or world or everybody): Same as group, but make the repository - readable by all users. +Same as group, but make the repository readable by all users. + + + +0xxx + -0xxx: 0xxx is an octal number and each file will have mode 0xxx. - 0xxx will override users' umask(2) value (and not only loosen permissions - as group and all does). 0640 will create a repository which is - group-readable, but not group-writable or accessible to others. 0660 will - create a repo that is readable and writable to the current user and group, - but inaccessible to others. +0xxx is an octal number and each file will have mode 0xxx. 0xxx will +override users' umask(2) value (and not only loosen permissions as group and +all does). 0640 will create a repository which is group-readable, but not +group-writable or accessible to others. 0660 will create a repo that is +readable and writable to the current user and group, but inaccessible to others. - -By default, the configuration flag receive.denyNonFastForwards is enabled + + + + + +By default, the configuration flag receive.denyNonFastForwards is enabled in shared repositories, so that you cannot force a non fast-forwarding push into it. -If you name a (possibly non-existent) directory at the end of the command -line, the command is run inside the directory (possibly after creating it). +If you provide a directory, the command is run inside it. If this directory +does not exist, it will be created. TEMPLATE DIRECTORY The template directory contains files and directories that will be copied to the $GIT_DIR after it is created. -The template directory used will (in order): +The template directory will be one of the following (in order): -The argument given with the --template option. +the argument given with the --template option; -The contents of the $GIT_TEMPLATE_DIR environment variable. +the contents of the $GIT_TEMPLATE_DIR environment variable; -The init.templatedir configuration variable. +the init.templateDir configuration variable; or -The default template directory: /usr/share/git-core/templates. +the default template directory: /usr/share/git-core/templates. -The default template directory includes some directory structure, some -suggested "exclude patterns", and copies of sample "hook" files. -The suggested patterns and hook files are all modifiable and extensible. +The default template directory includes some directory structure, suggested +"exclude patterns" (see ), and sample hook files (see ). EXAMPLES -Start a new git repository for an existing code base +Start a new Git repository for an existing code base $ cd /path/to/my/codebase $ git init -$ git add . +$ git add . +$ git commit -prepare /path/to/my/codebase/.git directory +Create a /path/to/my/codebase/.git directory. -add all existing file to the index +Add all existing files to the index. + + + + +Record the pristine state as the first commit in the history. diff --git a/doc/source/en/TortoiseGit/git_doc/git-instaweb.xml b/doc/source/en/TortoiseGit/git_doc/git-instaweb.xml index 8a3f6b35a..6b012dc06 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-instaweb.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-instaweb.xml @@ -153,7 +153,7 @@ restart httpd = apache2 -f port = 4321 browser = konqueror - modulepath = /usr/lib/apache2/modules + modulePath = /usr/lib/apache2/modules If the configuration variable instaweb.browser is not set, web.browser will be used instead if it is defined. See for more information about this. diff --git a/doc/source/en/TortoiseGit/git_doc/git-interpret-trailers.xml b/doc/source/en/TortoiseGit/git_doc/git-interpret-trailers.xml new file mode 100644 index 000000000..ea1c5e70b --- /dev/null +++ b/doc/source/en/TortoiseGit/git_doc/git-interpret-trailers.xml @@ -0,0 +1,404 @@ + + + + + git-interpret-trailers(1) + +git-interpret-trailers(1) + + +NAME +git-interpret-trailers - help add structured information into commit messages + + +SYNOPSIS +
+git interpret-trailers [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])…] [<file>…] +
+ + +DESCRIPTION +Help adding trailers lines, that look similar to RFC 822 e-mail +headers, at the end of the otherwise free-form part of a commit +message. +This command reads some patches or commit messages from either the +<file> arguments or the standard input if no <file> is specified. Then +this command applies the arguments passed using the --trailer +option, if any, to the commit message part of each input file. The +result is emitted on the standard output. +Some configuration variables control the way the --trailer arguments +are applied to each commit message and the way any existing trailer in +the commit message is changed. They also make it possible to +automatically add some trailers. +By default, a <token>=<value> or <token>:<value> argument given +using --trailer will be appended after the existing trailers only if +the last trailer has a different (<token>, <value>) pair (or if there +is no existing trailer). The <token> and <value> parts will be trimmed +to remove starting and trailing whitespace, and the resulting trimmed +<token> and <value> will appear in the message like this: +token: value +This means that the trimmed <token> and <value> will be separated by +': ' (one colon followed by one space). +By default the new trailer will appear at the end of all the existing +trailers. If there is no existing trailer, the new trailer will appear +after the commit message part of the output, and, if there is no line +with only spaces at the end of the commit message part, one blank line +will be added before the new trailer. +Existing trailers are extracted from the input message by looking for +a group of one or more lines that contain a colon (by default), where +the group is preceded by one or more empty (or whitespace-only) lines. +The group must either be at the end of the message or be the last +non-whitespace lines before a line that starts with ---. Such three +minus signs start the patch part of the message. +When reading trailers, there can be whitespaces before and after the +token, the separator and the value. There can also be whitespaces +inside the token and the value. +Note that trailers do not follow and are not intended to follow many +rules for RFC 822 headers. For example they do not follow the line +folding rules, the encoding rules and probably many other rules. + + +OPTIONS + + + +--in-place + + + + Edit the files in place. + + + + + +--trim-empty + + + + If the <value> part of any trailer contains only whitespace, + the whole trailer will be removed from the resulting message. + This applies to existing trailers as well as new trailers. + + + + + +--trailer <token>[(=|:)<value>] + + + + Specify a (<token>, <value>) pair that should be applied as a + trailer to the input messages. See the description of this + command. + + + + + + +CONFIGURATION VARIABLES + + + +trailer.separators + + + + This option tells which characters are recognized as trailer + separators. By default only : is recognized as a trailer + separator, except that = is always accepted on the command + line for compatibility with other git commands. + +The first character given by this option will be the default character +used when another separator is not specified in the config for this +trailer. +For example, if the value for this option is "%=$", then only lines +using the format <token><sep><value> with <sep> containing %, = +or $ and then spaces will be considered trailers. And % will be +the default separator used, so by default trailers will appear like: +<token>% <value> (one percent sign and one space will appear between +the token and the value). + + + + +trailer.where + + + + This option tells where a new trailer will be added. + +This can be end, which is the default, start, after or before. +If it is end, then each new trailer will appear at the end of the +existing trailers. +If it is start, then each new trailer will appear at the start, +instead of the end, of the existing trailers. +If it is after, then each new trailer will appear just after the +last trailer with the same <token>. +If it is before, then each new trailer will appear just before the +first trailer with the same <token>. + + + + +trailer.ifexists + + + + This option makes it possible to choose what action will be + performed when there is already at least one trailer with the + same <token> in the message. + +The valid values for this option are: addIfDifferentNeighbor (this +is the default), addIfDifferent, add, overwrite or doNothing. +With addIfDifferentNeighbor, a new trailer will be added only if no +trailer with the same (<token>, <value>) pair is above or below the line +where the new trailer will be added. +With addIfDifferent, a new trailer will be added only if no trailer +with the same (<token>, <value>) pair is already in the message. +With add, a new trailer will be added, even if some trailers with +the same (<token>, <value>) pair are already in the message. +With replace, an existing trailer with the same <token> will be +deleted and the new trailer will be added. The deleted trailer will be +the closest one (with the same <token>) to the place where the new one +will be added. +With doNothing, nothing will be done; that is no new trailer will be +added if there is already one with the same <token> in the message. + + + + +trailer.ifmissing + + + + This option makes it possible to choose what action will be + performed when there is not yet any trailer with the same + <token> in the message. + +The valid values for this option are: add (this is the default) and +doNothing. +With add, a new trailer will be added. +With doNothing, nothing will be done. + + + + +trailer.<token>.key + + + + This key will be used instead of <token> in the trailer. At + the end of this key, a separator can appear and then some + space characters. By default the only valid separator is :, + but this can be changed using the trailer.separators config + variable. + +If there is a separator, then the key will be used instead of both the +<token> and the default separator when adding the trailer. + + + + +trailer.<token>.where + + + + This option takes the same values as the trailer.where + configuration variable and it overrides what is specified by + that option for trailers with the specified <token>. + + + + + +trailer.<token>.ifexist + + + + This option takes the same values as the trailer.ifexist + configuration variable and it overrides what is specified by + that option for trailers with the specified <token>. + + + + + +trailer.<token>.ifmissing + + + + This option takes the same values as the trailer.ifmissing + configuration variable and it overrides what is specified by + that option for trailers with the specified <token>. + + + + + +trailer.<token>.command + + + + This option can be used to specify a shell command that will + be called to automatically add or modify a trailer with the + specified <token>. + +When this option is specified, the behavior is as if a special +<token>=<value> argument were added at the beginning of the command +line, where <value> is taken to be the standard output of the +specified command with any leading and trailing whitespace trimmed +off. +If the command contains the $ARG string, this string will be +replaced with the <value> part of an existing trailer with the same +<token>, if any, before the command is launched. +If some <token>=<value> arguments are also passed on the command +line, when a trailer.<token>.command is configured, the command will +also be executed for each of these arguments. And the <value> part of +these arguments, if any, will be used to replace the $ARG string in +the command. + + + + + +EXAMPLES + + + +Configure a sign trailer with a Signed-off-by key, and then + add two of these trailers to a message: + +$ git config trailer.sign.key "Signed-off-by" +$ cat msg.txt +subject + +message +$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' +subject + +message + +Signed-off-by: Alice <alice@example.com> +Signed-off-by: Bob <bob@example.com> + + + +Use the --in-place option to edit a message file in place: + +$ cat msg.txt +subject + +message + +Signed-off-by: Bob <bob@example.com> +$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt +$ cat msg.txt +subject + +message + +Signed-off-by: Bob <bob@example.com> +Acked-by: Alice <alice@example.com> + + + +Extract the last commit as a patch, and add a Cc and a + Reviewed-by trailer to it: + +$ git format-patch -1 +0001-foo.patch +$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch + + + +Configure a sign trailer with a command to automatically add a + 'Signed-off-by: ' with the author information only if there is no + 'Signed-off-by: ' already, and show how it works: + +$ git config trailer.sign.key "Signed-off-by: " +$ git config trailer.sign.ifmissing add +$ git config trailer.sign.ifexists doNothing +$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"' +$ git interpret-trailers <<EOF +> EOF + +Signed-off-by: Bob <bob@example.com> +$ git interpret-trailers <<EOF +> Signed-off-by: Alice <alice@example.com> +> EOF + +Signed-off-by: Alice <alice@example.com> + + + +Configure a fix trailer with a key that contains a # and no + space after this character, and show how it works: + +$ git config trailer.separators ":#" +$ git config trailer.fix.key "Fix #" +$ echo "subject" | git interpret-trailers --trailer fix=42 +subject + +Fix #42 + + + +Configure a see trailer with a command to show the subject of a + commit that is related, and show how it works: + +$ git config trailer.see.key "See-also: " +$ git config trailer.see.ifExists "replace" +$ git config trailer.see.ifMissing "doNothing" +$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG" +$ git interpret-trailers <<EOF +> subject +> +> message +> +> see: HEAD~2 +> EOF +subject + +message + +See-also: fe3187489d69c4 (subject of related commit) + + + +Configure a commit template with some trailers with empty values + (using sed to show and keep the trailing spaces at the end of the + trailers), then configure a commit-msg hook that uses + git interpret-trailers to remove trailers with empty values and + to add a git-version trailer: + +$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF +> ***subject*** +> +> ***message*** +> +> Fixes: Z +> Cc: Z +> Reviewed-by: Z +> Signed-off-by: Z +> EOF +$ git config commit.template commit_template.txt +$ cat >.git/hooks/commit-msg <<EOF +> #!/bin/sh +> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" +> mv "\$1.new" "\$1" +> EOF +$ chmod +x .git/hooks/commit-msg + + + + +SEE ALSO +, , + + +GIT +Part of the suite + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-log.xml b/doc/source/en/TortoiseGit/git_doc/git-log.xml index 154a90afa..a4b4d1d77 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-log.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-log.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git log [<options>] [<since>..<until>] [[--] <path>…] +git log [<options>] [<revision range>] [[--] <path>…]
@@ -29,20 +29,6 @@ each commit introduces are shown. -<since>..<until> - - - - Show only commits between the named two commits. When - either <since> or <until> is omitted, it defaults to - HEAD, i.e. the tip of the current branch. - For a more complete list of ways to spell <since> - and <until>, see . - - - - - --follow @@ -82,18 +68,30 @@ each commit introduces are shown. +--use-mailmap + + + + Use mailmap file to map author and committer names and email + addresses to canonical real names and email addresses. See + . + + + + + --full-diff - Without this flag, "git log -p <path>…" shows commits that + Without this flag, git log -p <path>... shows commits that touch the specified paths, and diffs about the same specified paths. With this, the full diff is shown for commits that touch the specified paths; this means that "<path>…" limits only commits, and doesn't limit diff for those commits. Note that this affects all diff-based output types, e.g. those -produced by --stat etc. +produced by --stat, etc. @@ -102,11 +100,78 @@ produced by --stat etc. - Before the log message print out its size in bytes. Intended - mainly for porcelain tools consumption. If git is unable to - produce a valid value size is set to zero. - Note that only message is considered, if also a diff is shown - its size is not included. + Include a line log size <number> in the output for each commit, + where <number> is the length of that commit's message in bytes. + Intended to speed up tools that read log messages from git log + output by allowing them to allocate space in advance. + + + + + +-L <start>,<end>:<file> + + +-L :<funcname>:<file> + + + + Trace the evolution of the line range given by "<start>,<end>" + (or the function name regex <funcname>) within the <file>. You may + not give any pathspec limiters. This is currently limited to + a walk starting from a single revision, i.e., you may only + give zero or one positive revision arguments. + You can specify this option more than once. + +<start> and <end> can take one of these forms: + + + +number + +If <start> or <end> is a number, it specifies an +absolute line number (lines count from 1). + + + +/regex/ + +This form will use the first line matching the given +POSIX regex. If <start> is a regex, it will search from the end of +the previous -L range, if any, otherwise from the start of file. +If <start> is ^/regex/, it will search from the start of file. +If <end> is a regex, it will search +starting at the line given by <start>. + + + ++offset or -offset + +This is only valid for <end> and will specify a number +of lines before or after the line given by <start>. + + +If :<funcname> is given in place of <start> and <end>, it is a +regular expression that denotes the range from the first funcname line +that matches <funcname>, up to the next funcname line. :<funcname> +searches from the end of the previous -L range, if any, otherwise +from the start of file. ^:<funcname> searches from the start of +file. + + + + +<revision range> + + + + Show only commits in the specified revision range. When no + <revision range> is specified, it defaults to HEAD (i.e. the + whole history leading to the current commit). origin..HEAD + specifies all the commits reachable from the current commit + (i.e. HEAD), but not from origin. For a complete list of + ways to spell <revision range>, see the Specifying Ranges + section of . @@ -117,12 +182,12 @@ produced by --stat etc. Show only commits that are enough to explain how the files - that match the specified paths came to be. See "History - Simplification" below for details and other simplification + that match the specified paths came to be. See History + Simplification below for details and other simplification modes. -To prevent confusion with options and branch names, paths may need to -be prefixed with "-- " to separate them from options or refnames. +Paths may need to be prefixed with `-- ' to separate them from +options or the revision range, when confusion arises. @@ -233,8 +298,8 @@ ordering and formatting options, such as --reverse.--all-match). -When --show-notes is in effect, the message from the notes as -if it is part of the log message. +When --show-notes is in effect, the message from the notes is +matched as if it were part of the log message. @@ -243,13 +308,24 @@ if it is part of the log message. - Limit the commits output to ones that match all given --grep, + Limit the commits output to ones that match all given --grep, instead of ones that match at least one. +--invert-grep + + + + Limit the commits output to ones with log message that do not + match the pattern specified with --grep=<pattern>. + + + + + -i @@ -257,7 +333,8 @@ if it is part of the log message. - Match the regexp limiting patterns without regard to letters case. + Match the regular expression limiting patterns without regard to letter + case. @@ -306,7 +383,7 @@ if it is part of the log message. - Consider the limiting patterns to be Perl-compatible regexp. + Consider the limiting patterns to be Perl-compatible regular expressions. Requires libpcre to be compiled in. @@ -357,7 +434,7 @@ if it is part of the log message. - Show only commits which have at least (or at most) that many + Show only commits which have at least (or at most) that many parent commits. In particular, --max-parents=1 is the same as --no-merges, --min-parents=2 is the same as --merges. --max-parents=0 gives all root commits and --min-parents=3 all octopus merges. @@ -379,7 +456,8 @@ parents) and --max-parents=-1 (negative numbers denote no u because merges into a topic branch tend to be only about adjusting to updated upstream from time to time, and this option allows you to ignore the individual commits - brought in to your history by such a merge. + brought in to your history by such a merge. Cannot be + combined with --bisect. @@ -459,6 +537,37 @@ parents) and --max-parents=-1 (negative numbers denote no u +--exclude=<glob-pattern> + + + + Do not include refs matching <glob-pattern> that the next --all, + --branches, --tags, --remotes, or --glob would otherwise + consider. Repetitions of this option accumulate exclusion patterns + up to the next --all, --branches, --tags, --remotes, or + --glob option (other options or arguments do not clear + accumulated patterns). + +The patterns given should not begin with refs/heads, refs/tags, or +refs/remotes when applied to --branches, --tags, or --remotes, +respectively, and they must begin with refs/ when applied to --glob +or --all. If a trailing /* is intended, it must be given +explicitly. + + + + +--reflog + + + + Pretend as if all objects mentioned by reflogs are listed on the + command line as <commit>. + + + + + --ignore-missing @@ -477,7 +586,7 @@ parents) and --max-parents=-1 (negative numbers denote no u Pretend as if the bad bisection ref refs/bisect/bad was listed and as if it was followed by --not and the good bisection refs refs/bisect/good-* on the command - line. + line. Cannot be combined with --first-parent. @@ -512,15 +621,15 @@ parents) and --max-parents=-1 (negative numbers denote no u Omit any commit that introduces the same change as - another commit on the "other side" when the set of + another commit on the other side when the set of commits are limited with symmetric difference. For example, if you have two branches, A and B, a usual way to list all commits on only one side of them is with --left-right (see the example below in the description of -the --left-right option). It however shows the commits that were cherry-picked -from the other branch (for example, "3rd on b" may be cherry-picked -from branch A). With this option, such pairs of commits are +the --left-right option). However, it shows the commits that were +cherry-picked from the other branch (for example, 3rd on b may be +cherry-picked from branch A). With this option, such pairs of commits are excluded from the output. @@ -571,9 +680,9 @@ list. reflog entries from the most recent one to older ones. When this option is used you cannot specify commits to exclude (that is, ^commit, commit1..commit2, - nor commit1...commit2 notations cannot be used). + and commit1...commit2 notations cannot be used). -With --pretty format other than oneline (for obvious reasons), +With --pretty format other than oneline (for obvious reasons), this causes the output to have two extra lines of information taken from the reflog. By default, commit@{Nth} notation is used in the output. When the starting commit is specified as @@ -601,8 +710,8 @@ See also . - Output uninteresting commits at the boundary, which are usually - not shown. + Output excluded boundary commits. Boundary commits are + prefixed with -. @@ -718,24 +827,24 @@ filtered for foo, they look different and equal, respective In the following, we will always refer to the same example history to illustrate the differences between simplification settings. We assume that you are filtering for a file foo in this commit graph: - .-A---M---N---O---P - / / / / / - I B C D E - \ / / / / - `-------------' -The horizontal line of history A---P is taken to be the first parent of + .-A---M---N---O---P---Q + / / / / / / + I B C D E Y + \ / / / / / + `-------------' X +The horizontal line of history A---Q is taken to be the first parent of each merge. The commits are: I is the initial commit, in which foo exists with contents - "asdf", and a file quux exists with contents "quux". Initial + asdf, and a file quux exists with contents quux. Initial commits are compared to an empty tree, so I is !TREESAME. -In A, foo contains just "foo". +In A, foo contains just foo. @@ -746,27 +855,33 @@ In A, foo contains just "foo". -C does not change foo, but its merge N changes it to "foobar", +C does not change foo, but its merge N changes it to foobar, so it is not TREESAME to any parent. -D sets foo to "baz". Its merge O combines the strings from - N and D to "foobarbaz"; i.e., it is not TREESAME to any parent. +D sets foo to baz. Its merge O combines the strings from + N and D to foobarbaz; i.e., it is not TREESAME to any parent. + + + + +E changes quux to xyzzy, and its merge P combines the + strings to quux xyzzy. P is TREESAME to O, but not to E. -E changes quux to "xyzzy", and its merge P combines the - strings to "quux xyzzy". Despite appearing interesting, P is - TREESAME to all parents. +X is an independent root commit that added a new file side, and Y + modified it. Y is TREESAME to X. Its merge Q added side to P, and + Q is TREESAME to P, but not to Y. rev-list walks backwards through history, including or excluding commits based on whether --full-history and/or parent rewriting -(via --parents or --children) are used. The following settings +(via --parents or --children) are used. The following settings are available. @@ -790,7 +905,7 @@ Default mode available, removed B from consideration entirely. C was considered via N, but is TREESAME. Root commits are compared to an empty tree, so I is !TREESAME. -Parent/child relations are only visible with --parents, but that does +Parent/child relations are only visible with --parents, but that does not affect the commits selected in default mode, so we have shown the parent lines. @@ -807,8 +922,8 @@ parent lines. included, this does not imply that the merge itself is! In the example, we get - I A B N D O -P and M were excluded because they are TREESAME to a parent. E, + I A B N D O P Q +M was excluded because it is TREESAME to both parents. E, C and B were all walked, but only B was !TREESAME, so the others do not appear. Note that without parent rewriting, it is not really possible to talk @@ -828,7 +943,7 @@ them disconnected. Merges are always included. However, their parent list is rewritten: Along each parent, prune away commits that are not included themselves. This results in - .-A---M---N---O---P + .-A---M---N---O---P---Q / / / / / I B / D / \ / / / / @@ -836,7 +951,7 @@ themselves. This results in Compare to --full-history without rewriting above. Note that E was pruned away because it is TREESAME, but the parent list of P was rewritten to contain E's parent I. The same happened for C and -N. Note also that P was included despite being TREESAME. +N, and X, Y and Q. @@ -887,8 +1002,9 @@ Set C' to C. Replace each parent P of C' with its simplification P'. In - the process, drop parents that are ancestors of other parents, and - remove duplicates. + the process, drop parents that are ancestors of other parents or that are + root commits TREESAME to an empty tree, and remove duplicates, but take care + to never drop all parents that we are TREESAME to. @@ -906,7 +1022,7 @@ If after this parent rewriting, C' is a root or merge commi I B D \ / / `---------' -Note the major differences in N and P over --full-history: +Note the major differences in N, P, and Q over --full-history: @@ -920,6 +1036,13 @@ If after this parent rewriting, C' is a root or merge commi removed completely, because it had one parent and is TREESAME. + + +Q's parent list had Y simplified to X. X was then removed, because it + was a TREESAME root. Q was then removed completely, because it had one + parent and is TREESAME. + + @@ -933,9 +1056,9 @@ If after this parent rewriting, C' is a root or merge commi Limit the displayed commits to those directly on the ancestry - chain between the "from" and "to" commits in the given commit - range. I.e. only display commits that are ancestor of the "to" - commit, and descendants of the "from" commit. + chain between the from and to commits in the given commit + range. I.e. only display commits that are ancestor of the to + commit and descendants of the from commit. As an example use case, consider the following commit history: D---E-------F @@ -946,7 +1069,7 @@ If after this parent rewriting, C' is a root or merge commi A regular D..M computes the set of commits that are ancestors of M, but excludes the ones that are ancestors of D. This is useful to see what happened to the history leading to M since D, in the sense -that "what does M have that did not exist in D". The result in this +that what does M have that did not exist in D. The result in this example would be all the commits, except A and B (and D itself, of course). When we want to find out what commits in M are contaminated with the @@ -987,6 +1110,17 @@ commits are marked as TREESAME (subject to be simplified away). +--author-date-order + + + + Show no parents before all of its children are shown, but + otherwise show commits in the author timestamp order. + + + + + --topo-order @@ -1023,58 +1157,21 @@ together.
Object Traversal -These options are mostly targeted for packing of git repositories. +These options are mostly targeted for packing of Git repositories. ---objects - - - - Print the object IDs of any object referenced by the listed - commits. --objects foo ^bar thus means "send me - all object IDs which I need to download if I have the commit - object bar, but not foo". - - - - - ---objects-edge - - - - Similar to --objects, but also print the IDs of excluded - commits prefixed with a "-" character. This is used by - to build "thin" pack, which records - objects in deltified form based on objects contained in these - excluded commits to reduce network traffic. - - - - - ---unpacked - - - - Only useful with --objects; print the object IDs that are not - in packs. - - - - - --no-walk[=(sorted|unsorted)] Only show the given commits, but do not traverse their ancestors. This has no effect if a range is specified. If the argument - "unsorted" is given, the commits are show in the order they were - given on the command line. Otherwise (if "sorted" or no argument - was given), the commits are show in reverse chronological order + unsorted is given, the commits are shown in the order they were + given on the command line. Otherwise (if sorted or no argument + was given), the commits are shown in reverse chronological order by commit time. + Cannot be combined with --graph. @@ -1084,7 +1181,7 @@ together. - Overrides a previous --no-walk. + Overrides a previous --no-walk. @@ -1104,10 +1201,13 @@ together. Pretty-print the contents of the commit logs in a given format, where <format> can be one of oneline, short, medium, - full, fuller, email, raw and format:<string>. See - the "PRETTY FORMATS" section for some additional details for each - format. When omitted, the format defaults to medium. + full, fuller, email, raw, format:<string> + and tformat:<string>. When <format> is none of the above, + and has %placeholder in it, it acts as if + --pretty=tformat:<format> were given. +See the "PRETTY FORMATS" section for some additional details for each +format. When =<format> part is omitted, it defaults to medium. Note: you can specify the default pretty format in the repository configuration (see ). @@ -1152,7 +1252,7 @@ people using 80-column terminals. ---encoding[=<encoding>] +--encoding=<encoding> @@ -1160,28 +1260,56 @@ people using 80-column terminals. in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this - defaults to UTF-8. + defaults to UTF-8. Note that if an object claims to be encoded + in X and we are outputting in X, we will output the object + verbatim; this means that invalid sequences in the original + commit may be copied to the output. ---notes[=<ref>] +--expand-tabs=<n> + + +--expand-tabs + + +--no-expand-tabs + + + + Perform a tab expansion (replace each tab with enough spaces + to fill to the next display column that is multiple of <n>) + in the log message before showing it in the output. + --expand-tabs is a short-hand for --expand-tabs=8, and + --no-expand-tabs is a short-hand for --expand-tabs=0, + which disables tab expansion. + +By default, tabs are expanded in pretty formats that indent the log +message by 4 spaces (i.e. medium, which is the default, full, +and fuller). + + + + +--notes[=<treeish>] Show the notes (see ) that annotate the commit, when showing the commit log message. This is the default for git log, git show and git whatchanged commands when - there is no --pretty, --format nor --oneline option given + there is no --pretty, --format, or --oneline option given on the command line. By default, the notes shown are from the notes refs listed in the core.notesRef and notes.displayRef variables (or corresponding environment overrides). See for more details. -With an optional <ref> argument, show this notes ref instead of the -default notes ref(s). The ref is taken to be in refs/notes/ if it -is not qualified. +With an optional <treeish> argument, use the treeish to find the notes +to display. The treeish can specify the full refname when it begins +with refs/notes/; when it begins with notes/, refs/ and otherwise +refs/notes/ is prefixed to form a full name of the ref. Multiple --notes options can be combined to control which notes are being displayed. Examples: "--notes=foo" will show only notes from "refs/notes/foo"; "--notes=foo --notes" will show both notes from @@ -1204,7 +1332,7 @@ being displayed. Examples: "--notes=foo" will show only notes from ---show-notes[=<ref>] +--show-notes[=<treeish>] --[no-]standard-notes @@ -1239,24 +1367,65 @@ being displayed. Examples: "--notes=foo" will show only notes from ---date=(relative|local|default|iso|rfc|short|raw) +--date=<format> Only takes effect for dates shown in human-readable format, such - as when using "--pretty". log.date config variable sets a default - value for log command's --date option. + as when using --pretty. log.date config variable sets a default + value for the log command's --date option. By default, dates + are shown in the original time zone (either committer's or + author's). If -local is appended to the format (e.g., + iso-local), the user's local time zone is used instead. --date=relative shows dates relative to the current time, -e.g. "2 hours ago". ---date=local shows timestamps in user's local timezone. ---date=iso (or --date=iso8601) shows timestamps in ISO 8601 format. +e.g. 2 hours ago. The -local option cannot be used with +--raw or --relative. +--date=local is an alias for --date=default-local. +--date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like format. +The differences to the strict ISO 8601 format are: + + + +a space instead of the T date/time delimiter + + + + +a space between time and time zone + + + + +no colon between hours and minutes of the time zone + + + +--date=iso-strict (or --date=iso8601-strict) shows timestamps in strict +ISO 8601 format. --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 -format, often found in E-mail messages. ---date=short shows only date but not time, in YYYY-MM-DD format. ---date=raw shows the date in the internal raw git format %s %z format. ---date=default shows timestamps in the original timezone -(either committer's or author's). +format, often found in email messages. +--date=short shows only the date, but not the time, in YYYY-MM-DD format. +--date=raw shows the date in the internal raw Git format %s %z format. +--date=format:... feeds the format ... to your system strftime. +Use --date=format:%c to show the date in your system locale's +preferred format. See the strftime manual for a complete list of +format placeholders. When using -local, the correct syntax is +--date=format-local:.... +--date=default is the default format, and is similar to +--date=rfc2822, with a few exceptions: + + + +there is no comma after the day-of-week + + + + +the time zone is omitted when the local time zone is used + + + @@ -1319,17 +1488,32 @@ format, often found in E-mail messages. on the left hand side of the output. This may cause extra lines to be printed in between commits, in order for the graph history to be drawn properly. + Cannot be combined with --no-walk. This enables parent rewriting, see History Simplification below. This implies the --topo-order option by default, but the --date-order option may also be specified. + + +--show-linear-break[=<barrier>] + + + + When --graph is not used, all history branches are flattened + which can make it hard to see that the two consecutive commits + do not belong to a linear branch. This option puts a barrier + in between them in that case. If <barrier> is specified, it + is the string that will be shown instead of the default one. + + +
Diff Formatting -Below are listed options that control the formatting of diff output. +Listed below are options that control the formatting of diff output. Some of them are specific to , however other diff options may be given. See for more options. @@ -1395,16 +1579,6 @@ options may be given. See for more options. - - --s - - - - Suppress diff output. - - -
@@ -1488,11 +1662,14 @@ Subject: [PATCH] <title line> raw The raw format shows the entire commit exactly as -stored in the commit object. Notably, the SHA1s are +stored in the commit object. Notably, the SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and parents information show the -true parent commits, without taking grafts nor history -simplification into account. +true parent commits, without taking grafts or history +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +git log --raw. To get full object names in a raw diff format, +use --no-abbrev. @@ -1545,7 +1722,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%aN: author name (respecting .mailmap, see or ) +%aN: author name (respecting .mailmap, see + or ) @@ -1555,7 +1733,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%aE: author email (respecting .mailmap, see or ) +%aE: author email (respecting .mailmap, see + or ) @@ -1580,7 +1759,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%ai: author date, ISO 8601 format +%ai: author date, ISO 8601-like format + + + + +%aI: author date, strict ISO 8601 format @@ -1590,7 +1774,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%cN: committer name (respecting .mailmap, see or ) +%cN: committer name (respecting .mailmap, see + or ) @@ -1600,12 +1785,13 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%cE: committer email (respecting .mailmap, see or ) +%cE: committer email (respecting .mailmap, see + or ) -%cd: committer date +%cd: committer date (format respects --date= option) @@ -1625,7 +1811,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%ci: committer date, ISO 8601 format +%ci: committer date, ISO 8601-like format + + + + +%cI: committer date, strict ISO 8601 format @@ -1635,6 +1826,11 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff +%D: ref names without the " (", ")" wrapping. + + + + %e: encoding @@ -1670,7 +1866,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%G?: show either "G" for Good or "B" for Bad for a signed commit +%G?: show "G" for a Good signature, "B" for a Bad signature, "U" for a good, + untrusted signature and "N" for no signature @@ -1680,6 +1877,11 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff +%GK: show the key used to sign a signed commit + + + + %gD: reflog selector, e.g., refs/stash@{1} @@ -1695,7 +1897,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%gN: reflog identity name (respecting .mailmap, see or ) +%gN: reflog identity name (respecting .mailmap, see + or ) @@ -1705,7 +1908,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%gE: reflog identity email (respecting .mailmap, see or ) +%gE: reflog identity email (respecting .mailmap, see + or ) @@ -1735,7 +1939,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%C(…): color specification, as described in color.branch.* config option +%C(…): color specification, as described in color.branch.* config option; + adding auto, at the beginning will emit color only when colors are + enabled for log output (by color.diff, color.ui, or --color, and + respecting the auto settings of the former if we are going to a + terminal). auto alone (i.e. %C(auto)) will turn on auto coloring + on the next placeholders until the color is switched again. @@ -1764,14 +1973,49 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff . + + +%<(<N>[,trunc|ltrunc|mtrunc]): make the next placeholder take at + least N columns, padding spaces on the right if necessary. + Optionally truncate at the beginning (ltrunc), the middle (mtrunc) + or the end (trunc) if the output is longer than N columns. + Note that truncating only works correctly with N >= 2. + + + + +%<|(<N>): make the next placeholder take at least until Nth + columns, padding spaces on the right if necessary + + + + +%>(<N>), %>|(<N>): similar to %<(<N>), %<|(<N>) + respectively, but padding spaces on the left + + + + +%>>(<N>), %>>|(<N>): similar to %>(<N>), %>|(<N>) + respectively, except that if the next placeholder takes more spaces + than given and there are spaces on its left, use those spaces + + + + +%><(<N>), %><|(<N>): similar to % <(<N>), %<|(<N>) + respectively, but padding both sides (i.e. the text is centered) + + Some placeholders may depend on other options given to the revision traversal engine. For example, the %g* reflog options will insert an empty string unless we are traversing reflog entries (e.g., by -git log -g). The %d placeholder will use the "short" decoration -format if --decorate was not already provided on the command line. +git log -g). The %d and %D placeholders will use the "short" +decoration format if --decorate was not already provided on the command +line. If you add a + (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string. @@ -1811,7 +2055,7 @@ $ git log -2 --pretty=%h 4da45bef -Common diff options +COMMON DIFF OPTIONS @@ -1826,7 +2070,20 @@ $ git log -2 --pretty=%h 4da45bef Generate patch (see section on generating patches). - + + + + + +-s + + +--no-patch + + + + Suppress diff output. Useful for commands like git show that + show the patch by default, or to cancel the effect of --patch. @@ -1851,8 +2108,11 @@ $ git log -2 --pretty=%h 4da45bef - Generate the raw format. - + For each commit, show a summary of changes using the raw diff + format. See the "RAW OUTPUT FORMAT" section of + . This is different from showing the log + itself in raw format, which you can achieve with + --format=raw. @@ -1899,6 +2159,63 @@ $ git log -2 --pretty=%h 4da45bef +--diff-algorithm={patience|minimal|histogram|myers} + + + + Choose a diff algorithm. The variants are as follows: + + + + +default, myers + + + + The basic greedy diff algorithm. Currently, this is the default. + + + + + +minimal + + + + Spend extra time to make sure the smallest possible diff is + produced. + + + + + +patience + + + + Use "patience diff" algorithm when generating patches. + + + + + +histogram + + + + This algorithm extends the patience algorithm to "support + low-occurrence common elements". + + + + +For instance, if you configured diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option. + + + + --stat[=<width>[,<name-width>[,<count>]]] @@ -2117,8 +2434,8 @@ any of those replacements occurred. Show colored diff. - The value must be always (the default for <when>), never, or auto. - The default value is never. + --color (i.e. without =<when>) is the same as --color=always. + <when> can be one of always, never, or auto. @@ -2214,6 +2531,8 @@ differences. You may want to append |[^[:space:]] to your expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline. +For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character. The regex can also be set via a diff driver or configuration option, see or . Giving it explicitly overrides any diff driver or configuration setting. Diff drivers @@ -2248,8 +2567,8 @@ override configuration settings. - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by core.whitespace + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the @@ -2261,6 +2580,22 @@ override configuration settings. +--ws-error-highlight=<kind> + + + + Highlight whitespace errors on lines specified by <kind> + in the color specified by color.diff.whitespace. <kind> + is a comma separated list of old, new, context. When + this option is not given, only whitespace errors in new + lines are highlighted. E.g. --ws-error-highlight=new,old + highlights whitespace errors on both deleted and added lines. + all can be used as a short-hand for old,new,context. + + + + + --full-index @@ -2315,7 +2650,7 @@ few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for git to consider it a total +original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines). When used with -M, a totally-rewritten file is also considered as the @@ -2341,13 +2676,13 @@ another file. --follow. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the - file's size). For example, -M90% means git should consider a + file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use - -M100%. + -M100%. The default similarity index is 50%. @@ -2392,7 +2727,7 @@ another file. Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch - is not meant to be applied with patch nor git apply; this is + is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, @@ -2441,11 +2776,15 @@ of a delete/create pair. - Look for differences that introduce or remove an instance of - <string>. Note that this is different than the string simply - appearing in diff output; see the pickaxe entry in - for more details. + Look for differences that change the number of occurrences of + the specified string (i.e. addition/deletion) in a file. + Intended for the scripter's use. +It is useful when you're looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block. @@ -2454,9 +2793,20 @@ of a delete/create pair. - Look for differences whose added or removed line matches - the given <regex>. + Look for differences whose patch text contains added/removed + lines that match <regex>. +To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file: ++ return !regexec(regexp, two->ptr, 1, &regmatch, 0); +... +- hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0); +While git log -G"regexec\(regexp" will show this commit, git log +-S"regexec\(regexp" --pickaxe-regex will not (because the number of +occurrences of that string did not change). +See the pickaxe entry in for more +information. @@ -2477,8 +2827,8 @@ of a delete/create pair. - Make the <string> not a plain string but an extended POSIX - regex to match. + Treat the <string> given to -S as an extended POSIX regular + expression to match. @@ -2490,6 +2840,9 @@ of a delete/create pair. Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. + This overrides the diff.orderFile configuration variable + (see ). To cancel diff.orderFile, + use -O/dev/null. @@ -2574,6 +2927,16 @@ of a delete/create pair. +--ignore-blank-lines + + + + Ignore changes whose lines are all blank. + + + + + --inter-hunk-context=<lines> @@ -2645,7 +3008,7 @@ of a delete/create pair. Ignore changes to submodules in the diff generation. <when> can be - either "none", "untracked", "dirty" or "all", which is the default + either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the @@ -2769,10 +3132,10 @@ rename to a combined diff format -Any diff-generating command can take the -c` or --cc option to +Any diff-generating command can take the -c or --cc option to produce a combined diff when showing a merge. This is the default format when showing merges with or -. Note also that you can give the `-m option to any +. Note also that you can give the -m option to any of these commands to force generation of diffs with individual parents of a merge. A combined diff format looks like this: @@ -2867,7 +3230,7 @@ added, from the point of view of that parent). 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 eight other lines are the same +in either file1 or file2). Also eight 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 @@ -2877,7 +3240,7 @@ two unresolved merge parents with the working tree file "their version"). -Examples +EXAMPLES @@ -2896,7 +3259,7 @@ two unresolved merge parents with the working tree file Show all commits since version v2.6.12 that changed any file - in the include/scsi or drivers/scsi subdirectories + in the include/scsi or drivers/scsi subdirectories @@ -2907,7 +3270,7 @@ two unresolved merge parents with the working tree file Show the changes during the last two weeks to the file gitk. - The "--" is necessary to avoid confusion with the branch named + The -- is necessary to avoid confusion with the branch named gitk @@ -2926,11 +3289,11 @@ two unresolved merge parents with the working tree file -git log --follow builtin-rev-list.c +git log --follow builtin/rev-list.c - Shows the commits that changed builtin-rev-list.c, including + Shows the commits that changed builtin/rev-list.c, including those commits that occurred before the file was given its present name. @@ -2966,7 +3329,7 @@ two unresolved merge parents with the working tree file Shows the history including change diffs, but only from the - "main branch" perspective, skipping commits that come from merged + main branch perspective, skipping commits that come from merged branches, and showing full diffs of changes introduced by the merges. This makes sense only when following a strict policy of merging all topic branches when staying on a single integration branch. @@ -2975,6 +3338,17 @@ two unresolved merge parents with the working tree file +git log -L '/int main/',/^}/:main.c + + + + Shows how the function main() in the file main.c evolved + over time. + + + + + git log -3 @@ -2986,37 +3360,49 @@ two unresolved merge parents with the working tree file -Discussion -At the core level, git is character encoding agnostic. +DISCUSSION +Git is to some extent character encoding agnostic. -The pathnames recorded in the index and in the tree objects - are treated as uninterpreted sequences of non-NUL bytes. - What readdir(2) returns are what are recorded and compared - with the data git keeps track of, which in turn are expected - to be what lstat(2) and creat(2) accepts. There is no such - thing as pathname encoding translation. +The contents of the blob objects are uninterpreted sequences + of bytes. There is no encoding translation at the core + level. -The contents of the blob objects are uninterpreted sequences - of bytes. There is no encoding translation at the core - level. +Path names are encoded in UTF-8 normalization form C. This + applies to tree objects, the index file, ref names, as well as + path names in command line arguments, environment variables + and config files (.git/config (see ), + , and + ). +Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly. -The commit log messages are uninterpreted sequences of non-NUL - bytes. +Commit log messages are typically encoded in UTF-8, but other + extended ASCII encodings are also supported. This includes + ISO-8859-x, CP125x and many others, but not UTF-16/32, + EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, + EUC-x, CP9xx etc.). Although we encourage that the commit log messages are encoded -in UTF-8, both the core and git Porcelain are designed not to +in UTF-8, both the core and Git Porcelain are designed not to force UTF-8 on projects. If all participants of a particular -project find it more convenient to use legacy encodings, git +project find it more convenient to use legacy encodings, Git does not forbid it. However, there are a few things to keep in mind. @@ -3055,7 +3441,7 @@ object level, because re-coding to UTF-8 is not necessarily a reversible operation. -Configuration +CONFIGURATION See for core variables and for settings related to diff generation. @@ -3065,8 +3451,8 @@ format.pretty - Default for the --format option. (See "PRETTY FORMATS" above.) - Defaults to "medium". + Default for the --format option. (See Pretty Formats above.) + Defaults to medium. @@ -3076,8 +3462,8 @@ i18n.logOutputEncoding - Encoding to use when displaying logs. (See "Discussion", above.) - Defaults to the value of i18n.commitEncoding if set, UTF-8 + Encoding to use when displaying logs. (See Discussion above.) + Defaults to the value of i18n.commitEncoding if set, and UTF-8 otherwise. @@ -3096,7 +3482,20 @@ log.date -log.showroot +log.follow + + + + If true, git log will act as if the --follow option was used when + a single <path> is given. This has the same limitations as --follow, + i.e. it cannot be used to follow multiple files and does not work well + on non-linear history. + + + + + +log.showRoot @@ -3109,7 +3508,7 @@ log.showroot -mailmap.file +mailmap.* diff --git a/doc/source/en/TortoiseGit/git_doc/git-lost-found.xml b/doc/source/en/TortoiseGit/git_doc/git-lost-found.xml deleted file mode 100644 index a08cf4da3..000000000 --- a/doc/source/en/TortoiseGit/git_doc/git-lost-found.xml +++ /dev/null @@ -1,67 +0,0 @@ - - - - - git-lost-found(1) - -git-lost-found(1) - - -NAME -git-lost-found - Recover lost refs that luckily have not yet been pruned - - -SYNOPSIS -
-git lost-found -
- - -DESCRIPTION -NOTE: this command is deprecated. Use with -the option --lost-found instead. -Finds dangling commits and tags from the object database, and -creates refs to them in the .git/lost-found/ directory. Commits and -tags that dereference to commits are stored in .git/lost-found/commit, -and other objects are stored in .git/lost-found/other. - - -OUTPUT -Prints to standard output the object names and one-line descriptions -of any commits or tags found. - - -EXAMPLE -Suppose you run git tag -f and mistype the tag to overwrite. -The ref to your tag is overwritten, but until you run git -prune, the tag itself is still there. -$ git lost-found -[1ef2b196d909eed523d4f3c9bf54b78cdd6843c6] GIT 0.99.9c -... -Also you can use gitk to browse how any tags found relate to each -other. -$ gitk $(cd .git/lost-found/commit && echo ??*) -After making sure you know which the object is the tag you are looking -for, you can reconnect it to your regular refs hierarchy by using -the update-ref command. -$ 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 - - -GIT -Part of the suite - - diff --git a/doc/source/en/TortoiseGit/git_doc/git-ls-files.xml b/doc/source/en/TortoiseGit/git_doc/git-ls-files.xml index 6b62968cf..ad4481a00 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-ls-files.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-ls-files.xml @@ -16,6 +16,7 @@ git ls-files [-z] [-t] [-v] (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (-[c|d|o|i|s|u|k|m])* + [--eol] [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] @@ -220,7 +221,7 @@ shown: - Add the standard git exclusions: .git/info/exclude, .gitignore + Add the standard Git exclusions: .git/info/exclude, .gitignore in each directory, and the user's global exclusion file. @@ -389,6 +390,28 @@ other +--eol + + + + Show <eolinfo> and <eolattr> of files. + <eolinfo> is the file content identification used by Git when + the "text" attribute is "auto" (or not set and core.autocrlf is not false). + <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "". + +"" means the file is not a regular file, it is not in the index or +not accessible in the working tree. +<eolattr> is the attribute that is used when checking out or committing, +it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". +Note: Currently Git does not support "text=auto eol=lf" or "text=auto eol=crlf", +that may change in the future. +Both the <eolinfo> in the index ("i/<eolinfo>") +and in the working tree ("w/<eolinfo>") are shown for regular files, +followed by the ("attr/<eolattr>"). + + + + -- @@ -415,9 +438,11 @@ other git ls-files just outputs the filenames unless --stage is specified in which case it outputs: [<tag> ]<mode> <object> <stage> <file> +git ls-files --eol will show + i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><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, +For an unmerged path, instead of recording a single mode/SHA-1 pair, the index 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 @@ -436,21 +461,21 @@ specifies the format of exclude patterns. -The command line flag --exclude=<pattern> specifies a +The command-line flag --exclude=<pattern> specifies a single pattern. Patterns are ordered in the same order they appear in the command line. -The command line flag --exclude-from=<file> specifies a +The command-line flag --exclude-from=<file> specifies a file containing a list of patterns. Patterns are ordered in the same order they appear in the file. -The command line flag --exclude-per-directory=<name> specifies +The command-line flag --exclude-per-directory=<name> specifies a name of the file in each directory git ls-files examines, normally .gitignore. Files in deeper directories take precedence. Patterns are ordered in the diff --git a/doc/source/en/TortoiseGit/git_doc/git-ls-remote.xml b/doc/source/en/TortoiseGit/git_doc/git-ls-remote.xml index 2444c5377..a39945ce6 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-ls-remote.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-ls-remote.xml @@ -13,8 +13,9 @@ SYNOPSIS
-git ls-remote [--heads] [--tags] [-u <exec> | --upload-pack <exec>] - [--exit-code] <repository> [<refs>…] +git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>] + [-q | --quiet] [--exit-code] [--get-url] + [--symref] [<repository> [<refs>…]]
@@ -49,8 +50,28 @@ commit IDs. --u <exec> +--refs + + + Do not show peeled tags or pseudorefs like HEAD in the output. + + + + + +-q + + +--quiet + + + + Do not print remote URL to stderr. + + + + --upload-pack=<exec> @@ -90,13 +111,26 @@ commit IDs. +--symref + + + + In addition to the object pointed by it, show the underlying + ref pointed by it when showing a symbolic ref. Currently, + upload-pack only shows the symref HEAD, so it will be the only + one shown by ls-remote. + + + + + <repository> - Location of the repository. The shorthand defined in - $GIT_DIR/branches/ can be used. Use "." (dot) to list references in - the local repository. + The "remote" repository to query. This parameter can be + either a URL or the name of a remote (see the GIT URLS and + REMOTES sections of ). @@ -126,9 +160,8 @@ c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 $ 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\* +$ git remote add korg http://www.kernel.org/pub/scm/git/git.git +$ git ls-remote --tags korg v\* d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 diff --git a/doc/source/en/TortoiseGit/git_doc/git-mailinfo.xml b/doc/source/en/TortoiseGit/git_doc/git-mailinfo.xml index 327fd95b3..e5207e465 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-mailinfo.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-mailinfo.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git mailinfo [-k|-b] [-u | --encoding=<encoding> | -n] [--scissors] <msg> <patch> +git mailinfo [-k|-b] [-u | --encoding=<encoding> | -n] [--[no-]scissors] <msg> <patch>
@@ -113,6 +113,20 @@ conversion, even with this flag. +-m + + +--message-id + + + + Copy the Message-ID header at the end of the commit message. This + is useful in order to associate commits with mailing list discussions. + + + + + --scissors diff --git a/doc/source/en/TortoiseGit/git_doc/git-merge-base.xml b/doc/source/en/TortoiseGit/git_doc/git-merge-base.xml index 954664432..6457fbac3 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-merge-base.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-merge-base.xml @@ -16,7 +16,8 @@ git merge-base [-a|--all] <commit> <commit>… git merge-base [-a|--all] --octopus <commit>… git merge-base --is-ancestor <commit> <commit> -git merge-base --independent <commit>… +git merge-base --independent <commit>… +git merge-base --fork-point <ref> [<commit>] @@ -28,8 +29,8 @@ that does not have any better common ancestor is a best common ancestor, i.e. a merge base. Note that there can be more than one merge base for a pair of commits. - -OPERATION MODE + +OPERATION MODES As the most common special case, specifying only two commits on the command line means computing the merge base between the given two commits. More generally, among the two commits to compute the merge base from, @@ -78,6 +79,22 @@ from when used with the --merge- + + +--fork-point + + + + Find the point at which a branch (or any history that leads + to <commit>) forked from another branch (or any reference) + <ref>. This does not just look for the common ancestor of + the two commits, but also takes into account the reflog of + <ref> to see if the history leading to <commit> forked from + an earlier incarnation of the branch <ref> (see discussion + on this mode below). + + + @@ -153,6 +170,27 @@ then fi instead. + +Discussion on fork-point mode +After working on the topic branch created with git checkout -b +topic origin/master, the history of remote-tracking branch +origin/master may have been rewound and rebuilt, leading to a +history of this shape: + o---B1 + / +---o---o---B2--o---o---o---B (origin/master) + \ + B3 + \ + Derived (topic) +where origin/master used to point at commits B3, B2, B1 and now it +points at B, and your topic branch was started on top of it back +when origin/master was at B3. This mode uses the reflog of +origin/master to find B3 as the fork point, so that the topic +can be rebased on top of the updated origin/master by: +$ fork_point=$(git merge-base --fork-point origin/master topic) +$ git rebase --onto origin/master $fork_point topic + See also , diff --git a/doc/source/en/TortoiseGit/git_doc/git-merge-file.xml b/doc/source/en/TortoiseGit/git_doc/git-merge-file.xml index 13bb87cfb..47498b3cc 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-merge-file.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-merge-file.xml @@ -15,7 +15,7 @@
git merge-file [-L <current-name> [-L <base-name> [-L <other-name>]]] [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>] - <current-file> <base-file> <other-file> + [--[no-]diff3] <current-file> <base-file> <other-file>
@@ -41,7 +41,8 @@ however, these conflicts are resolved favouring lines from <current lines from <other-file>, or lines from both respectively. The length of the conflict markers can be given with the --marker-size option. The exit value of this program is negative on error, and the number of -conflicts otherwise. If the merge was clean, the exit value is 0. +conflicts otherwise (truncated to 127 if there are more than that many +conflicts). If the merge was clean, the exit value is 0. git merge-file is designed to be a minimal clone of RCS merge; that is, it implements all of RCS merge's functionality which is needed by . @@ -87,6 +88,16 @@ implements all of RCS merge's functionality which is needed +--diff3 + + + + Show conflicts in "diff3" style. + + + + + --ours diff --git a/doc/source/en/TortoiseGit/git_doc/git-merge-index.xml b/doc/source/en/TortoiseGit/git_doc/git-merge-index.xml index 860b1bf90..2bcc0cd3a 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-merge-index.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-merge-index.xml @@ -19,7 +19,7 @@ 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 +entries, passes the SHA-1 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. @@ -75,11 +75,11 @@ files are passed as arguments 5, 6 and 7. 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 a script calling git's imitation of +Typically this is run with a script calling Git's imitation of 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 +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. diff --git a/doc/source/en/TortoiseGit/git_doc/git-merge-tree.xml b/doc/source/en/TortoiseGit/git_doc/git-merge-tree.xml index 77a1e7a6c..d704d1bc9 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-merge-tree.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-merge-tree.xml @@ -18,7 +18,7 @@ DESCRIPTION -Reads three treeish, and output trivial merge results and +Reads three tree-ish, and output trivial merge results and conflicting stages to the standard output. This is similar to what three-way git read-tree -m does, but instead of storing the results in the index, the command outputs the entries to the diff --git a/doc/source/en/TortoiseGit/git_doc/git-merge.xml b/doc/source/en/TortoiseGit/git_doc/git-merge.xml index 44669567b..78d68280b 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-merge.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-merge.xml @@ -14,7 +14,8 @@ SYNOPSIS
git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] - [-s <strategy>] [-X <strategy-option>] + [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] + [--[no-]allow-unrelated-histories] [--[no-]rerere-autoupdate] [-m <msg>] [<commit>…] git merge <msg> HEAD <commit>… git merge --abort @@ -50,8 +51,8 @@ if there were uncommitted changes when the merge started (and especially if those changes were further modified after the merge was started), git merge --abort will in some cases be unable to reconstruct the original (pre-merge) changes. Therefore: -Warning: Running git merge with uncommitted changes is -discouraged: while possible, it leaves you in a state that is hard to +Warning: Running git merge with non-trivial uncommitted changes is +discouraged: while possible, it may leave you in a state that is hard to back out of in the case of a conflict. @@ -79,6 +80,9 @@ inspect and further tweak the merge result before committing. --edit +-e + + --no-edit @@ -87,9 +91,10 @@ inspect and further tweak the merge result before committing. further edit the auto-generated merge message, so that the user can explain and justify the merge. The --no-edit option can be used to accept the auto-generated message (this is generally - discouraged). The --edit option is still useful if you are - giving a draft message with the -m option from the command line - and want to edit it in the editor. + discouraged). +The --edit (or -e) option is still useful if you are +giving a draft message with the -m option from the command line +and want to edit it in the editor. Older scripts may depend on the historical behaviour of not allowing the user to edit the merge log message. They will see an editor opened when @@ -117,7 +122,8 @@ set to no at the beginning of them. Create a merge commit even when the merge resolves as a - fast-forward. + fast-forward. This is the default behaviour when merging an + annotated (and possibly signed) tag. @@ -178,14 +184,13 @@ merge. - Produce the working tree and index state as if a real - merge happened (except for the merge information), - but do not actually make a commit or - move the HEAD, nor record $GIT_DIR/MERGE_HEAD to - cause the next git commit command to create a merge - commit. This allows you to create a single commit on - top of the current branch whose effect is the same as - merging another branch (or more in case of an octopus). + Produce the working tree and index state as if a real merge + happened (except for the merge information), but do not actually + make a commit, move the HEAD, or record $GIT_DIR/MERGE_HEAD + (to cause the next git commit command to create a merge + commit). This allows you to create a single commit on top of + the current branch whose effect is the same as merging another + branch (or more in case of an octopus). With --no-squash perform the merge and commit the result. This option can be used to override --squash. @@ -224,6 +229,20 @@ option can be used to override --squash. +--verify-signatures + + +--no-verify-signatures + + + + Verify that the commits being merged have good and trusted GPG signatures + and abort the merge in case they do not. + + + + + --summary @@ -280,6 +299,36 @@ option can be used to override --squash. +--allow-unrelated-histories + + + + By default, git merge command refuses to merge histories + that do not share a common ancestor. This option can be + used to override this safety when merging histories of two + projects that started their lives independently. As that is + a very rare occasion, no configuration variable to enable + this by default exists and will not be added. + + + + + +-S[<keyid>] + + +--gpg-sign[=<keyid>] + + + + GPG-sign the resulting merge commit. The keyid argument is + optional and defaults to the committer identity; if specified, + it must be stuck to the option without a space. + + + + + -m <msg> @@ -291,15 +340,12 @@ option can be used to override --squash. will be appended to the specified message. The git fmt-merge-msg command can be used to give a good default for automated git merge -invocations. +invocations. The automated message can include the branch description. ---rerere-autoupdate - - ---no-rerere-autoupdate +--[no-]rerere-autoupdate @@ -335,10 +381,12 @@ commit or stash your changes before running git merge. -If no commit is given from the command line, and if merge.defaultToUpstream -configuration variable is set, merge the remote-tracking branches -that the current branch is configured to use as its upstream. +If no commit is given from the command line, merge the remote-tracking +branches that the current branch is configured to use as its upstream. See also the configuration section of this manual page. +When FETCH_HEAD (and no other commit) is specified, the branches +recorded in the .git/FETCH_HEAD file by the previous invocation +of git fetch for merging are merged to the current branch. @@ -421,6 +469,23 @@ No other changes are made. In particular, the local If you tried a merge which resulted in complex conflicts and want to start over, you can recover with git merge --abort. + +MERGING TAG +When merging an annotated (and possibly signed) tag, Git always +creates a merge commit even if a fast-forward merge is possible, and +the commit message template is prepared with the tag message. +Additionally, if the tag is signed, the signature check is reported +as a comment in the message template. See also . +When you want to just integrate with the work leading to the commit +that happens to be tagged, e.g. synchronizing with an upstream +release point, you may not want to make an unnecessary merge commit. +In such a case, you can "unwrap" the tag yourself before feeding it +to git merge, or pass --ff-only when you do not have any work on +your own. e.g. +git fetch origin +git merge v1.2.3^0 +git merge --ff-only v1.2.3 + HOW CONFLICTS ARE PRESENTED During a merge, the working tree files are updated to reflect the result @@ -428,9 +493,9 @@ of the merge. Among the changes made to the common ancestor's version, non-overlapping ones (that is, you changed an area of the file while the other side left that area intact, or vice versa) are incorporated in the final result verbatim. When both sides made changes to the same area, -however, git cannot randomly pick one side over the other, and asks you to +however, Git cannot randomly pick one side over the other, and asks you to resolve it by leaving what both sides did to that area. -By default, git uses the same style as the one used by the "merge" program +By default, Git uses the same style as the one used by the "merge" program from the RCS suite to present such a conflicted hunk, like this: Here are lines that are either unchanged from the common ancestor, or cleanly resolved because only one side changed. @@ -449,7 +514,7 @@ area. You cannot tell how many lines are deleted and replaced with Barbie's remark on your side. The only thing you can tell is that your side wants to say it is hard and you'd prefer to go shopping, while the other side wants to claim it is easy. -An alternative style can be used by setting the "merge.conflictstyle" +An alternative style can be used by setting the "merge.conflictStyle" configuration variable to "diff3". In "diff3" style, the above conflict may look like this: Here are lines that are either unchanged from the common @@ -555,10 +620,10 @@ release/version name would be acceptable. MERGE STRATEGIES -The merge mechanism (git-merge and git-pull commands) allows the +The merge mechanism (git merge and git pull commands) allows the backend merge strategies to be chosen with -s option. Some strategies can also take their own options, which can be passed by giving -X<option> -arguments to git-merge and/or git-pull. +arguments to git merge and/or git pull. @@ -586,7 +651,7 @@ recursive merged tree of the common ancestors and uses that as the reference tree for the 3-way merge. This has been reported to result in fewer merge conflicts without - causing mis-merges by tests done on actual merge commits + causing mismerges by tests done on actual merge commits taken from Linux 2.6 kernel development history. Additionally this can detect and handle merges involving renames. This is the default merge strategy when @@ -636,6 +701,19 @@ patience +diff-algorithm=[patience|minimal|histogram|myers] + + + + Tells merge-recursive to use a different diff algorithm, which + can help avoid mismerges that occur due to unimportant matching + lines (such as braces from distinct functions). See also + --diff-algorithm. + + + + + ignore-space-change @@ -701,12 +779,34 @@ no-renormalize +no-renames + + + + Turn off rename detection. + See also --no-renames. + + + + + +find-renames[=<n>] + + + + Turn on rename detection, optionally setting the similarity + threshold. This is the default. + See also --find-renames. + + + + + rename-threshold=<n> - Controls the similarity threshold used for rename detection. - See also -M. + Deprecated synonym for find-renames=<n>. @@ -771,13 +871,20 @@ subtree +With the strategies that use 3-way merge (including the default, recursive), +if a change is made on both branches, but later reverted on one of the +branches, that change will be present in the merged result; some people find +this behavior confusing. It occurs because only the heads and the merge base +are considered when performing a merge, not the individual commits. The merge +algorithm therefore considers the reverted change as no change at all, and +substitutes the changed version instead. CONFIGURATION -merge.conflictstyle +merge.conflictStyle @@ -813,10 +920,10 @@ merge.ff - By default, git does not create an extra merge commit when merging + By default, Git does not create an extra merge commit when merging a commit that is a descendant of the current commit. Instead, the tip of the current branch is fast-forwarded. When set to false, - this variable tells git to create an extra merge commit in such + this variable tells Git to create an extra merge commit in such a case (equivalent to giving the --no-ff option from the command line). When set to only, only such fast-forward merges are allowed (equivalent to giving the --ff-only option from the @@ -826,6 +933,18 @@ merge.ff +merge.branchdesc + + + + In addition to branch names, populate the log message with + the branch description text associated with them. Defaults + to false. + + + + + merge.log @@ -855,10 +974,10 @@ merge.renormalize - Tell git that canonical representation of files in the + Tell Git that canonical representation of files in the repository has changed over time (e.g. earlier commits record text files with CRLF line endings, but recent ones use LF line - endings). In such a repository, git can convert the data + endings). In such a repository, Git can convert the data recorded in commits to a canonical form before performing a merge to reduce unnecessary conflicts. For more information, see section "Merging branches with differing checkin/checkout @@ -883,14 +1002,134 @@ merge.tool - Controls which merge resolution program is used by - . Valid built-in values are: "araxis", - "bc3", "diffuse", "ecmerge", "emerge", "gvimdiff", "kdiff3", "meld", - "opendiff", "p4merge", "tkdiff", "tortoisemerge", "vimdiff" - and "xxdiff". Any other value is treated is custom merge tool - and there must be a corresponding mergetool.<tool>.cmd option. + Controls which merge tool is used by . + The list below shows the valid built-in values. + Any other value is treated as a custom merge tool and requires + that a corresponding mergetool.<tool>.cmd variable is defined. + + + + +araxis + + + + +bc + + + + +bc3 + + + + +codecompare + + +deltawalker + + + + +diffmerge + + + + +diffuse + + + + +ecmerge + + + + +emerge + + + + +examdiff + + + + +gvimdiff + + + + +gvimdiff2 + + + + +gvimdiff3 + + + + +kdiff3 + + + + +meld + + + + +opendiff + + + + +p4merge + + + + +tkdiff + + + + +tortoisemerge + + + + +vimdiff + + + + +vimdiff2 + + + + +vimdiff3 + + + + +winmerge + + + + +xxdiff + + + + @@ -943,7 +1182,7 @@ merge.<driver>.recursive -branch.<name>.mergeoptions +branch.<name>.mergeOptions diff --git a/doc/source/en/TortoiseGit/git_doc/git-mergetool--lib.xml b/doc/source/en/TortoiseGit/git_doc/git-mergetool--lib.xml index 70196330e..4986866b7 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-mergetool--lib.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-mergetool--lib.xml @@ -8,7 +8,7 @@ NAME -git-mergetool--lib - Common git merge tool shell scriptlets +git-mergetool--lib - Common Git merge tool shell scriptlets SYNOPSIS @@ -23,7 +23,7 @@ This documentation is meant for people who are studying the Porcelain-ish scripts and/or are writing new ones. The git-mergetool--lib scriptlet is designed to be sourced (using .) by other shell scripts to set up functions for working -with git merge tools. +with Git merge tools. Before sourcing git-mergetool--lib, your script must set TOOL_MODE to define the operation mode for the functions listed below. diff and merge are valid values. diff --git a/doc/source/en/TortoiseGit/git_doc/git-mergetool.xml b/doc/source/en/TortoiseGit/git_doc/git-mergetool.xml index 7aa15af34..4bada8f5e 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-mergetool.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-mergetool.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git mergetool [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>…] +git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>…]
@@ -94,6 +94,9 @@ success of the resolution after the custom tool has exited. Don't prompt before each invocation of the merge resolution program. + This is the default if the merge resolution program is + explicitly specified with the --tool option or with the + merge.tool configuration variable. @@ -103,9 +106,8 @@ success of the resolution after the custom tool has exited. - Prompt before each invocation of the merge resolution program. - This is the default behaviour; the option is provided to - override any configuration settings. + Prompt before each invocation of the merge resolution program + to give the user a chance to skip the path. diff --git a/doc/source/en/TortoiseGit/git_doc/git-mktag.xml b/doc/source/en/TortoiseGit/git_doc/git-mktag.xml index 4842a6e7b..f134ed959 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-mktag.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-mktag.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git mktag < signature_file +git mktag
@@ -24,15 +24,16 @@ that can also be used to sign other objects. Tag Format -A tag signature file has a very simple fixed format: four lines of +A tag signature file, to be fed to this command's standard input, +has a very simple fixed format: four lines of object <sha1> type <typename> tag <tagname> tagger <tagger> followed by some optional free-form message (some tags created -by older git may not have tagger line). The message, when +by older Git may not have tagger line). The message, when exists, is separated by a blank line from the header. The -message part may contain a signature that git itself doesn't +message part may contain a signature that Git itself doesn't care about, but that can be verified with gpg. diff --git a/doc/source/en/TortoiseGit/git_doc/git-mv.xml b/doc/source/en/TortoiseGit/git_doc/git-mv.xml index a64eac50a..a7a8a80a0 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-mv.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-mv.xml @@ -18,7 +18,7 @@ DESCRIPTION -This script is used to move or rename a file, directory or symlink. +Move or rename a file, directory or symlink. git mv [-v] [-f] [-n] [-k] <source> <destination> git mv [-v] [-f] [-n] [-k] <source> ... <destination directory> In the first form, it renames <source>, which must exist and be either @@ -52,7 +52,7 @@ committed. Skip move or rename actions which would lead to an error condition. An error happens when a source is neither existing nor - controlled by GIT, or when it would overwrite an existing + controlled by Git, or when it would overwrite an existing file unless -f is given. @@ -85,6 +85,26 @@ committed. + +SUBMODULES +Moving a submodule using a gitfile (which means they were cloned +with a Git version 1.7.8 or newer) will update the gitfile and +core.worktree setting to make the submodule work in the new location. +It also will attempt to update the submodule.<name>.path setting in +the file and stage that file (unless -n is used). + + +BUGS +Each time a superproject update moves a populated submodule (e.g. when +switching between commits before and after the move) a stale submodule +checkout will remain in the old location and an empty directory will +appear in the new location. To populate the submodule again in the new +location the user will have to run "git submodule update" +afterwards. Removing the old directory is only safe when it uses a +gitfile, as otherwise the history of the submodule will be deleted +too. Both steps will be obsolete when recursive submodule update has +been implemented. + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-name-rev.xml b/doc/source/en/TortoiseGit/git_doc/git-name-rev.xml index 33e71ff1a..4be2e44e4 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-name-rev.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-name-rev.xml @@ -14,7 +14,7 @@ SYNOPSIS
git name-rev [--tags] [--refs=<pattern>] - ( --all | --stdin | <committish>… ) + ( --all | --stdin | <commit-ish>… )
@@ -41,7 +41,8 @@ format parsable by git rev-parse. - Only use refs whose names match a given shell pattern. + Only use refs whose names match a given shell pattern. The pattern + can be one of branch name, tag name or fully qualified ref name. @@ -61,8 +62,10 @@ format parsable by git rev-parse. - Read from stdin, append "(<rev_name>)" to all sha1's of nameable - commits, and pass to stdout + Transform stdin by substituting all the 40-character SHA-1 + hexes (say $hex) with "$hex ($rev_name)". When used with + --name-only, substitute with "$rev_name", omitting $hex + altogether. Intended for the scripter's use. diff --git a/doc/source/en/TortoiseGit/git_doc/git-notes.xml b/doc/source/en/TortoiseGit/git_doc/git-notes.xml index 83c7caa6e..ec190ced6 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-notes.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-notes.xml @@ -14,12 +14,12 @@ SYNOPSIS
git notes [list [<object>]] -git notes add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +git notes add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] git notes copy [-f] ( --stdin | <from-object> <to-object> ) -git notes append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] -git notes edit [<object>] +git notes append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +git notes edit [--allow-empty] [<object>] git notes show [<object>] -git notes merge [-v | -q] [-s <strategy> ] <notes_ref> +git notes merge [-v | -q] [-s <strategy> ] <notes-ref> git notes merge --commit [-v | -q] git notes merge --abort [-v | -q] git notes remove [--ignore-missing] [--stdin] [<object>…] @@ -142,7 +142,7 @@ merge any) into the current notes ref (called "local"). If conflicts arise and a strategy for automatically resolving -conflicting notes (see the -s/--strategy option) is not given, +conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given, the "manual" resolver is used. This resolver checks out the conflicting notes in a special worktree (.git/NOTES_MERGE_WORKTREE), and instructs the user to manually resolve the conflicts there. @@ -268,13 +268,26 @@ get-ref +--allow-empty + + + + Allow an empty note object to be stored. The default behavior is + to automatically remove empty notes. + + + + + --ref <ref> Manipulate the notes tree in <ref>. This overrides GIT_NOTES_REF and the "core.notesRef" configuration. The ref - is taken to be in refs/notes/ if it is not qualified. + specifies the full refname when it begins with refs/notes/; when it + begins with notes/, refs/ and otherwise refs/notes/ is prefixed + to form a full name of the ref. @@ -327,6 +340,7 @@ get-ref When merging notes, resolve notes conflicts using the given strategy. The following strategies are recognized: "manual" (default), "ours", "theirs", "union" and "cat_sort_uniq". + This option overrides the "notes.mergeStrategy" configuration setting. See the "NOTES MERGE STRATEGIES" section below for more information on each notes merge strategy. @@ -420,6 +434,8 @@ conflicts in that work tree. When done, the user can either finalize the merge with git notes merge --commit, or abort the merge with git notes merge --abort. +Users may select an automated merge strategy from among the following using +either -s/--strategy option or configuring notes.mergeStrategy accordingly: "ours" automatically resolves conflicting notes in favor of the local version (i.e. the current notes ref). "theirs" automatically resolves notes conflicts in favor of the remote @@ -453,7 +469,7 @@ Notes: arbitrary files using git hash-object: $ cc *.c $ blob=$(git hash-object -w a.out) -$ git notes --ref=built add -C "$blob" HEAD +$ git notes --ref=built add --allow-empty -C "$blob" HEAD (You cannot simply use git notes --ref=built add -F a.out HEAD because that is not binary-safe.) Of course, it doesn't make much sense to display non-text-format notes @@ -478,6 +494,33 @@ core.notesRef +notes.mergeStrategy + + + + Which merge strategy to choose by default when resolving notes + conflicts. Must be one of manual, ours, theirs, union, or + cat_sort_uniq. Defaults to manual. See "NOTES MERGE STRATEGIES" + section above for more information on each strategy. + +This setting can be overridden by passing the --strategy option. + + + + +notes.<name>.mergeStrategy + + + + Which merge strategy to choose when doing a notes merge into + refs/notes/<name>. This overrides the more general + "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above + for more information on each available strategy. + + + + + notes.displayRef @@ -515,7 +558,8 @@ notes.rewriteMode When copying notes during a rewrite, what to do if the target commit already has a note. Must be one of overwrite, - concatenate, and ignore. Defaults to concatenate. + concatenate, cat_sort_uniq, or ignore. Defaults to + concatenate. This setting can be overridden with the GIT_NOTES_REWRITE_MODE environment variable. @@ -577,7 +621,7 @@ does not match any refs is silently ignored. When copying notes during a rewrite, what to do if the target commit already has a note. - Must be one of overwrite, concatenate, and ignore. + Must be one of overwrite, concatenate, cat_sort_uniq, or ignore. This overrides the core.rewriteMode setting. @@ -598,15 +642,6 @@ on the notes.rewrite.<command> and notes.re - -Author -Written by Johannes Schindelin <johannes.schindelin@gmx.de> and -Johan Herland <johan@herland.net> - - -Documentation -Documentation by Johannes Schindelin and Johan Herland - GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-p4.xml b/doc/source/en/TortoiseGit/git_doc/git-p4.xml index 6c7a7065c..1266b3f6f 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-p4.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-p4.xml @@ -22,12 +22,12 @@ DESCRIPTION This command provides a way to interact with p4 repositories -using git. -Create a new git repository from an existing p4 repository using +using Git. +Create a new Git repository from an existing p4 repository using git p4 clone, giving it one or more p4 depot paths. Incorporate new commits from p4 changes with git p4 sync. The sync command is also used to include new branches from other p4 depot paths. -Submit git changes back to p4 using git p4 submit. The command +Submit Git changes back to p4 using git p4 submit. The command git p4 rebase does a sync plus rebases the current branch onto the updated p4 remote branch. @@ -42,7 +42,7 @@ Clone a repository: -Do some work in the newly created git repository: +Do some work in the newly created Git repository: $ cd project $ vi foo.h @@ -50,7 +50,7 @@ $ git commit -a -m "edited foo.h" -Update the git repository with recent changes from p4, rebasing your +Update the Git repository with recent changes from p4, rebasing your work on top: $ git p4 rebase @@ -67,20 +67,20 @@ Submit your commits back to p4: COMMANDS
Clone -Generally, git p4 clone is used to create a new git directory +Generally, git p4 clone is used to create a new Git directory from an existing p4 repository: $ git p4 clone //depot/path/project This: -Creates an empty git repository in a subdirectory called project. +Creates an empty Git repository in a subdirectory called project. Imports the full contents of the head revision from the given p4 -depot path into a single commit in the git branch refs/remotes/p4/master. +depot path into a single commit in the Git branch refs/remotes/p4/master. @@ -89,30 +89,34 @@ Creates a local branch, master from this remote and checks -To reproduce the entire p4 history in git, use the @all modifier on +To reproduce the entire p4 history in Git, use the @all modifier on the depot path: $ git p4 clone //depot/path/project@all
Sync As development continues in the p4 repository, those changes can -be included in the git repository using: +be included in the Git repository using: $ git p4 sync -This command finds new changes in p4 and imports them as git commits. -P4 repositories can be added to an existing git repository using +This command finds new changes in p4 and imports them as Git commits. +P4 repositories can be added to an existing Git repository using git p4 sync too: $ mkdir repo-git $ cd repo-git $ git init $ git p4 sync //path/in/your/perforce/depot This imports the specified depot into -refs/remotes/p4/master in an existing git repository. The +refs/remotes/p4/master in an existing Git repository. The --branch option can be used to specify a different branch to be used for the p4 content. -If a git repository includes branches refs/remotes/origin/p4, these +If a Git repository includes branches refs/remotes/origin/p4, these will be fetched and consulted first during a git p4 sync. Since importing directly from p4 is considerably slower than pulling changes -from a git remote, this can be useful in a multi-developer environment. +from a Git remote, this can be useful in a multi-developer environment. +If there are multiple branches, doing git p4 sync will automatically +use the "BRANCH DETECTION" algorithm to try to partition new changes +into the right branch. This can be overridden with the --branch +option to specify just a single branch to update.
Rebase @@ -125,12 +129,12 @@ local commits on top of updated p4 changes.
Submit -Submitting changes from a git repository back to the p4 repository +Submitting changes from a Git repository back to the p4 repository requires a separate p4 client workspace. This should be specified -using the P4CLIENT environment variable or the git configuration +using the P4CLIENT environment variable or the Git configuration variable git-p4.client. The p4 client must exist, but the client root will be created and populated if it does not already exist. -To submit all changes that are in the current git branch but not in +To submit all changes that are in the current Git branch but not in the p4/master branch, use: $ git p4 submit To specify a branch other than the current one, use: @@ -139,7 +143,7 @@ the p4/master branch, use: be overridden using the --origin= command-line option. The p4 changes will be created as the user invoking git p4 submit. The --preserve-user option will cause ownership to be modified -according to the author of the git commit. This option requires admin +according to the author of the Git commit. This option requires admin privileges in p4, which can be granted using p4 protect.
@@ -161,7 +165,10 @@ privileges in p4, which can be granted using p4 protect. ---verbose, -v +-v + + +--verbose @@ -178,17 +185,20 @@ subsequent sync operations. ---branch <branch> +--branch <ref> - Import changes into given branch. If the branch starts with - refs/, it will be used as is, otherwise the path refs/heads/ - will be prepended. The default branch is master. If used - with an initial clone, no HEAD will be checked out. + Import changes into <ref> instead of refs/remotes/p4/master. + If <ref> starts with refs/, it is used as is. Otherwise, if + it does not start with p4/, that prefix is added. +By default a <ref> not starting with refs/ is treated as the +name of a remote-tracking branch (under refs/remotes/). This +behavior can be modified using the --import-local option. +The default <ref> is "master". This example imports a new remote "p4/proj2" into an existing -git repository: +Git repository: $ git init $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 @@ -233,7 +243,7 @@ git repository: Query p4 for labels associated with the depot paths, and add - them as tags in git. Limited usefulness as only imports labels + them as tags in Git. Limited usefulness as only imports labels associated with new changelists. Deprecated. @@ -244,7 +254,7 @@ git repository: - Import labels from p4 into git. + Import labels from p4 into Git. @@ -269,9 +279,27 @@ git repository: - Limit the number of imported changes to n. Useful to - limit the amount of history when using the @all p4 revision - specifier. + Import at most n changes, rather than the entire range of + changes included in the given revision specifier. A typical + usage would be use @all as the revision specifier, but then + to use --max-changes 1000 to import only the last 1000 + revisions rather than the entire revision history. + + + + + +--changes-block-size <n> + + + + The internal block size to use when converting a revision + specifier such as @all into a list of specific change + numbers. Instead of using a single call to p4 changes to + find the full list of changes for the conversion, there are a + sequence of calls to p4 changes -m, each of which requests + one block of changes of the given size. The default block size + is 500, which should usually be suitable. @@ -281,12 +309,12 @@ git repository: - The mapping of file names from the p4 depot path to git, by + The mapping of file names from the p4 depot path to Git, by default, involves removing the entire depot path. With this - option, the full p4 depot path is retained in git. For example, + option, the full p4 depot path is retained in Git. For example, path //depot/main/foo/bar.c, when imported from //depot/main/, becomes foo/bar.c. With --keep-path, the - git path is instead depot/main/foo/bar.c. + Git path is instead depot/main/foo/bar.c. @@ -301,6 +329,16 @@ git repository: + + +-/ <path> + + + + Exclude selected depot paths when cloning or syncing. + + +
@@ -314,7 +352,7 @@ options described above. - Where to create the git repository. If not provided, the last + Where to create the Git repository. If not provided, the last component in the p4 depot path is used to create a new directory. @@ -330,16 +368,6 @@ options described above. - - --/ <path> - - - - Exclude selected depot paths when cloning. - - -
@@ -388,19 +416,22 @@ options described above. - Export tags from git as p4 labels. Tags found in git are applied + Export tags from Git as p4 labels. Tags found in Git are applied to the perforce working directory. ---dry-run, -n +-n + + +--dry-run Show just what commits would be submitted to p4; do not change - state in git or p4. + state in Git or p4. @@ -432,6 +463,18 @@ options described above. + + +--branch <branch> + + + + After submitting, sync this named branch instead of the default + p4/master. See the "Sync options" section above for more + information. + + +
@@ -495,12 +538,12 @@ p4 revision specifier on the end: Import all changes from both named depot paths into a single repository. Only files below these directories are included. - There is not a subdirectory in git for each "proj1" and "proj2". + There is not a subdirectory in Git for each "proj1" and "proj2". You must use the --destination option when specifying more than one depot path. The revision specifier must be specified identically on each depot path. If there are files in the depot paths with the same name, the path with the most recently - updated version of the file is the one that appears in git. + updated version of the file is the one that appears in Git. @@ -518,11 +561,11 @@ useClientSpec variable is automatically set in the repository configuration file. This allows future git p4 submit commands to work properly; the submit command looks only at the variable and does not have a command-line option. -The full syntax for a p4 view is documented in p4 help views. Git p4 +The full syntax for a p4 view is documented in p4 help views. git p4 knows only a subset of the view syntax. It understands multi-line mappings, overlays with +, exclusions with - and double-quotes around whitespace. Of the possible wildcards, git p4 only handles -…, and only when it is at the end of the path. Git p4 will complain +…, and only when it is at the end of the path. git p4 will complain if it encounters an unhandled wildcard. Bugs in the implementation of overlap mappings exist. If multiple depot paths map through overlays to the same location in the repository, @@ -535,7 +578,7 @@ variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. BRANCH DETECTION -P4 does not have the same concept of a branch as git. Instead, +P4 does not have the same concept of a branch as Git. Instead, p4 organizes its content as a directory tree, where by convention different logical branches are in different locations in the tree. The p4 branch command is used to maintain mappings between @@ -544,7 +587,7 @@ can use these mappings to determine branch relationships. If you have a repository where all the branches of interest exist as subdirectories of a single depot path, you can use --detect-branches when cloning or syncing to have git p4 automatically find -subdirectories in p4, and to generate these as branches in git. +subdirectories in p4, and to generate these as branches in Git. For example, if the P4 repository structure is: //depot/main/... //depot/branch1/... @@ -556,20 +599,22 @@ subdirectories in p4, and to generate these as branches in git. called master, and one for //depot/branch1 called depot/branch1. However, it is not necessary to create branches in p4 to be able to use them like branches. Because it is difficult to infer branch -relationships automatically, a git configuration setting +relationships automatically, a Git configuration setting git-p4.branchList can be used to explicitly identify branch relationships. It is a list of "source:destination" pairs, like a simple p4 branch specification, where the "source" and "destination" are the path elements in the p4 repository. The example above relied on the presence of the p4 branch. Without p4 branches, the same result will occur with: -git config git-p4.branchList main:branch1 -git p4 clone --detect-branches //depot@all +git init depot +cd depot +git config git-p4.branchList main:branch1 +git p4 clone --detect-branches //depot@all . PERFORMANCE The fast-import mechanism used by git p4 creates one pack file for -each invocation of git p4 sync. Normally, git garbage compression +each invocation of git p4 sync. Normally, Git garbage compression () automatically compresses these to fewer pack files, but explicit invocation of git repack -adf may improve performance. @@ -649,9 +694,9 @@ git-p4.syncFromOrigin - Because importing commits from other git repositories is much faster + Because importing commits from other Git repositories is much faster than importing them from p4, a mechanism exists to find p4 changes - first in git remotes. If branches exist under refs/remote/origin/p4, + first in Git remotes. If branches exist under refs/remote/origin/p4, those will be fetched and used when syncing from p4. This variable can be set to false to disable this behavior. @@ -730,6 +775,107 @@ git-p4.useClientSpec + + +git-p4.pathEncoding + + + + Perforce keeps the encoding of a path as given by the originating OS. + Git expects paths encoded as UTF-8. Use this config to tell git-p4 + what encoding Perforce had used for the paths. This encoding is used + to transcode the paths to UTF-8. As an example, Perforce on Windows + often uses "cp1252" to encode path names. + + + + + +git-p4.largeFileSystem + + + + Specify the system that is used for large (binary) files. Please note + that large file systems do not support the git p4 submit command. + Only Git LFS is implemented right now (see https://git-lfs.github.com/ + for more information). Download and install the Git LFS command line + extension to use this option and configure it like this: + +git config git-p4.largeFileSystem GitLFS + + + + +git-p4.largeFileExtensions + + + + All files matching a file extension in the list will be processed + by the large file system. Do not prefix the extensions with .. + + + + + +git-p4.largeFileThreshold + + + + All files with an uncompressed size exceeding the threshold will be + processed by the large file system. By default the threshold is + defined in bytes. Add the suffix k, m, or g to change the unit. + + + + + +git-p4.largeFileCompressedThreshold + + + + All files with a compressed size exceeding the threshold will be + processed by the large file system. This option might slow down + your clone/sync process. By default the threshold is defined in + bytes. Add the suffix k, m, or g to change the unit. + + + + + +git-p4.largeFilePush + + + + Boolean variable which defines if large files are automatically + pushed to a server. + + + + + +git-p4.keepEmptyCommits + + + + A changelist that contains only excluded files will be imported + as an empty commit if this boolean option is set to true. + + + + + +git-p4.mapUser + + + + Map a P4 user to a name and email address in Git. Use a string + with the following format to create a mapping: + +git config --add git-p4.mapUser "p4user = First Last <mail@address.com>" +A mapping will override any user information from P4. Mappings for +multiple P4 user can be defined. + +
@@ -773,7 +919,7 @@ git-p4.preserveUser - On submit, re-author changes to reflect the git author, + On submit, re-author changes to reflect the Git author, regardless of who invokes git p4 submit. @@ -859,7 +1005,7 @@ git-p4.exportLabels - Export git tags to p4 labels, as per --export-labels. + Export Git tags to p4 labels, as per --export-labels. @@ -893,7 +1039,7 @@ git-p4.conflict -Changesets from p4 are imported using git fast-import. +Changesets from p4 are imported using Git fast-import. @@ -905,7 +1051,7 @@ Cloning or syncing does not require a p4 client; file contents are Submitting requires a p4 client, which is not in the same location - as the git repository. Patches are applied, one at a time, to + as the Git repository. Patches are applied, one at a time, to this p4 client and submitted from there. diff --git a/doc/source/en/TortoiseGit/git_doc/git-pack-objects.xml b/doc/source/en/TortoiseGit/git_doc/git-pack-objects.xml index 7d7343865..e80d4c040 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-pack-objects.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-pack-objects.xml @@ -17,7 +17,7 @@ [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--stdout | base-name] - [--keep-true-parents] < object-list + [--shallow] [--keep-true-parents] < object-list @@ -36,7 +36,7 @@ each object that a delta depends upon must be present within the pack. objects in the pack. Placing both the index file (.idx) and the packed archive (.pack) in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) -enables git to read from the pack archive. +enables Git to read from the pack archive. The git unpack-objects command can read the packed archive and expand the objects contained in the pack into "one-file one-object" format; this is typically done by the smart-pull @@ -55,9 +55,8 @@ base-name Write into a pair of files (.pack and .idx), using <base-name> to determine the name of the created file. When this option is used, the two files are written in - <base-name>-<SHA1>.{pack,idx} files. <SHA1> is a hash - of the sorted object names to make the resulting filename - based on the pack content, and written to the standard + <base-name>-<SHA-1>.{pack,idx} files. <SHA-1> is a hash + based on the pack content and is written to the standard output of the command. @@ -84,6 +83,8 @@ base-name the same way as git rev-list with the --objects flag uses its commit arguments to build the list of objects it outputs. The objects on the resulting list are packed. + Besides revisions, --not or --shallow <SHA-1> lines are + also accepted. @@ -120,7 +121,7 @@ base-name Include unasked-for annotated tags if the object they reference was included in the resulting packfile. This - can be useful to send new tags to native git clients. + can be useful to send new tags to native Git clients. @@ -332,20 +333,32 @@ base-name option only makes sense in conjunction with --stdout. Note: A thin pack violates the packed archive format by omitting -required objects and is thus unusable by git without making it +required objects and is thus unusable by Git without making it self-contained. Use git index-pack --fix-thin (see ) to restore the self-contained property. +--shallow + + + + Optimize a pack that will be provided to a client with a shallow + repository. This option, combined with --thin, can result in a + smaller pack at the cost of speed. + + + + + --delta-base-offset A packed archive can express the base object of a delta as either a 20-byte object name or as an offset in the - stream, but ancient versions of git don't understand the + stream, but ancient versions of Git don't understand the latter. By default, git pack-objects only uses the former format for better compatibility. This option allows the command to use the latter format for @@ -355,7 +368,7 @@ self-contained. Use git index-pack --fix-thin Note: Porcelain commands such as git gc (see ), git repack (see ) pass this option by default -in modern git when they put objects in your repository into pack files. +in modern Git when they put objects in your repository into pack files. So does git bundle (see ) when it creates a bundle. @@ -371,7 +384,7 @@ So does git bundle (see ) w This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. - Specifying 0 will cause git to auto-detect the number of CPU's + Specifying 0 will cause Git to auto-detect the number of CPU's and set the number of threads accordingly. diff --git a/doc/source/en/TortoiseGit/git_doc/git-pack-refs.xml b/doc/source/en/TortoiseGit/git_doc/git-pack-refs.xml index 7919a736f..eeb2a6aea 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-pack-refs.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-pack-refs.xml @@ -35,8 +35,8 @@ file and used if found. Subsequent updates to branches always create new files under $GIT_DIR/refs directory hierarchy. A recommended practice to deal with a repository with too many -refs is to pack its refs with --all --prune once, and -occasionally run git pack-refs --prune. Tags are by +refs is to pack its refs with --all once, and +occasionally run git pack-refs. Tags are by definition stationary and are not expected to change. Branch heads will be packed with the initial pack-refs --all, but only the currently active branch heads will become unpacked, diff --git a/doc/source/en/TortoiseGit/git_doc/git-patch-id.xml b/doc/source/en/TortoiseGit/git_doc/git-patch-id.xml index 1a05b7533..735a6c665 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-patch-id.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-patch-id.xml @@ -13,15 +13,16 @@ SYNOPSIS
-git patch-id < <patch> +git patch-id [--stable | --unstable]
DESCRIPTION -A "patch ID" is nothing but a SHA1 of the diff associated with a patch, with -whitespace and line numbers ignored. As such, it's "reasonably stable", but at -the same time also reasonably unique, i.e., two patches that have the same "patch -ID" are almost guaranteed to be the same thing. +Read a patch from the standard input and compute the patch ID for it. +A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a +patch, with whitespace and line numbers ignored. As such, it's "reasonably +stable", but at the same time also reasonably unique, i.e., two patches that +have the same "patch ID" are almost guaranteed to be the same thing. IOW, you can use this thing to look for likely duplicate commits. When dealing with git diff-tree output, it takes advantage of the fact that the patch is prefixed with the object name of the @@ -34,6 +35,53 @@ This can be used to make a mapping from patch ID to commit ID. +--stable + + + + Use a "stable" sum of hashes as the patch ID. With this option: + + + + +Reordering file diffs that make up a patch does not affect the ID. + In particular, two patches produced by comparing the same two trees + with two different settings for "-O<orderfile>" result in the same + patch ID signature, thereby allowing the computed result to be used + as a key to index some meta-information about the change between + the two trees; + + + + +Result is different from the value produced by git 1.9 and older + or produced when an "unstable" hash (see --unstable below) is + configured - even when used on a diff output taken without any use + of "-O<orderfile>", thereby making existing databases storing such + "unstable" or historical patch-ids unusable. + +This is the default if patchid.stable is set to true. + + + + + + +--unstable + + + + Use an "unstable" hash as the patch ID. With this option, + the result produced is compatible with the patch-id value produced + by git 1.9 and older. Users with pre-existing databases storing + patch-ids produced by git 1.9 and older (who do not deal with reordered + patches) may want to use this option. + +This is the default. + + + + <patch> diff --git a/doc/source/en/TortoiseGit/git_doc/git-peek-remote.xml b/doc/source/en/TortoiseGit/git_doc/git-peek-remote.xml deleted file mode 100644 index 84df2c713..000000000 --- a/doc/source/en/TortoiseGit/git_doc/git-peek-remote.xml +++ /dev/null @@ -1,73 +0,0 @@ - - - - - git-peek-remote(1) - -git-peek-remote(1) - - -NAME -git-peek-remote - List the references in a remote repository - - -SYNOPSIS -
-git peek-remote [--upload-pack=<git-upload-pack>] [<host>:]<directory> -
- - -DESCRIPTION -This command is deprecated; use git ls-remote instead. - - -OPTIONS - - - ---upload-pack=<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. Some - 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, but prefer 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. - - - - - - -GIT -Part of the suite - - diff --git a/doc/source/en/TortoiseGit/git_doc/git-prune-packed.xml b/doc/source/en/TortoiseGit/git_doc/git-prune-packed.xml index 3aafe0d5e..9a82f63bd 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-prune-packed.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-prune-packed.xml @@ -18,7 +18,7 @@ DESCRIPTION -This program searches the $GIT_OBJECT_DIR for all objects that currently +This program searches the $GIT_OBJECT_DIRECTORY for all objects that currently exist in a pack file as well as the independent object directories. All such extra objects are removed. A pack is a collection of objects, individually compressed, with delta diff --git a/doc/source/en/TortoiseGit/git_doc/git-prune.xml b/doc/source/en/TortoiseGit/git_doc/git-prune.xml index 6e1e59b71..84fd606eb 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-prune.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-prune.xml @@ -26,7 +26,9 @@ objects specified on the command line, and prunes all unpacked objects unreachable from any of these head objects from the object database. In addition, it prunes the unpacked objects that are also found in packs by -running git prune-packed. +running git prune-packed. +It also removes entries from .git/shallow that are not reachable by +any ref. Note that unreachable, packed objects will remain. If this is not desired, see . @@ -96,10 +98,10 @@ not desired, see . EXAMPLE -To prune objects not used by your repository nor another that +To prune objects not used by your repository or another that borrows from your repository via its .git/objects/info/alternates: -$ git prune $(cd ../another && $(git rev-parse --all)) +$ git prune $(cd ../another && git rev-parse --all) Notes diff --git a/doc/source/en/TortoiseGit/git_doc/git-pull.xml b/doc/source/en/TortoiseGit/git_doc/git-pull.xml index 4a340de96..41cd44733 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-pull.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-pull.xml @@ -8,7 +8,7 @@ NAME -git-pull - Fetch from and merge with another repository or a local branch +git-pull - Fetch from and integrate with another repository or a local branch SYNOPSIS @@ -38,19 +38,21 @@ as set by --track.master": A---B---C master on origin / - D---E---F---G master + D---E---F---G master + ^ + origin/master in your repository Then "git pull" will fetch and replay the changes from the remote master branch since it diverged from the local master (i.e., E) until its current commit (C) on top of master and record the result in a new commit along with the names of the two parent commits and a log message from the user describing the changes. - A---B---C remotes/origin/master + A---B---C origin/master / \ D---E---F---G---H master See for details, including how conflicts are presented and handled. -In git 1.7.0 or later, to cancel a conflicting merge, use -git reset --merge. Warning: In older versions of git, running git pull +In Git 1.7.0 or later, to cancel a conflicting merge, use +git reset --merge. Warning: In older versions of Git, running git pull with uncommitted changes is discouraged: while possible, it leaves you in a state that may be hard to back out of in the case of a conflict. If any of the remote changes overlap with local uncommitted changes, @@ -60,8 +62,6 @@ pulling or stash them away with . OPTIONS -Options meant for git pull itself and the underlying git merge -must be given before the options meant for git fetch. @@ -100,7 +100,7 @@ must be given before the options meant for git fetch. and ). That might be necessary to get the data needed for merging submodule - commits, a feature git learned in 1.7.3. Notice that the result of a + commits, a feature Git learned in 1.7.3. Notice that the result of a merge will not be checked out in the submodule, "git submodule update" has to be called afterwards to bring the work tree up to date with the merge result. @@ -133,6 +133,9 @@ inspect and further tweak the merge result before committing. --edit +-e + + --no-edit @@ -141,9 +144,7 @@ inspect and further tweak the merge result before committing. further edit the auto-generated merge message, so that the user can explain and justify the merge. The --no-edit option can be used to accept the auto-generated message (this is generally - discouraged). The --edit option is still useful if you are - giving a draft message with the -m option from the command line - and want to edit it in the editor. + discouraged). Older scripts may depend on the historical behaviour of not allowing the user to edit the merge log message. They will see an editor opened when @@ -171,7 +172,8 @@ set to no at the beginning of them. Create a merge commit even when the merge resolves as a - fast-forward. + fast-forward. This is the default behaviour when merging an + annotated (and possibly signed) tag. @@ -232,14 +234,13 @@ merge. - Produce the working tree and index state as if a real - merge happened (except for the merge information), - but do not actually make a commit or - move the HEAD, nor record $GIT_DIR/MERGE_HEAD to - cause the next git commit command to create a merge - commit. This allows you to create a single commit on - top of the current branch whose effect is the same as - merging another branch (or more in case of an octopus). + Produce the working tree and index state as if a real merge + happened (except for the merge information), but do not actually + make a commit, move the HEAD, or record $GIT_DIR/MERGE_HEAD + (to cause the next git commit command to create a merge + commit). This allows you to create a single commit on top of + the current branch whose effect is the same as merging another + branch (or more in case of an octopus). With --no-squash perform the merge and commit the result. This option can be used to override --squash. @@ -278,78 +279,67 @@ option can be used to override --squash. ---summary +--verify-signatures ---no-summary +--no-verify-signatures - Synonyms to --stat and --no-stat; these are deprecated and will be - removed in the future. + Verify that the commits being merged have good and trusted GPG signatures + and abort the merge in case they do not. --q - - ---quiet - - - - Operate quietly. Implies --no-progress. - - - - - --v +--summary ---verbose +--no-summary - Be verbose. + Synonyms to --stat and --no-stat; these are deprecated and will be + removed in the future. ---progress - - ---no-progress +--allow-unrelated-histories - Turn progress on/off explicitly. If neither is specified, - progress is shown if standard error is connected to a terminal. - Note that not all merge strategies may support progress - reporting. + By default, git merge command refuses to merge histories + that do not share a common ancestor. This option can be + used to override this safety when merging histories of two + projects that started their lives independently. As that is + a very rare occasion, no configuration variable to enable + this by default exists and will not be added. - - -r ---rebase +--rebase[=false|true|preserve|interactive] - Rebase the current branch on top of the upstream branch after - fetching. If there is a remote-tracking branch corresponding to - the upstream branch and the upstream branch was rebased since last - fetched, the rebase uses that information to avoid rebasing - non-local changes. + When true, rebase the current branch on top of the upstream + branch after fetching. If there is a remote-tracking branch + corresponding to the upstream branch and the upstream branch + was rebased since last fetched, the rebase uses that information + to avoid rebasing non-local changes. -See pull.rebase, branch.<name>.rebase and branch.autosetuprebase in +When set to preserve, rebase with the --preserve-merges option passed +to git rebase so that locally created merge commits will not be flattened. +When false, merge the current branch into the upstream branch. +When interactive, enable the interactive mode of rebase. +See pull.rebase, branch.<name>.rebase and branch.autoSetupRebase in if you want to make git pull always use --rebase instead of merging. This is a potentially dangerous mode of operation. @@ -368,6 +358,23 @@ unless you have read carefully. + + +--autostash + + +--no-autostash + + + + Before starting rebase, stash local modifications away (see + ) if needed, and apply the stash when + done. --no-autostash is useful to override the rebase.autoStash + configuration variable (see ). + +This option is only valid when "--rebase" is used. + +
@@ -404,10 +411,38 @@ unless you have read carefully. - Deepen the history of a shallow repository created by - git clone with --depth=<depth> option (see ) - to the specified number of commits from the tip of each remote - branch history. Tags for the deepened commits are not fetched. + Limit fetching to the specified number of commits from the tip of + each remote branch history. If fetching to a shallow repository + created by git clone with --depth=<depth> option (see + ), deepen or shorten the history to the specified + number of commits. Tags for the deepened commits are not fetched. + + + + + +--unshallow + + + + If the source repository is complete, convert a shallow + repository to a complete one, removing all the limitations + imposed by shallow repositories. + +If the source repository is shallow, fetch as much as possible so that +the current repository has the same history as the source repository. + + + + +--update-shallow + + + + By default when fetching from a shallow repository, + git fetch refuses refs that require updating + .git/shallow. This option updates .git/shallow and accept such + refs. @@ -450,7 +485,7 @@ unless you have read carefully.. @@ -501,6 +536,32 @@ unless you have read carefully. +-4 + + +--ipv4 + + + + Use IPv4 addresses only, ignoring IPv6 addresses. + + + + + +-6 + + +--ipv6 + + + + Use IPv6 addresses only, ignoring IPv4 addresses. + + + + + <repository> @@ -518,67 +579,50 @@ unless you have read carefully. - The format of a <refspec> parameter is an optional plus - +, followed by the source ref <src>, followed - by a colon :, followed by the destination ref <dst>. + Specifies which refs to fetch and which local refs to update. + When no <refspec>s appear on the command line, the refs to fetch + are read from remote.<repository>.fetch variables instead + (see ). +The format of a <refspec> parameter is an optional plus ++, followed by the source ref <src>, followed +by a colon :, followed by the destination ref <dst>. +The colon can be omitted when <dst> is empty. +tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; +it requests fetching everything up to the given tag. The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast-forwarded using <src>. If the optional plus + is used, the local ref is updated even if it does not result in a fast-forward update. -If the remote branch from which you want to pull is -modified in non-linear ways such as being rewound and -rebased frequently, then a pull will attempt a merge with -an older version of itself, likely conflict, and fail. -It is under these conditions that you would want to use -the + sign to indicate non-fast-forward updates will -be needed. There is currently no easy way to determine -or declare that a branch will be made available in a -repository with this behavior; the pulling user simply +When the remote branch you want to fetch is known to +be rewound and rebased regularly, it is expected that +its new tip will not be descendant of its previous tip +(as stored in your remote-tracking branch the last time +you fetched). You would want +to use the + sign to indicate non-fast-forward updates +will be needed for such branches. There is no way to +determine or declare that a branch will be made available +in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch. -You never do your own development on branches that appear -on the right hand side of a <refspec> colon on Pull: lines; -they are to be updated by git fetch. If you intend to do -development derived from a remote branch B, have a Pull: -line to track it (i.e. Pull: B:remote-B), and have a separate -branch my-B to do your development on top of it. The latter -is created by git branch my-B remote-B (or its equivalent git -checkout -b my-B remote-B). Run git fetch to keep track of -the progress of the remote side, and when you see something new -on the remote branch, merge it into your development branch with -git pull . remote-B, while you are on my-B branch. There is a difference between listing multiple <refspec> directly on git pull command line and having multiple -Pull: <refspec> lines for a <repository> and running +remote.<repository>.fetch entries in your configuration +for a <repository> and running a git pull command without any explicit <refspec> parameters. -<refspec> listed explicitly on the command line are always +<refspec>s listed explicitly on the command line are always merged into the current branch after fetching. In other words, -if you list more than one remote refs, you would be making -an Octopus. While git pull run without any explicit <refspec> -parameter takes default <refspec>s from Pull: lines, it -merges only the first <refspec> found into the current branch, -after fetching all the remote refs. This is because making an +if you list more than one remote ref, git pull will create +an Octopus merge. On the other hand, if you do not list any +explicit <refspec> parameter on the command line, git pull +will fetch all the <refspec>s it finds in the +remote.<repository>.fetch configuration and merge +only the first <refspec> found into the current branch. +This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one-go by fetching more than one is often useful. -Some short-cut notations are also supported. - - - -tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; - it requests fetching everything up to the given tag. - - - - -A parameter <ref> without a colon is equivalent to - <ref>: when pulling/fetching, so it merges <ref> into the current - branch without storing the remote branch anywhere locally - - - @@ -591,9 +635,10 @@ address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. Git supports ssh, git, http, and https protocols (in addition, ftp, -and ftps can be used for fetching and rsync can be used for fetching -and pushing, but these are inefficient and deprecated; do not use -them). +and ftps can be used for fetching, but this is inefficient and +deprecated; do not use it). +The native transport (i.e. git:// URL) does no authentication and +should be used with caution on unsecured networks. The following syntaxes may be used with them: @@ -616,11 +661,6 @@ http[s]://host.xz[:port]/path/to/repo.git/ ftp[s]://host.xz[:port]/path/to/repo.git/ - - -rsync://host.xz/path/to/repo.git/ - - An alternative scp-like syntax may also be used with the ssh protocol: @@ -630,6 +670,11 @@ rsync://host.xz/path/to/repo.git/ +This syntax is only recognized if there are no slashes before the +first colon. This helps differentiate a local path that contains a +colon. For example the local path foo:bar could be specified as an +absolute path or ./foo:bar to avoid being misinterpreted as an ssh +url. The ssh and git protocols additionally support ~username expansion: @@ -648,7 +693,7 @@ git://host.xz[:port]/~[user]/path/to/repo.git/ -For local repositories, also supported by git natively, the following +For local repositories, also supported by Git natively, the following syntaxes may be used: @@ -658,14 +703,14 @@ syntaxes may be used: -file:///path/to/repo.git/ +file:///path/to/repo.git/ These two syntaxes are mostly equivalent, except when cloning, when the former implies --local option. See for details. -When git doesn't know how to handle a certain transport protocol, it +When Git doesn't know how to handle a certain transport protocol, it attempts to use the remote-<transport> remote helper, if one exists. To explicitly request a remote helper, the following syntax may be used: @@ -678,7 +723,7 @@ may be used: where <address> may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being -invoked. See for details. +invoked. See for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you use will be rewritten into URLs that work), you can create a @@ -709,7 +754,7 @@ of a URL as <repository> argument: -a remote in the git configuration file: $GIT_DIR/config, +a remote in the Git configuration file: $GIT_DIR/config, @@ -778,10 +823,10 @@ refspecs, if you don't provide one on the command line. MERGE STRATEGIES -The merge mechanism (git-merge and git-pull commands) allows the +The merge mechanism (git merge and git pull commands) allows the backend merge strategies to be chosen with -s option. Some strategies can also take their own options, which can be passed by giving -X<option> -arguments to git-merge and/or git-pull. +arguments to git merge and/or git pull. @@ -809,7 +854,7 @@ recursive merged tree of the common ancestors and uses that as the reference tree for the 3-way merge. This has been reported to result in fewer merge conflicts without - causing mis-merges by tests done on actual merge commits + causing mismerges by tests done on actual merge commits taken from Linux 2.6 kernel development history. Additionally this can detect and handle merges involving renames. This is the default merge strategy when @@ -859,6 +904,19 @@ patience +diff-algorithm=[patience|minimal|histogram|myers] + + + + Tells merge-recursive to use a different diff algorithm, which + can help avoid mismerges that occur due to unimportant matching + lines (such as braces from distinct functions). See also + --diff-algorithm. + + + + + ignore-space-change @@ -924,12 +982,34 @@ no-renormalize +no-renames + + + + Turn off rename detection. + See also --no-renames. + + + + + +find-renames[=<n>] + + + + Turn on rename detection, optionally setting the similarity + threshold. This is the default. + See also --find-renames. + + + + + rename-threshold=<n> - Controls the similarity threshold used for rename detection. - See also -M. + Deprecated synonym for find-renames=<n>. @@ -994,6 +1074,13 @@ subtree +With the strategies that use 3-way merge (including the default, recursive), +if a change is made on both branches, but later reverted on one of the +branches, that change will be present in the merged result; some people find +this behavior confusing. It occurs because only the heads and the merge base +are considered when performing a merge, not the individual commits. The merge +algorithm therefore considers the reverted change as no change at all, and +substitutes the changed version instead. DEFAULT BEHAVIOUR @@ -1075,7 +1162,7 @@ branches, the same can be done by invoking fetch and merge: $ git merge origin/next -If you tried a pull which resulted in a complex conflicts and +If you tried a pull which resulted in complex conflicts and would want to start over, you can recover with git reset. @@ -1084,7 +1171,7 @@ would want to start over, you can recover with git reset. diff --git a/doc/source/en/TortoiseGit/git_doc/git-push.xml b/doc/source/en/TortoiseGit/git_doc/git-push.xml index 9c174b56f..71a3f09e0 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-push.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-push.xml @@ -13,9 +13,12 @@ SYNOPSIS
-git push [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] - [<repository> [<refspec>…]] +git push [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] + [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-v | --verbose] + [-u | --set-upstream] + [--[no-]signed|--sign=(true|false|if-asked)] + [--force-with-lease[=<refname>[:<expect>]]] + [--no-verify] [<repository> [<refspec>…]]
@@ -25,6 +28,21 @@ necessary to complete the given refs. You can make interesting things happen to a repository every time you push into it, by setting up hooks there. See documentation for . +When the command line does not specify where to push with the +<repository> argument, branch.*.remote configuration for the +current branch is consulted to determine where to push. If the +configuration is missing, it defaults to origin. +When the command line does not specify what to push with <refspec>... +arguments or --all, --mirror, --tags options, the command finds +the default <refspec> by consulting remote.*.push configuration, +and if it is not found, honors push.default configuration to decide +what to push (See for the meaning of push.default). +When neither the command-line nor the configuration specify what to +push, the default behavior is used, which corresponds to the simple +value for push.default: the current branch is pushed to the +corresponding upstream branch, but as a safety measure, the push is +aborted if the upstream branch does not have the same name as the +local one. OPTIONS<anchor id="git-push(1)_OPTIONS" xreflabel="[OPTIONS]"/> @@ -48,37 +66,37 @@ documentation for . + Specify what destination ref to update with what source object. The format of a <refspec> parameter is an optional plus - +, followed by the source ref <src>, followed + +, followed by the source object <src>, followed by a colon :, followed by the destination ref <dst>. - It is used to specify with what <src> object the <dst> ref - in the remote repository is to be updated. If not specified, - the behavior of the command is controlled by the push.default - configuration variable. The <src> is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as master~4 or HEAD (see ). The <dst> tells which ref on the remote side is updated with this push. Arbitrary expressions cannot be used here, an actual ref must -be named. If :<dst> is omitted, the same ref as <src> will be -updated. +be named. +If git push [<repository>] without any <refspec> argument is set to +update some ref at the destination with <src> with +remote.<repository>.push configuration variable, :<dst> part can +be omitted--such a push will update a ref that <src> normally updates +without any <refspec> on the command line. Otherwise, missing +:<dst> means to update the same ref as the <src>. The object referenced by <src> is used to update the <dst> reference -on the remote side, but by default this is only allowed if the -update can fast-forward <dst>. By having the optional leading +, -you can tell git to update the <dst> ref even when the update is not a -fast-forward. This does not attempt to merge <src> into <dst>. See +on the remote side. By default this is only allowed if <dst> is not +a tag (annotated or lightweight), and then only if it can fast-forward +<dst>. By having the optional leading +, you can tell Git to update +the <dst> ref even if it is not allowed by default (e.g., it is not a +fast-forward.) This does not attempt to merge <src> into <dst>. See EXAMPLES below for details. tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>. Pushing an empty <src> allows you to delete the <dst> ref from the remote repository. The special refspec : (or +: to allow non-fast-forward updates) -directs git to push "matching" branches: for every branch that exists on +directs Git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name -already exists on the remote side. This is the default operation mode -if no explicit refspec is found (that is neither on the command line -nor in any Push line of the corresponding remotes file---see below) and -no push.default configuration variable is set. +already exists on the remote side. @@ -87,8 +105,8 @@ no push.default configuration variable is set. - Instead of naming each ref to push, specifies that all - refs under refs/heads/ be pushed. + Push all branches (i.e. refs under refs/heads/); cannot be + used with other <refspec>. @@ -175,6 +193,53 @@ no push.default configuration variable is set. +--follow-tags + + + + Push all the refs that would be pushed without this option, + and also push annotated tags in refs/tags that are missing + from the remote but are pointing at commit-ish that are + reachable from the refs being pushed. This can also be specified + with configuration variable push.followTags. For more + information, see push.followTags in . + + + + + +--[no-]signed + + +--sign=(true|false|if-asked) + + + + GPG-sign the push request to update refs on the receiving + side, to allow it to be checked by the hooks and/or be + logged. If false or --no-signed, no signing will be + attempted. If true or --signed, the push will fail if the + server does not support signed pushes. If set to if-asked, + sign if and only if the server supports signed pushes. The push + will also fail if the actual call to gpg --sign fails. See + for the details on the receiving end. + + + + + +--[no-]atomic + + + + Use an atomic transaction on the remote side if available. + Either all refs are updated, or on error, no refs are updated. + If the server does not support atomic pushes the push will fail. + + + + + --receive-pack=<git-receive-pack> @@ -191,6 +256,57 @@ no push.default configuration variable is set. +--[no-]force-with-lease + + +--force-with-lease=<refname> + + +--force-with-lease=<refname>:<expect> + + + + Usually, "git push" refuses to update a remote ref that is + not an ancestor of the local ref used to overwrite it. + +This option overrides this restriction if the current value of the +remote ref is the expected value. "git push" fails otherwise. +Imagine that you have to rebase what you have already published. +You will have to bypass the "must fast-forward" rule in order to +replace the history you originally published with the rebased history. +If somebody else built on top of your original history while you are +rebasing, the tip of the branch at the remote may advance with her +commit, and blindly pushing with --force will lose her work. +This option allows you to say that you expect the history you are +updating is what you rebased and want to replace. If the remote ref +still points at the commit you specified, you can be sure that no +other people did anything to the ref. It is like taking a "lease" on +the ref without explicitly locking it, and the remote ref is updated +only if the "lease" is still valid. +--force-with-lease alone, without specifying the details, will protect +all remote refs that are going to be updated by requiring their +current value to be the same as the remote-tracking branch we have +for them. +--force-with-lease=<refname>, without specifying the expected value, will +protect the named ref (alone), if it is going to be updated, by +requiring its current value to be the same as the remote-tracking +branch we have for it. +--force-with-lease=<refname>:<expect> will protect the named ref (alone), +if it is going to be updated, by requiring its current value to be +the same as the specified value <expect> (which is allowed to be +different from the remote-tracking branch we have for the refname, +or we do not even have to have such a remote-tracking branch when +this form is used). +Note that all forms other than --force-with-lease=<refname>:<expect> +that specifies the expected current value of the ref explicitly are +still experimental and their semantics may change as we gain experience +with this feature. +"--no-force-with-lease" will cancel all the previous --force-with-lease on the +command line. + + + + -f @@ -200,9 +316,20 @@ no push.default configuration variable is set. 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. This can cause the - remote repository to lose commits; use it with care. + Also, when --force-with-lease option is used, the command refuses + to update a remote ref whose current value does not match + what is expected. +This flag disables these checks, and can cause the remote repository +to lose commits; use it with care. +Note that --force applies to all the refs that are pushed, hence +using it with push.default set to matching or with multiple push +destinations configured with remote.*.push may overwrite refs +other than the current branch (including local refs that are +strictly behind their remote counterpart). To force a push to only +one branch, use a + in front of the refspec to push (e.g git push +origin +master to force a push to the master branch). See the +<refspec>... section above for details. @@ -211,19 +338,9 @@ no push.default configuration variable is set. - This option is only relevant if no <repository> argument is - passed in the invocation. In this case, git push derives the - remote name from the current branch: If it tracks a remote - branch, then that remote repository is pushed to. Otherwise, - the name "origin" is used. For this latter case, this option - can be used to override the name "origin". In other words, - the difference between these two commands + This option is equivalent to the <repository> argument. If both + are specified, the command-line argument takes precedence. -git push public #1 -git push --repo=public #2 -is that #1 always pushes to "public" whereas #2 pushes to "public" -only if the current branch does not track a remote branch. This is -useful if you write an alias or script around git push. @@ -244,10 +361,7 @@ useful if you write an alias or script around git push. ---thin - - ---no-thin +--[no-]thin @@ -301,19 +415,63 @@ useful if you write an alias or script around git push. ---recurse-submodules=check|on-demand +--no-recurse-submodules + + +--recurse-submodules=check|on-demand|no + + + + May be used to make sure all submodule commits used by the + revisions to be pushed are available on a remote-tracking branch. + If check is used Git will verify that all submodule commits that + changed in the revisions to be pushed are available on at least one + remote of the submodule. If any commits are missing the push will + be aborted and exit with non-zero status. If on-demand is used + all submodules that changed in the revisions to be pushed will be + pushed. If on-demand was not able to push all necessary revisions + it will also be aborted and exit with non-zero status. A value of + no or using --no-recurse-submodules can be used to override the + push.recurseSubmodules configuration variable when no submodule + recursion is required. + + + + + +--[no-]verify + + + + Toggle the pre-push hook (see ). The + default is --verify, giving the hook a chance to prevent the + push. With --no-verify, the hook is bypassed completely. + + + + + +-4 + + +--ipv4 - Make sure all submodule commits used by the revisions to be - pushed are available on a remote-tracking branch. If check is - used git will verify that all submodule commits that changed in - the revisions to be pushed are available on at least one remote - of the submodule. If any commits are missing the push will be - aborted and exit with non-zero status. If on-demand is used - all submodules that changed in the revisions to be pushed will - be pushed. If on-demand was not able to push all necessary - revisions it will also be aborted and exit with non-zero status. + Use IPv4 addresses only, ignoring IPv6 addresses. + + + + + +-6 + + +--ipv6 + + + + Use IPv6 addresses only, ignoring IPv4 addresses. @@ -326,9 +484,10 @@ address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent. Git supports ssh, git, http, and https protocols (in addition, ftp, -and ftps can be used for fetching and rsync can be used for fetching -and pushing, but these are inefficient and deprecated; do not use -them). +and ftps can be used for fetching, but this is inefficient and +deprecated; do not use it). +The native transport (i.e. git:// URL) does no authentication and +should be used with caution on unsecured networks. The following syntaxes may be used with them: @@ -351,11 +510,6 @@ http[s]://host.xz[:port]/path/to/repo.git/ ftp[s]://host.xz[:port]/path/to/repo.git/ - - -rsync://host.xz/path/to/repo.git/ - - An alternative scp-like syntax may also be used with the ssh protocol: @@ -365,6 +519,11 @@ rsync://host.xz/path/to/repo.git/ +This syntax is only recognized if there are no slashes before the +first colon. This helps differentiate a local path that contains a +colon. For example the local path foo:bar could be specified as an +absolute path or ./foo:bar to avoid being misinterpreted as an ssh +url. The ssh and git protocols additionally support ~username expansion: @@ -383,7 +542,7 @@ git://host.xz[:port]/~[user]/path/to/repo.git/ -For local repositories, also supported by git natively, the following +For local repositories, also supported by Git natively, the following syntaxes may be used: @@ -393,14 +552,14 @@ syntaxes may be used: -file:///path/to/repo.git/ +file:///path/to/repo.git/ These two syntaxes are mostly equivalent, except when cloning, when the former implies --local option. See for details. -When git doesn't know how to handle a certain transport protocol, it +When Git doesn't know how to handle a certain transport protocol, it attempts to use the remote-<transport> remote helper, if one exists. To explicitly request a remote helper, the following syntax may be used: @@ -413,7 +572,7 @@ may be used: where <address> may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being -invoked. See for details. +invoked. See for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you use will be rewritten into URLs that work), you can create a @@ -444,7 +603,7 @@ of a URL as <repository> argument: -a remote in the git configuration file: $GIT_DIR/config, +a remote in the Git configuration file: $GIT_DIR/config, @@ -514,7 +673,7 @@ refspecs, if you don't provide one on the command line. OUTPUT The output of "git push" depends on the transport method used; this -section describes the output when pushing over the git protocol (either +section describes the output when pushing over the Git protocol (either locally or via ssh). The status of the push is output in tabular form, with each line representing the status of a single ref. Each line is of the form: @@ -714,7 +873,7 @@ so, the changes introduced by commit A will be lost, because everybody will now start building on top of B. The command by default does not allow an update that is not a fast-forward to prevent such loss of history. -If you do not want to lose your work (history from X to B) nor the work by +If you do not want to lose your work (history from X to B) or the work by the other person (history from X to A), you would need to first fetch the history from the repository, create a history that contains changes done by both parties, and push the result back. @@ -767,8 +926,10 @@ a case where you do mean to lose history. - Without additional configuration, works like - git push origin :. + Without additional configuration, pushes the current branch to + the configured upstream (remote.origin.merge configuration + variable) if it has the same name as the current branch, and + errors out without pushing otherwise. The default behavior of this command when no <refspec> is given can be configured by setting the push option of the remote, or the push.default diff --git a/doc/source/en/TortoiseGit/git_doc/git-quiltimport.xml b/doc/source/en/TortoiseGit/git_doc/git-quiltimport.xml index 541679d85..89ee394e2 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-quiltimport.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-quiltimport.xml @@ -13,12 +13,13 @@ SYNOPSIS
-git quiltimport [--dry-run | -n] [--author <author>] [--patches <dir>] +git quiltimport [--dry-run | -n] [--author <author>] [--patches <dir>] + [--series <file>]
DESCRIPTION -Applies a quilt patchset onto the current git branch, preserving +Applies a quilt patchset onto the current Git branch, preserving the patch boundaries, patch order, and patch descriptions present in the quilt patchset. For each patch the code attempts to extract the author from the @@ -27,7 +28,7 @@ specified with --author. If the --author flag was not given the patch description is displayed and the user is asked to interactively enter the author of the patch. If a subject is not found in the patch description the patch name is -preserved as the 1 line subject in the git description. +preserved as the 1 line subject in the Git description. OPTIONS @@ -65,14 +66,26 @@ preserved as the 1 line subject in the git description. - The directory to find the quilt patches and the - quilt series file. + The directory to find the quilt patches. The default for the patch directory is patches or the value of the $QUILT_PATCHES environment variable. + + +--series <file> + + + + The quilt series file. + +The default for the series file is <patches>/series +or the value of the $QUILT_SERIES environment +variable. + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-read-tree.xml b/doc/source/en/TortoiseGit/git_doc/git-read-tree.xml index a4237c65e..97b868f46 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-read-tree.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-read-tree.xml @@ -95,7 +95,7 @@ will be in unmerged state when git read-tree returns. Check if the command would error out, without updating the index - nor the files in the working tree for real. + or the files in the working tree for real. @@ -392,7 +392,7 @@ merge. The different stages represent the "result tree" (stage 0, aka "merged"), the original tree (stage 1, aka "orig"), and the two trees you are trying to merge (stage 2 and 3 respectively). The order of stages 1, 2 and 3 (hence the order of three -<tree-ish> command line arguments) are significant when you +<tree-ish> command-line arguments) are significant when you start a 3-way merge with an index file that is already populated. Here is an outline of how the algorithm works: diff --git a/doc/source/en/TortoiseGit/git_doc/git-rebase.xml b/doc/source/en/TortoiseGit/git_doc/git-rebase.xml index 414dd8286..93f019d19 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-rebase.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-rebase.xml @@ -8,13 +8,13 @@ NAME -git-rebase - Forward-port local commits to the updated upstream head +git-rebase - Reapply commits on top of another base tip SYNOPSIS
git rebase [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>] - [<upstream>] [<branch>] + [<upstream> [<branch>]] git rebase [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>] --root [<branch>] git rebase --continue | --skip | --abort | --edit-todo @@ -26,14 +26,16 @@ git checkout <branch> before doing anything else. Otherwise it remains on the current branch. If <upstream> is not specified, the upstream configured in -branch.<name>.remote and branch.<name>.merge options will be used; see - for details. If you are currently not on any -branch or if the current branch does not have a configured upstream, -the rebase will abort. +branch.<name>.remote and branch.<name>.merge options will be used (see + for details) and the --fork-point option is +assumed. If you are currently not on any branch or if the current +branch does not have a configured upstream, the rebase will abort. All changes made by commits in the current branch but that are not in <upstream> are saved to a temporary area. This is the same set -of commits that would be shown by git log <upstream>..HEAD (or -git log HEAD, if --root is specified). +of commits that would be shown by git log <upstream>..HEAD; or by +git log 'fork_point'..HEAD, if --fork-point is active (see the +description on --fork-point below); or by git log HEAD, if the +--root option is specified. The current branch is reset to <upstream>, or <newbase> if the --onto option was supplied. This has the exact same effect as git reset --hard <upstream> (or <newbase>). ORIG_HEAD is set @@ -65,8 +67,8 @@ followed by git rebase master. When rebase exits remain the checked-out branch. If the upstream branch already contains a change you have made (e.g., because you mailed a patch which was applied upstream), then that commit -will be skipped. For example, running git rebase master` on the -following history (in which A and A introduce the same set of changes, +will be skipped. For example, running git rebase master on the +following history (in which A' and A introduce the same set of changes, but have different committer information): A---B---C topic / @@ -125,7 +127,7 @@ parameter can be any valid commit-ish. In case of conflict, git rebase will stop at the first problematic commit and leave conflict markers in the tree. You can use git diff to locate the markers (<<<<<<) and make edits to resolve the conflict. For each -file you edit, you need to tell git that the conflict has been resolved, +file you edit, you need to tell Git that the conflict has been resolved, typically this would be done with git add <filename> After resolving the conflict manually and updating the index with the @@ -150,7 +152,7 @@ rebase.stat -rebase.autosquash +rebase.autoSquash @@ -158,6 +160,39 @@ rebase.autosquash + + +rebase.autoStash + + + + If set to true enable --autostash option by default. + + + + + +rebase.missingCommitsCheck + + + + If set to "warn", print warnings about removed commits in + interactive mode. If set to "error", print the warnings and + stop the rebase. If set to "ignore", no checking is + done. "ignore" by default. + + + + + +rebase.instructionFormat + + + + Custom commit list format to use during an --interactive rebase. + + + @@ -313,6 +348,21 @@ which makes little sense. +-S[<keyid>] + + +--gpg-sign[=<keyid>] + + + + GPG-sign commits. The keyid argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. + + + + + -q @@ -404,17 +454,36 @@ which makes little sense. - Force the rebase even if the current branch is a descendant - of the commit you are rebasing onto. Normally non-interactive rebase will - exit with the message "Current branch is up to date" in such a - situation. - Incompatible with the --interactive option. + Force a rebase even if the current branch is up-to-date and + the command without --force would return without doing anything. You may find this (or --no-ff with an interactive rebase) helpful after reverting a topic branch merge, as this option recreates the topic branch with fresh commits so it can be remerged successfully without needing to "revert the reversion" (see the -link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). + + + + +--fork-point + + +--no-fork-point + + + + Use reflog to find a better common ancestor between <upstream> + and <branch> when calculating which commits have been + introduced by <branch>. + +When --fork-point is active, fork_point will be used instead of +<upstream> to calculate the set of commits to rebase, where +fork_point is the result of git merge-base --fork-point <upstream> +<branch> command (see ). If fork_point +ends up being empty, the <upstream> will be used as a fallback. +If either <upstream> or --root is given on the command line, then the +default is --no-fork-point, otherwise the default is --fork-point. @@ -460,6 +529,9 @@ link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). user edit that list before rebasing. This mode can also be used to split commits (see SPLITTING COMMITS below). +The commit list format can be changed by setting the configuration option +rebase.instructionFormat. A customized instruction format will automatically +have the long commit hash prepended to the format. @@ -471,7 +543,9 @@ link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). - Instead of ignoring merges, try to recreate them. + Recreate merge commits instead of flattening the history by replaying + commits a merge commit introduces. Merge conflict resolutions or manual + amendments to merge commits are not preserved. This uses the --interactive machinery internally, but combining it with the --interactive option explicitly is generally not a good @@ -491,8 +565,6 @@ idea unless you know what you are doing (see BUGS below). final history. <cmd> will be interpreted as one or more shell commands. -This option can only be used with the --interactive option -(see INTERACTIVE MODE below). You may execute several commands by either using one instance of --exec with several commands: git rebase -i --exec "cmd1 && cmd2 && ..." @@ -501,6 +573,8 @@ with several commands: If --autosquash is used, "exec" lines will not be appended for the intermediate commits, and will only appear at the end of each squash/fixup series. +This uses the --interactive machinery internally, but it can be run +without an explicit --interactive. @@ -534,16 +608,35 @@ squash/fixup series. the same …, automatically modify the todo list of rebase -i so that the commit marked for squashing comes right after the commit to be modified, and change the action of the moved - commit from pick to squash (or fixup). + commit from pick to squash (or fixup). Ignores subsequent + "fixup! " or "squash! " after the first, in case you referred to an + earlier fixup/squash with git commit --fixup/--squash. This option is only valid when the --interactive option is used. If the --autosquash option is enabled by default using the -configuration variable rebase.autosquash, this option can be +configuration variable rebase.autoSquash, this option can be used to override and disable this setting. +--autostash + + +--no-autostash + + + + Automatically create a temporary stash before the operation + begins, and apply it after the operation ends. This means + that you can run rebase on a dirty worktree. However, use + with care: the final stash application after a successful + rebase might result in non-trivial conflicts. + + + + + --no-ff @@ -556,17 +649,17 @@ used to override and disable this setting. You may find this helpful after reverting a topic branch merge, as this option recreates the topic branch with fresh commits so it can be remerged successfully without needing to "revert the reversion" (see the -link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). MERGE STRATEGIES -The merge mechanism (git-merge and git-pull commands) allows the +The merge mechanism (git merge and git pull commands) allows the backend merge strategies to be chosen with -s option. Some strategies can also take their own options, which can be passed by giving -X<option> -arguments to git-merge and/or git-pull. +arguments to git merge and/or git pull. @@ -594,7 +687,7 @@ recursive merged tree of the common ancestors and uses that as the reference tree for the 3-way merge. This has been reported to result in fewer merge conflicts without - causing mis-merges by tests done on actual merge commits + causing mismerges by tests done on actual merge commits taken from Linux 2.6 kernel development history. Additionally this can detect and handle merges involving renames. This is the default merge strategy when @@ -644,6 +737,19 @@ patience +diff-algorithm=[patience|minimal|histogram|myers] + + + + Tells merge-recursive to use a different diff algorithm, which + can help avoid mismerges that occur due to unimportant matching + lines (such as braces from distinct functions). See also + --diff-algorithm. + + + + + ignore-space-change @@ -709,12 +815,34 @@ no-renormalize +no-renames + + + + Turn off rename detection. + See also --no-renames. + + + + + +find-renames[=<n>] + + + + Turn on rename detection, optionally setting the similarity + threshold. This is the default. + See also --find-renames. + + + + + rename-threshold=<n> - Controls the similarity threshold used for rename detection. - See also -M. + Deprecated synonym for find-renames=<n>. @@ -779,6 +907,13 @@ subtree +With the strategies that use 3-way merge (including the default, recursive), +if a change is made on both branches, but later reverted on one of the +branches, that change will be present in the merged result; some people find +this behavior confusing. It occurs because only the heads and the merge base +are considered when performing a merge, not the individual commits. The merge +algorithm therefore considers the reverted change as no change at all, and +substitutes the changed version instead. NOTES @@ -874,6 +1009,8 @@ the files and/or the commit message, amend the commit, and continue rebasing. If you just want to edit the commit message for a commit, replace the command "pick" with the command "reword". +To drop a commit, replace the command "pick" with "drop", or just +delete the matching line. If you want to fold two or more commits into one, replace the command "pick" for the second and subsequent commits with "squash" or "fixup". If the commits had different authors, the folded commit will be diff --git a/doc/source/en/TortoiseGit/git_doc/git-receive-pack.xml b/doc/source/en/TortoiseGit/git_doc/git-receive-pack.xml index ab5e87432..cbe298a0a 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-receive-pack.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-receive-pack.xml @@ -61,6 +61,139 @@ each refname are the object names for the refname before and after the update. Refs to be created will have sha1-old equal to 0{40}, while refs to be deleted will have sha1-new equal to 0{40}, otherwise sha1-old and sha1-new should be valid objects in the repository. +When accepting a signed push (see ), the signed +push certificate is stored in a blob and an environment variable +GIT_PUSH_CERT can be consulted for its object name. See the +description of post-receive hook for an example. In addition, the +certificate is verified using GPG and the result is exported with +the following environment variables: + + + +GIT_PUSH_CERT_SIGNER + + + + The name and the e-mail address of the owner of the key that + signed the push certificate. + + + + + +GIT_PUSH_CERT_KEY + + + + The GPG key ID of the key that signed the push certificate. + + + + + +GIT_PUSH_CERT_STATUS + + + + The status of GPG verification of the push certificate, + using the same mnemonic as used in %G? format of git log + family of commands (see ). + + + + + +GIT_PUSH_CERT_NONCE + + + + The nonce string the process asked the signer to include + in the push certificate. If this does not match the value + recorded on the "nonce" header in the push certificate, it + may indicate that the certificate is a valid one that is + being replayed from a separate "git push" session. + + + + + +GIT_PUSH_CERT_NONCE_STATUS + + + + + +UNSOLICITED + + + + "git push --signed" sent a nonce when we did not ask it to + send one. + + + + + +MISSING + + + + "git push --signed" did not send any nonce header. + + + + + +BAD + + + + "git push --signed" sent a bogus nonce. + + + + + +OK + + + + "git push --signed" sent the nonce we asked it to send. + + + + + +SLOP + + + + "git push --signed" sent a nonce different from what we + asked it to send now, but in a previous session. See + GIT_PUSH_CERT_NONCE_SLOP environment variable. + + + + + + + + +GIT_PUSH_CERT_NONCE_SLOP + + + + "git push --signed" sent a nonce different from what we + asked it to send now, but in a different session whose + starting time is different by this many seconds from the + current session. Only meaningful when + GIT_PUSH_CERT_NONCE_STATUS says SLOP. + Also read about receive.certNonceSlop variable in + . + + + + This hook is called before any refname is updated and before any fast-forward checks are performed. If the pre-receive hook exits with a non-zero exit status no updates @@ -101,9 +234,13 @@ the update. Refs that were created will have sha1-old equal to 0{40}, while refs that were deleted will have sha1-new equal to 0{40}, otherwise sha1-old and sha1-new should be valid objects in the repository. +The GIT_PUSH_CERT* environment variables can be inspected, just as +in pre-receive hook, after accepting a signed push. Using this hook, it is easy to generate mails describing the updates to the repository. This example script sends one mail message per -ref listing the commits pushed to the repository: +ref listing the commits pushed to the repository, and logs the push +certificates of signed pushes with good signatures to a logger +service: #!/bin/sh # mail out commit update information. while read oval nval ref @@ -118,6 +255,14 @@ do fi | mail -s "Changes to ref $ref" commit-list@mydomain done +# log signed push certificate, if any +if test -n "${GIT_PUSH_CERT-}" && test ${GIT_PUSH_CERT_STATUS} = G +then + ( + echo expected nonce is ${GIT_PUSH_NONCE} + git cat-file blob ${GIT_PUSH_CERT} + ) | mail -s "push certificate from $GIT_PUSH_CERT_SIGNER" push-log@mydomain +fi exit 0 The exit code from this hook invocation is ignored, however a non-zero exit code will generate an error message. diff --git a/doc/source/en/TortoiseGit/git_doc/git-reflog.xml b/doc/source/en/TortoiseGit/git_doc/git-reflog.xml dissimilarity index 63% index 2394004bd..86d983eea 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-reflog.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-reflog.xml @@ -1,147 +1,188 @@ - - - - - git-reflog(1) - -git-reflog(1) - - -NAME -git-reflog - Manage reflog information - - -SYNOPSIS -
-git reflog <subcommand> <options> -
- - -DESCRIPTION -The command takes various subcommands, and different options -depending on the subcommand: -
-git reflog expire [--dry-run] [--stale-fix] [--verbose] - [--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>… -git reflog delete ref@{specifier}… -git reflog [show] [log-options] [<ref>] -
-Reflog is a mechanism to record when the tip of branches are -updated. This command is to manage the information recorded in it. -The subcommand "expire" is used to prune older reflog entries. -Entries older than expire time, or entries older than -expire-unreachable time and not reachable from the current -tip, are removed from the reflog. This is typically not used -directly by the end users -- instead, see . -The subcommand "show" (which is also the default, in the absence of any -subcommands) will take all the normal log options, and show the log of -the reference provided in the command-line (or HEAD, by default). -The reflog will cover all recent actions (HEAD reflog records branch switching -as well). It is an alias for git log -g --abbrev-commit --pretty=oneline; -see . -The reflog is useful in various git commands, to specify the old value -of a reference. For example, HEAD@{2} means "where HEAD used to be -two moves ago", master@{one.week.ago} means "where master used to -point to one week ago", and so on. See for -more details. -To delete single entries from the reflog, use the subcommand "delete" -and specify the exact entry (e.g. "git reflog delete master@{2}"). - - -OPTIONS - - - ---stale-fix - - - - This revamps the logic -- the definition of "broken commit" - becomes: a commit that is not reachable from any of the refs and - there is a missing object among the commit, tree, or blob - objects reachable from it that is not reachable from any of the - refs. - -This computation involves traversing all the reachable objects, i.e. it -has the same cost as git prune. Fortunately, once this is run, we -should not have to ever worry about missing objects, because the current -prune and pack-objects know about reflogs and protect objects referred by -them. - - - - ---expire=<time> - - - - Entries older than this time are pruned. Without the - option it is taken from configuration gc.reflogExpire, - which in turn defaults to 90 days. - - - - - ---expire-unreachable=<time> - - - - Entries older than this time and not reachable from - the current tip of the branch are pruned. Without the - option it is taken from configuration - gc.reflogExpireUnreachable, which in turn defaults to - 30 days. - - - - - ---all - - - - Instead of listing <refs> explicitly, prune all refs. - - - - - ---updateref - - - - Update the ref with the sha1 of the top reflog entry (i.e. - <ref>@{0}) after expiring or deleting. - - - - - ---rewrite - - - - While expiring or deleting, adjust each reflog entry to ensure - that the old sha1 field points to the new sha1 field of the - previous entry. - - - - - ---verbose - - - - Print extra information on screen. - - - - - - -GIT -Part of the suite - - + + + + + git-reflog(1) + +git-reflog(1) + + +NAME +git-reflog - Manage reflog information + + +SYNOPSIS +
+git reflog <subcommand> <options> +
+ + +DESCRIPTION +The command takes various subcommands, and different options +depending on the subcommand: +
+git reflog [show] [log-options] [<ref>] +git reflog expire [--expire=<time>] [--expire-unreachable=<time>] + [--rewrite] [--updateref] [--stale-fix] + [--dry-run] [--verbose] [--all | <refs>…] +git reflog delete [--rewrite] [--updateref] + [--dry-run] [--verbose] ref@{specifier}… +git reflog exists <ref> +
+Reference logs, or "reflogs", record when the tips of branches and +other references were updated in the local repository. Reflogs are +useful in various Git commands, to specify the old value of a +reference. For example, HEAD@{2} means "where HEAD used to be two +moves ago", master@{one.week.ago} means "where master used to point +to one week ago in this local repository", and so on. See + for more details. +This command manages the information recorded in the reflogs. +The "show" subcommand (which is also the default, in the absence of +any subcommands) shows the log of the reference provided in the +command-line (or HEAD, by default). The reflog covers all recent +actions, and in addition the HEAD reflog records branch switching. +git reflog show is an alias for git log -g --abbrev-commit +--pretty=oneline; see for more information. +The "expire" subcommand prunes older reflog entries. Entries older +than expire time, or entries older than expire-unreachable time +and not reachable from the current tip, are removed from the reflog. +This is typically not used directly by end users -- instead, see +. +The "delete" subcommand deletes single entries from the reflog. Its +argument must be an exact entry (e.g. "git reflog delete +master@{2}"). This subcommand is also typically not used directly by +end users. +The "exists" subcommand checks whether a ref has a reflog. It exits +with zero status if the reflog exists, and non-zero status if it does +not. + + +OPTIONS +
+Options for <emphasis>show</emphasis> +git reflog show accepts any of the options accepted by git log. +
+
+Options for <emphasis>expire</emphasis> + + + +--all + + + + Process the reflogs of all references. + + + + + +--expire=<time> + + + + Prune entries older than the specified time. If this option is + not specified, the expiration time is taken from the + configuration setting gc.reflogExpire, which in turn + defaults to 90 days. --expire=all prunes entries regardless + of their age; --expire=never turns off pruning of reachable + entries (but see --expire-unreachable). + + + + + +--expire-unreachable=<time> + + + + Prune entries older than <time> that are not reachable from + the current tip of the branch. If this option is not + specified, the expiration time is taken from the configuration + setting gc.reflogExpireUnreachable, which in turn defaults + to 30 days. --expire-unreachable=all prunes unreachable + entries regardless of their age; --expire-unreachable=never + turns off early pruning of unreachable entries (but see + --expire). + + + + + +--updateref + + + + Update the reference to the value of the top reflog entry (i.e. + <ref>@{0}) if the previous top entry was pruned. (This + option is ignored for symbolic references.) + + + + + +--rewrite + + + + If a reflog entry's predecessor is pruned, adjust its "old" + SHA-1 to be equal to the "new" SHA-1 field of the entry that + now precedes it. + + + + + +--stale-fix + + + + Prune any reflog entries that point to "broken commits". A + broken commit is a commit that is not reachable from any of + the reference tips and that refers, directly or indirectly, to + a missing commit, tree, or blob object. + +This computation involves traversing all the reachable objects, i.e. it +has the same cost as git prune. It is primarily intended to fix +corruption caused by garbage collecting using older versions of Git, +which didn't protect objects referred to by reflogs. + + + + +-n + + +--dry-run + + + + Do not actually prune any entries; just show what would have + been pruned. + + + + + +--verbose + + + + Print extra information on screen. + + + + +
+
+Options for <emphasis>delete</emphasis> +git reflog delete accepts options --updateref, --rewrite, -n, +--dry-run, and --verbose, with the same meanings as when they are +used with expire. +
+ + +GIT +Part of the suite + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-remote-ext.xml b/doc/source/en/TortoiseGit/git_doc/git-remote-ext.xml index d3f71195e..7bb1ca746 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-remote-ext.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-remote-ext.xml @@ -19,7 +19,7 @@ DESCRIPTION This remote helper uses the specified <command> to connect -to a remote git server. +to a remote Git server. Data written to stdin of the specified <command> is assumed to be sent to a git:// server, git-upload-pack, git-receive-pack or git-upload-archive (depending on situation), and data read @@ -55,7 +55,7 @@ the same service. Replaced with name (receive-pack, upload-pack, or - upload-archive) of the service git wants to invoke. + upload-archive) of the service Git wants to invoke. @@ -67,7 +67,7 @@ the same service. Replaced with long name (git-receive-pack, git-upload-pack, or git-upload-archive) of the service - git wants to invoke. + Git wants to invoke. @@ -145,7 +145,7 @@ GIT_EXT_SERVICE_NOPREFIX EXAMPLES: -This remote helper is transparently used by git when +This remote helper is transparently used by Git when you use commands such as "git fetch <URL>", "git clone <URL>", , "git push <URL>" or "git remote add <nick> <URL>", where <URL> begins with ext::. Examples: @@ -168,7 +168,7 @@ begins with ext::. Examples: - Represents repository with path /somerepo accessable over + Represents repository with path /somerepo accessible over git protocol at abstract namespace address /git-server. @@ -196,7 +196,7 @@ begins with ext::. Examples: Represents a repository with path /repo accessed using the helper program "git-server-alias foo". The hostname for the remote server passed in the protocol stream will be "foo" - (this allows multiple virtual git servers to share a + (this allows multiple virtual Git servers to share a link-level address). @@ -210,7 +210,7 @@ begins with ext::. Examples: Represents a repository with path /repo with spaces accessed using the helper program "git-server-alias foo". The hostname for the remote server passed in the protocol stream will be "foo" - (this allows multiple virtual git servers to share a + (this allows multiple virtual Git servers to share a link-level address). @@ -230,10 +230,9 @@ begins with ext::. Examples: - -Documentation -Documentation by Ilari Liusvaara, Jonathan Nieder and the git list -<git@vger.kernel.org> + +SEE ALSO + GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-remote-fd.xml b/doc/source/en/TortoiseGit/git_doc/git-remote-fd.xml index cf0e9d481..42101351e 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-remote-fd.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-remote-fd.xml @@ -16,13 +16,13 @@ DESCRIPTION -This helper uses specified file descriptors to connect to a remote git server. +This helper uses specified file descriptors to connect to a remote Git server. This is not meant for end users but for programs and scripts calling git fetch, push or archive. If only <infd> is given, it is assumed to be a bidirectional socket connected -to remote git server (git-upload-pack, git-receive-pack or +to remote Git server (git-upload-pack, git-receive-pack or git-upload-achive). If both <infd> and <outfd> are given, they are assumed -to be pipes connected to a remote git server (<infd> being the inbound pipe +to be pipes connected to a remote Git server (<infd> being the inbound pipe and <outfd> being the outbound pipe. It is assumed that any handshaking procedures have already been completed (such as sending service request for git://) before this helper is started. @@ -93,9 +93,9 @@ GIT_TRANSLOOP_DEBUG - -Documentation -Documentation by Ilari Liusvaara and the git list <git@vger.kernel.org> + +SEE ALSO + GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-remote-testgit.xml b/doc/source/en/TortoiseGit/git_doc/git-remote-testgit.xml index 56d082123..14308e031 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-remote-testgit.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-remote-testgit.xml @@ -22,11 +22,11 @@ testcase for the remote-helper functionality, and as an example to show remote-helper authors one possible implementation. The best way to learn more is to read the comments and source code in -git-remote-testgit.py. +git-remote-testgit. SEE ALSO - + GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-remote.xml b/doc/source/en/TortoiseGit/git_doc/git-remote.xml index 18ea747b4..c8a4908dd 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-remote.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-remote.xml @@ -8,22 +8,23 @@ NAME -git-remote - manage set of tracked repositories +git-remote - Manage set of tracked repositories SYNOPSIS
git remote [-v | --verbose] -git remote add [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror=<fetch|push>] <name> <url> +git remote add [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=<fetch|push>] <name> <url> git remote rename <old> <new> git remote remove <name> -git remote set-head <name> (-a | -d | <branch>) +git remote set-head <name> (-a | --auto | -d | --delete | <branch>) git remote set-branches [--add] <name> <branch>… +git remote get-url [--push] [--all] <name> git remote set-url [--push] <name> <newurl> [<oldurl>] git remote set-url --add [--push] <name> <newurl> git remote set-url --delete [--push] <name> <url> -git remote [-v | --verbose] show [-n] <name> -git remote prune [-n | --dry-run] <name> +git remote [-v | --verbose] show [-n] <name>… +git remote prune [-n | --dry-run] <name>… git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)…]
@@ -71,6 +72,8 @@ the remote information is set up. remote repository. With --no-tags option, git fetch <name> does not import tags from the remote repository. +By default, only tags on fetched branches are imported +(see ). With -t <branch> option, instead of the default glob refspec for the remote to track all branches under the refs/remotes/<name>/ namespace, a refspec to track only <branch> @@ -129,8 +132,8 @@ branch. For example, if the default branch for origin is se master, then origin may be specified wherever you would normally specify origin/master. -With -d, the symbolic ref refs/remotes/<name>/HEAD is deleted. -With -a, the remote is queried to determine its HEAD, then the +With -d or --delete, the symbolic ref refs/remotes/<name>/HEAD is deleted. +With -a or --auto, the remote is queried to determine its HEAD, then the symbolic-ref refs/remotes/<name>/HEAD is set to the same branch. e.g., if the remote HEAD is pointed at next, "git remote set-head origin -a" will set the symbolic-ref refs/remotes/origin/HEAD to refs/remotes/origin/next. This will @@ -160,19 +163,38 @@ branches, adds to that list. +get-url + + + +Retrieves the URLs for a remote. Configurations for insteadOf and +pushInsteadOf are expanded here. By default, only the first URL is listed. + +With --push, push URLs are queried rather than fetch URLs. +With --all, all URLs for the remote will be listed. + + + + set-url -Changes URL remote points to. Sets first URL remote points to matching +Changes URLs for the remote. Sets first URL for remote <name> that matches regex <oldurl> (first URL if no <oldurl> is given) to <newurl>. If -<oldurl> doesn't match any URL, error occurs and nothing is changed. +<oldurl> doesn't match any URL, an error occurs and nothing is changed. With --push, push URLs are manipulated instead of fetch URLs. -With --add, instead of changing some URL, new URL is added. -With --delete, instead of changing some URL, all URLs matching -regex <url> are deleted. Trying to delete all non-push URLs is an -error. +With --add, instead of changing existing URLs, new URL is added. +With --delete, instead of changing existing URLs, all URLs matching +regex <url> are deleted for remote <name>. Trying to delete all +non-push URLs is an error. +Note that the push URL and the fetch URL, even though they can +be set differently, must still refer to the same place. What you +pushed to the push URL should be what you would see if you +immediately fetched from the fetch URL. If you are trying to +fetch from one place (e.g. your upstream) and push to another (e.g. +your publishing repository), use two separate remotes. @@ -236,18 +258,25 @@ Add a new remote, fetch, and check out a branch from it $ git remote origin $ git branch -r -origin/master -$ git remote add linux-nfs git://linux-nfs.org/pub/linux/nfs-2.6.git + origin/HEAD -> origin/master + origin/master +$ git remote add staging git://git.kernel.org/.../gregkh/staging.git $ git remote -linux-nfs origin -$ git fetch -* refs/remotes/linux-nfs/master: storing branch 'master' ... - commit: bf81b46 +staging +$ git fetch staging +... +From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging + * [new branch] master -> staging/master + * [new branch] staging-linus -> staging/staging-linus + * [new branch] staging-next -> staging/staging-next $ git branch -r -origin/master -linux-nfs/master -$ git checkout -b nfs linux-nfs/master + origin/HEAD -> origin/master + origin/master + staging/master + staging/staging-linus + staging/staging-next +$ git checkout -b staging staging/master ... diff --git a/doc/source/en/TortoiseGit/git_doc/git-repack.xml b/doc/source/en/TortoiseGit/git_doc/git-repack.xml index 19949087a..edb4a9a7f 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-repack.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-repack.xml @@ -13,12 +13,12 @@ SYNOPSIS
-git repack [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>] +git repack [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [--window=<n>] [--depth=<n>]
DESCRIPTION -This script is used to combine all objects that do not currently +This command is used to combine all objects that do not currently reside in a "pack", into a pack. It can also be used to re-organize existing packs into a single, more efficient pack. A pack is a collection of objects, individually compressed, with @@ -190,6 +190,38 @@ other objects in that pack they already have locally. + + +-b + + +--write-bitmap-index + + + + Write a reachability bitmap index as part of the repack. This + only makes sense when used with -a or -A, as the bitmaps + must be able to refer to all reachable objects. This option + overrides the setting of pack.writeBitmaps. + + + + + +--pack-kept-objects + + + + Include objects in .keep files when repacking. Note that we + still do not delete .keep packs after pack-objects finishes. + This means that we may duplicate objects, but this makes the + option safe to use when there are concurrent pushes or fetches. + This option is generally only useful if you are writing bitmaps + with -b or pack.writeBitmaps, as it ensures that the + bitmapped packfile has the necessary objects. + + + @@ -198,7 +230,7 @@ other objects in that pack they already have locally. git pack-objects; this typically results in slightly smaller packs, but the generated packs are incompatible with versions of Git older than version 1.4.4. If you need to share your repository with such ancient Git -versions, either directly or via the dumb http or rsync protocol, then you +versions, either directly or via the dumb http protocol, then you need to set the configuration variable repack.UseDeltaBaseOffset to "false" and repack. Access from old Git versions over the native protocol is unaffected by this option as the conversion is performed on the fly diff --git a/doc/source/en/TortoiseGit/git_doc/git-replace.xml b/doc/source/en/TortoiseGit/git_doc/git-replace.xml index 9e63d6a6a..7d751cc51 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-replace.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-replace.xml @@ -14,18 +14,24 @@ SYNOPSIS
git replace [-f] <object> <replacement> +git replace [-f] --edit <object> +git replace [-f] --graft <commit> [<parent>…] git replace -d <object>… -git replace -l [<pattern>] +git replace [--format=<format>] [-l [<pattern>]]
DESCRIPTION Adds a replace reference in refs/replace/ namespace. -The name of the replace reference is the SHA1 of the object that is -replaced. The content of the replace reference is the SHA1 of the +The name of the replace reference is the SHA-1 of the object that is +replaced. The content of the replace reference is the SHA-1 of the replacement object. +The replaced object and the replacement object must be of the same type. +This restriction can be bypassed using -f. Unless -f is given, the replace reference must not yet exist. -Replacement references will be used by default by all git commands +There is no other restriction on the replaced and replacement objects. +Merge commits can be replaced by non-merge commits and vice versa. +Replacement references will be used by default by all Git commands except those doing reachability traversal (prune, pack transfer and fsck). It is possible to disable use of replacement references for any @@ -45,6 +51,9 @@ achieve the same effect as the --no-replace-objects option. -f + +--force + If an existing replace ref for the same object exists, it will @@ -56,6 +65,9 @@ achieve the same effect as the --no-replace-objects option. -d + +--delete + Delete existing replace refs for the given objects. @@ -64,8 +76,58 @@ achieve the same effect as the --no-replace-objects option. +--edit <object> + + + + Edit an object's content interactively. The existing content + for <object> is pretty-printed into a temporary file, an + editor is launched on the file, and the result is parsed to + create a new object of the same type as <object>. A + replacement ref is then created to replace <object> with the + newly created object. See for details about + how the editor will be chosen. + + + + + +--raw + + + + When editing, provide the raw object contents rather than + pretty-printed ones. Currently this only affects trees, which + will be shown in their binary form. This is harder to work with, + but can help when repairing a tree that is so corrupted it + cannot be pretty-printed. Note that you may need to configure + your editor to cleanly read and write binary data. + + + + + +--graft <commit> [<parent>…] + + + + Create a graft commit. A new commit is created with the same + content as <commit> except that its parents will be + [<parent>…] instead of <commit>'s parents. A replacement ref + is then created to replace <commit> with the newly created + commit. See contrib/convert-grafts-to-replace-refs.sh for an + example script based on this option that can convert grafts to + replace refs. + + + + + -l <pattern> + +--list <pattern> + List replace refs for objects that match the given pattern (or @@ -75,8 +137,57 @@ achieve the same effect as the --no-replace-objects option. + + +--format=<format> + + + + When listing, use the specified <format>, which can be one of + short, medium and long. When omitted, the format + defaults to short. + + + + +FORMATS +The following format are available: + + + +short: + <replaced sha1> + + + + +medium: + <replaced sha1> → <replacement sha1> + + + + +long: + <replaced sha1> (<replaced type>) → <replacement sha1> (<replacement type>) + + + + + +CREATING REPLACEMENT OBJECTS +, and +, among other git commands, can be used to create +replacement objects from existing objects. The --edit option can +also be used with git replace to create a replacement object by +editing an existing object. +If you want to replace many blobs, trees or commits that are part of a +string of commits, you may just want to create a replacement string of +commits and then only replace the commit at the tip of the target +string of commits with the commit at the tip of the replacement string +of commits. + BUGS Comparing blobs or trees that have been replaced with those that @@ -84,14 +195,17 @@ replace them will not work properly. And using git reset --hard There may be other problems when using git rev-list related to -pending objects. And of course things may break if an object of one -type is replaced by an object of another type (for example a blob -replaced by a commit). +pending objects. SEE ALSO - + + + + + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-repo-config.xml b/doc/source/en/TortoiseGit/git_doc/git-repo-config.xml deleted file mode 100644 index 5a2383471..000000000 --- a/doc/source/en/TortoiseGit/git_doc/git-repo-config.xml +++ /dev/null @@ -1,28 +0,0 @@ - - - - - git-repo-config(1) - -git-repo-config(1) - - -NAME -git-repo-config - Get and set repository or global options - - -SYNOPSIS -
-git repo-config … -
- - -DESCRIPTION -This is a synonym for . Please refer to the -documentation of that command. - - -GIT -Part of the suite - - diff --git a/doc/source/en/TortoiseGit/git_doc/git-request-pull.xml b/doc/source/en/TortoiseGit/git_doc/git-request-pull.xml index 6cfe85dc5..ff2baf0d2 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-request-pull.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-request-pull.xml @@ -18,8 +18,14 @@ DESCRIPTION -Summarizes the changes between two commits to the standard output, and includes -the given URL in the generated summary. +Generate a request asking your upstream project to pull changes into +their tree. The request, printed to the standard output, +begins with the branch description, summarizes +the changes and indicates from where they can be pulled. +The upstream project is expected to have the commit named by +<start> and the output asks it to integrate the changes you made +since that commit, up to the commit named by <end>, by visiting +the repository named by <url>. OPTIONS @@ -30,7 +36,7 @@ the given URL in the generated summary. - Show patch text + Include patch text in the output. @@ -40,7 +46,8 @@ the given URL in the generated summary. - Commit to start at. + Commit to start at. This names a commit that is already in + the upstream history. @@ -50,7 +57,7 @@ the given URL in the generated summary. - URL to include in the summary. + The repository URL to be pulled from. @@ -60,12 +67,35 @@ the given URL in the generated summary. - Commit to end at; defaults to HEAD. + Commit to end at (defaults to HEAD). This names the commit + at the tip of the history you are asking to be pulled. +When the repository named by <url> has the commit at a tip of a +ref that is different from the ref you have locally, you can use the +<local>:<remote> syntax, to have its local name, a colon :, and +its remote name. + +EXAMPLE +Imagine that you built your work on your master branch on top of +the v1.0 release, and want it to be integrated to the project. +First you push that change to your public repository for others to +see: +git push https://git.ko.xz/project master +Then, you run this command: +git request-pull v1.0 https://git.ko.xz/project master +which will produce a request to the upstream, summarizing the +changes between the v1.0 release and your master, to pull it +from your public repository. +If you pushed your change to a branch whose name is different from +the one you have locally, e.g. +git push https://git.ko.xz/project master:for-linus +then you can ask that to be pulled with +git request-pull v1.0 https://git.ko.xz/project master:for-linus + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-rerere.xml b/doc/source/en/TortoiseGit/git_doc/git-rerere.xml index 40b71bdd1..0105976d2 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-rerere.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-rerere.xml @@ -103,7 +103,7 @@ Prune records of conflicted merges that occurred a long time ago. By default, unresolved conflicts older than 15 days and resolved conflicts older than 60 days are pruned. These defaults are controlled via the -gc.rerereunresolved and gc.rerereresolved configuration +gc.rerereUnresolved and gc.rerereResolved configuration variables respectively. diff --git a/doc/source/en/TortoiseGit/git_doc/git-reset.xml b/doc/source/en/TortoiseGit/git_doc/git-reset.xml index 8d6ac9b29..aa2fdc267 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-reset.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-reset.xml @@ -13,26 +13,26 @@ SYNOPSIS
-git reset [-q] [<commit>] [--] <paths>… -git reset (--patch | -p) [<commit>] [--] [<paths>…] -git reset [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>] +git reset [-q] [<tree-ish>] [--] <paths>… +git reset (--patch | -p) [<tree-ish>] [--] [<paths>…] +git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
DESCRIPTION -In the first and second form, copy entries from <commit> to the index. +In the first and second form, copy entries from <tree-ish> to the index. In the third form, set the current branch head (HEAD) to <commit>, optionally -modifying index and working tree to match. The <commit> defaults to HEAD -in all forms. +modifying index and working tree to match. The <tree-ish>/<commit> defaults +to HEAD in all forms. -git reset [-q] [<commit>] [--] <paths>… +git reset [-q] [<tree-ish>] [--] <paths>… This form resets the index entries for all <paths> to their - state at <commit>. (It does not affect the working tree, nor + state at <tree-ish>. (It does not affect the working tree or the current branch.) This means that git reset <paths> is the opposite of git add @@ -47,12 +47,12 @@ working tree in one go. -git reset (--patch | -p) [<commit>] [--] [<paths>…] +git reset (--patch | -p) [<tree-ish>] [--] [<paths>…] Interactively select hunks in the difference between the index - and <commit> (defaults to HEAD). The chosen hunks are applied + and <tree-ish> (defaults to HEAD). The chosen hunks are applied in reverse to the index. This means that git reset -p is the opposite of git add -p, i.e. @@ -78,7 +78,7 @@ section of to learn how to operate the - - Does not touch the index file nor the working tree at all (but + Does not touch the index file or the working tree at all (but resets the head to <commit>, just like all modes do). This leaves all your changed files "Changes to be committed", as git status would put it. @@ -95,6 +95,8 @@ section of to learn how to operate the - are preserved but not marked for commit) and reports what has not been updated. This is the default action. +If -N is specified, removed paths are marked as intent-to-add (see +). @@ -194,7 +196,7 @@ Somebody asks you to pull, and the changes sounds worthy of merging. However, you already dirtied the index (i.e. your index does not match the HEAD commit). But you know the pull you are going -to make does not affect frotz.c nor filfre.c, so you revert the +to make does not affect frotz.c or filfre.c, so you revert the index changes for these two files. Your changes in working tree remain there. diff --git a/doc/source/en/TortoiseGit/git_doc/git-rev-list.xml b/doc/source/en/TortoiseGit/git_doc/git-rev-list.xml index d9bbd3d71..41c2c101c 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-rev-list.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-rev-list.xml @@ -44,13 +44,14 @@ [ --right-only ] [ --cherry-mark ] [ --cherry-pick ] - [ --encoding[=<encoding>] ] + [ --encoding=<encoding> ] [ --(author|committer|grep)=<pattern> ] [ --regexp-ignore-case | -i ] [ --extended-regexp | -E ] [ --fixed-strings | -F ] - [ --date=(local|relative|default|iso|rfc|short) ] - [ [--objects | --objects-edge] [ --unpacked ] ] + [ --date=<format>] + [ [ --objects | --objects-edge | --objects-edge-aggressive ] + [ --unpacked ] ] [ --pretty | --header ] [ --bisect ] [ --bisect-vars ] @@ -59,6 +60,8 @@ [ --reverse ] [ --walk-reflogs ] [ --no-walk ] [ --do-walk ] + [ --count ] + [ --use-bitmap-index ] <commit>… [ -- <paths>… ]
@@ -88,7 +91,7 @@ for merges. The resulting set of commits is the symmetric difference between the two operands. The following two commands are equivalent: $ git rev-list A B --not $(git merge-base --all A B) $ git rev-list A...B -rev-list is a very essential git command, since it +rev-list is a very essential Git command, since it provides the ability to build and traverse commit ancestry graphs. For this reason, it has a lot of different options that enables it to be used by commands as different as git bisect and @@ -216,8 +219,6 @@ ordering and formatting options, such as --reverse.--all-match). -When --show-notes is in effect, the message from the notes as -if it is part of the log message. @@ -226,13 +227,24 @@ if it is part of the log message. - Limit the commits output to ones that match all given --grep, + Limit the commits output to ones that match all given --grep, instead of ones that match at least one. +--invert-grep + + + + Limit the commits output to ones with log message that do not + match the pattern specified with --grep=<pattern>. + + + + + -i @@ -240,7 +252,8 @@ if it is part of the log message. - Match the regexp limiting patterns without regard to letters case. + Match the regular expression limiting patterns without regard to letter + case. @@ -289,7 +302,7 @@ if it is part of the log message. - Consider the limiting patterns to be Perl-compatible regexp. + Consider the limiting patterns to be Perl-compatible regular expressions. Requires libpcre to be compiled in. @@ -340,7 +353,7 @@ if it is part of the log message. - Show only commits which have at least (or at most) that many + Show only commits which have at least (or at most) that many parent commits. In particular, --max-parents=1 is the same as --no-merges, --min-parents=2 is the same as --merges. --max-parents=0 gives all root commits and --min-parents=3 all octopus merges. @@ -362,7 +375,8 @@ parents) and --max-parents=-1 (negative numbers denote no u because merges into a topic branch tend to be only about adjusting to updated upstream from time to time, and this option allows you to ignore the individual commits - brought in to your history by such a merge. + brought in to your history by such a merge. Cannot be + combined with --bisect. @@ -442,6 +456,37 @@ parents) and --max-parents=-1 (negative numbers denote no u +--exclude=<glob-pattern> + + + + Do not include refs matching <glob-pattern> that the next --all, + --branches, --tags, --remotes, or --glob would otherwise + consider. Repetitions of this option accumulate exclusion patterns + up to the next --all, --branches, --tags, --remotes, or + --glob option (other options or arguments do not clear + accumulated patterns). + +The patterns given should not begin with refs/heads, refs/tags, or +refs/remotes when applied to --branches, --tags, or --remotes, +respectively, and they must begin with refs/ when applied to --glob +or --all. If a trailing /* is intended, it must be given +explicitly. + + + + +--reflog + + + + Pretend as if all objects mentioned by reflogs are listed on the + command line as <commit>. + + + + + --ignore-missing @@ -474,7 +519,7 @@ parents) and --max-parents=-1 (negative numbers denote no u is primarily meant to allow the caller to test the exit status to see if a range of objects is fully connected (or not). It is faster than redirecting stdout - to /dev/null as the output does not have to be formatted. + to /dev/null as the output does not have to be formatted. @@ -496,15 +541,15 @@ parents) and --max-parents=-1 (negative numbers denote no u Omit any commit that introduces the same change as - another commit on the "other side" when the set of + another commit on the other side when the set of commits are limited with symmetric difference. For example, if you have two branches, A and B, a usual way to list all commits on only one side of them is with --left-right (see the example below in the description of -the --left-right option). It however shows the commits that were cherry-picked -from the other branch (for example, "3rd on b" may be cherry-picked -from branch A). With this option, such pairs of commits are +the --left-right option). However, it shows the commits that were +cherry-picked from the other branch (for example, 3rd on b may be +cherry-picked from branch A). With this option, such pairs of commits are excluded from the output. @@ -555,9 +600,9 @@ list. reflog entries from the most recent one to older ones. When this option is used you cannot specify commits to exclude (that is, ^commit, commit1..commit2, - nor commit1...commit2 notations cannot be used). + and commit1...commit2 notations cannot be used). -With --pretty format other than oneline (for obvious reasons), +With --pretty format other than oneline (for obvious reasons), this causes the output to have two extra lines of information taken from the reflog. By default, commit@{Nth} notation is used in the output. When the starting commit is specified as @@ -585,8 +630,20 @@ See also . - Output uninteresting commits at the boundary, which are usually - not shown. + Output excluded boundary commits. Boundary commits are + prefixed with -. + + + + + +--use-bitmap-index + + + + Try to speed up the traversal using the pack bitmap index (if + one is available). Note that when traversing with --objects, + trees and blobs will not have their associated path printed. @@ -702,24 +759,24 @@ filtered for foo, they look different and equal, respective In the following, we will always refer to the same example history to illustrate the differences between simplification settings. We assume that you are filtering for a file foo in this commit graph: - .-A---M---N---O---P - / / / / / - I B C D E - \ / / / / - `-------------' -The horizontal line of history A---P is taken to be the first parent of + .-A---M---N---O---P---Q + / / / / / / + I B C D E Y + \ / / / / / + `-------------' X +The horizontal line of history A---Q is taken to be the first parent of each merge. The commits are: I is the initial commit, in which foo exists with contents - "asdf", and a file quux exists with contents "quux". Initial + asdf, and a file quux exists with contents quux. Initial commits are compared to an empty tree, so I is !TREESAME. -In A, foo contains just "foo". +In A, foo contains just foo. @@ -730,27 +787,33 @@ In A, foo contains just "foo". -C does not change foo, but its merge N changes it to "foobar", +C does not change foo, but its merge N changes it to foobar, so it is not TREESAME to any parent. -D sets foo to "baz". Its merge O combines the strings from - N and D to "foobarbaz"; i.e., it is not TREESAME to any parent. +D sets foo to baz. Its merge O combines the strings from + N and D to foobarbaz; i.e., it is not TREESAME to any parent. + + + + +E changes quux to xyzzy, and its merge P combines the + strings to quux xyzzy. P is TREESAME to O, but not to E. -E changes quux to "xyzzy", and its merge P combines the - strings to "quux xyzzy". Despite appearing interesting, P is - TREESAME to all parents. +X is an independent root commit that added a new file side, and Y + modified it. Y is TREESAME to X. Its merge Q added side to P, and + Q is TREESAME to P, but not to Y. rev-list walks backwards through history, including or excluding commits based on whether --full-history and/or parent rewriting -(via --parents or --children) are used. The following settings +(via --parents or --children) are used. The following settings are available. @@ -774,7 +837,7 @@ Default mode available, removed B from consideration entirely. C was considered via N, but is TREESAME. Root commits are compared to an empty tree, so I is !TREESAME. -Parent/child relations are only visible with --parents, but that does +Parent/child relations are only visible with --parents, but that does not affect the commits selected in default mode, so we have shown the parent lines. @@ -791,8 +854,8 @@ parent lines. included, this does not imply that the merge itself is! In the example, we get - I A B N D O -P and M were excluded because they are TREESAME to a parent. E, + I A B N D O P Q +M was excluded because it is TREESAME to both parents. E, C and B were all walked, but only B was !TREESAME, so the others do not appear. Note that without parent rewriting, it is not really possible to talk @@ -812,7 +875,7 @@ them disconnected. Merges are always included. However, their parent list is rewritten: Along each parent, prune away commits that are not included themselves. This results in - .-A---M---N---O---P + .-A---M---N---O---P---Q / / / / / I B / D / \ / / / / @@ -820,7 +883,7 @@ themselves. This results in Compare to --full-history without rewriting above. Note that E was pruned away because it is TREESAME, but the parent list of P was rewritten to contain E's parent I. The same happened for C and -N. Note also that P was included despite being TREESAME. +N, and X, Y and Q. @@ -871,8 +934,9 @@ Set C' to C. Replace each parent P of C' with its simplification P'. In - the process, drop parents that are ancestors of other parents, and - remove duplicates. + the process, drop parents that are ancestors of other parents or that are + root commits TREESAME to an empty tree, and remove duplicates, but take care + to never drop all parents that we are TREESAME to. @@ -890,7 +954,7 @@ If after this parent rewriting, C' is a root or merge commi I B D \ / / `---------' -Note the major differences in N and P over --full-history: +Note the major differences in N, P, and Q over --full-history: @@ -904,6 +968,13 @@ If after this parent rewriting, C' is a root or merge commi removed completely, because it had one parent and is TREESAME. + + +Q's parent list had Y simplified to X. X was then removed, because it + was a TREESAME root. Q was then removed completely, because it had one + parent and is TREESAME. + + @@ -917,9 +988,9 @@ If after this parent rewriting, C' is a root or merge commi Limit the displayed commits to those directly on the ancestry - chain between the "from" and "to" commits in the given commit - range. I.e. only display commits that are ancestor of the "to" - commit, and descendants of the "from" commit. + chain between the from and to commits in the given commit + range. I.e. only display commits that are ancestor of the to + commit and descendants of the from commit. As an example use case, consider the following commit history: D---E-------F @@ -930,7 +1001,7 @@ If after this parent rewriting, C' is a root or merge commi A regular D..M computes the set of commits that are ancestors of M, but excludes the ones that are ancestors of D. This is useful to see what happened to the history leading to M since D, in the sense -that "what does M have that did not exist in D". The result in this +that what does M have that did not exist in D. The result in this example would be all the commits, except A and B (and D itself, of course). When we want to find out what commits in M are contaminated with the @@ -963,16 +1034,13 @@ commits are marked as TREESAME (subject to be simplified away). -Limit output to the one commit object which is roughly halfway between -included and excluded commits. Note that the bad bisection ref -refs/bisect/bad is added to the included commits (if it -exists) and the good bisection refs refs/bisect/good-* are -added to the excluded commits (if they exist). Thus, supposing there -are no refs in refs/bisect/, if + Limit output to the one commit object which is roughly halfway between + included and excluded commits. Note that the bad bisection ref + refs/bisect/bad is added to the included commits (if it + exists) and the good bisection refs refs/bisect/good-* are + added to the excluded commits (if they exist). Thus, supposing there + are no refs in refs/bisect/, if - - - $ git rev-list --bisect foo ^bar ^baz outputs midpoint, the output of the two commands $ git rev-list foo ^midpoint @@ -980,24 +1048,25 @@ are no refs in refs/bisect/, if would be of roughly the same length. Finding the change which introduces a regression is thus reduced to a binary search: repeatedly generate and test new 'midpoint's until the commit chain is of length -one. - +one. Cannot be combined with --first-parent. + + --bisect-vars -This calculates the same as --bisect, except that refs in -refs/bisect/ are not used, and except that this outputs -text ready to be eval'ed by the shell. These lines will assign the -name of the midpoint revision to the variable bisect_rev, and the -expected number of commits to be tested after bisect_rev is tested -to bisect_nr, the expected number of commits to be tested if -bisect_rev turns out to be good to bisect_good, the expected -number of commits to be tested if bisect_rev turns out to be bad to -bisect_bad, and the number of commits we are bisecting right now to -bisect_all. + This calculates the same as --bisect, except that refs in + refs/bisect/ are not used, and except that this outputs + text ready to be eval'ed by the shell. These lines will assign the + name of the midpoint revision to the variable bisect_rev, and the + expected number of commits to be tested after bisect_rev is tested + to bisect_nr, the expected number of commits to be tested if + bisect_rev turns out to be good to bisect_good, the expected + number of commits to be tested if bisect_rev turns out to be bad to + bisect_bad, and the number of commits we are bisecting right now to + bisect_all. @@ -1007,11 +1076,11 @@ number of commits to be tested if bisect_rev turns out to b -This outputs all the commit objects between the included and excluded -commits, ordered by their distance to the included and excluded -commits. Refs in refs/bisect/ are not used. The farthest -from them is displayed first. (This is the only one displayed by ---bisect.) + This outputs all the commit objects between the included and excluded + commits, ordered by their distance to the included and excluded + commits. Refs in refs/bisect/ are not used. The farthest + from them is displayed first. (This is the only one displayed by + --bisect.) This is useful because it makes it easy to choose a good commit to test when you want to avoid to test some of them for some reason (they @@ -1040,6 +1109,17 @@ after all the sorted commit objects, there will be the same text as if +--author-date-order + + + + Show no parents before all of its children are shown, but + otherwise show commits in the author timestamp order. + + + + + --topo-order @@ -1076,7 +1156,7 @@ together.
Object Traversal -These options are mostly targeted for packing of git repositories. +These options are mostly targeted for packing of Git repositories. @@ -1085,9 +1165,9 @@ together. Print the object IDs of any object referenced by the listed - commits. --objects foo ^bar thus means "send me + commits. --objects foo ^bar thus means send me all object IDs which I need to download if I have the commit - object bar, but not foo". + object bar but not foo. @@ -1098,8 +1178,8 @@ together. Similar to --objects, but also print the IDs of excluded - commits prefixed with a "-" character. This is used by - to build "thin" pack, which records + commits prefixed with a - character. This is used by + to build a thin pack, which records objects in deltified form based on objects contained in these excluded commits to reduce network traffic. @@ -1107,6 +1187,30 @@ together. +--objects-edge-aggressive + + + + Similar to --objects-edge, but it tries harder to find excluded + commits at the cost of increased time. This is used instead of + --objects-edge to build thin packs for shallow repositories. + + + + + +--indexed-objects + + + + Pretend as if all trees and blobs used by the index are listed + on the command line. Note that you probably want to use + --objects, too. + + + + + --unpacked @@ -1124,10 +1228,11 @@ together. Only show the given commits, but do not traverse their ancestors. This has no effect if a range is specified. If the argument - "unsorted" is given, the commits are show in the order they were - given on the command line. Otherwise (if "sorted" or no argument - was given), the commits are show in reverse chronological order + unsorted is given, the commits are shown in the order they were + given on the command line. Otherwise (if sorted or no argument + was given), the commits are shown in reverse chronological order by commit time. + Cannot be combined with --graph. @@ -1137,7 +1242,7 @@ together. - Overrides a previous --no-walk. + Overrides a previous --no-walk. @@ -1160,10 +1265,13 @@ more specialized family of commit log tools: , Pretty-print the contents of the commit logs in a given format, where <format> can be one of oneline, short, medium, - full, fuller, email, raw and format:<string>. See - the "PRETTY FORMATS" section for some additional details for each - format. When omitted, the format defaults to medium. + full, fuller, email, raw, format:<string> + and tformat:<string>. When <format> is none of the above, + and has %placeholder in it, it acts as if + --pretty=tformat:<format> were given. +See the "PRETTY FORMATS" section for some additional details for each +format. When =<format> part is omitted, it defaults to medium. Note: you can specify the default pretty format in the repository configuration (see ). @@ -1208,7 +1316,7 @@ people using 80-column terminals. ---encoding[=<encoding>] +--encoding=<encoding> @@ -1216,60 +1324,35 @@ people using 80-column terminals. in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this - defaults to UTF-8. + defaults to UTF-8. Note that if an object claims to be encoded + in X and we are outputting in X, we will output the object + verbatim; this means that invalid sequences in the original + commit may be copied to the output. ---notes[=<ref>] +--expand-tabs=<n> - - - Show the notes (see ) that annotate the - commit, when showing the commit log message. This is the default - for git log, git show and git whatchanged commands when - there is no --pretty, --format nor --oneline option given - on the command line. - -By default, the notes shown are from the notes refs listed in the -core.notesRef and notes.displayRef variables (or corresponding -environment overrides). See for more details. -With an optional <ref> argument, show this notes ref instead of the -default notes ref(s). The ref is taken to be in refs/notes/ if it -is not qualified. -Multiple --notes options can be combined to control which notes are -being displayed. Examples: "--notes=foo" will show only notes from -"refs/notes/foo"; "--notes=foo --notes" will show both notes from -"refs/notes/foo" and from the default notes ref(s). - - - - ---no-notes - - - - Do not show notes. This negates the above --notes option, by - resetting the list of notes refs from which notes are shown. - Options are parsed in the order given on the command line, so e.g. - "--notes --notes=foo --no-notes --notes=bar" will only show notes - from "refs/notes/bar". - - - - ---show-notes[=<ref>] +--expand-tabs ---[no-]standard-notes +--no-expand-tabs - These options are deprecated. Use the above --notes/--no-notes - options instead. + Perform a tab expansion (replace each tab with enough spaces + to fill to the next display column that is multiple of <n>) + in the log message before showing it in the output. + --expand-tabs is a short-hand for --expand-tabs=8, and + --no-expand-tabs is a short-hand for --expand-tabs=0, + which disables tab expansion. +By default, tabs are expanded in pretty formats that indent the log +message by 4 spaces (i.e. medium, which is the default, full, +and fuller). @@ -1295,24 +1378,65 @@ being displayed. Examples: "--notes=foo" will show only notes from ---date=(relative|local|default|iso|rfc|short|raw) +--date=<format> Only takes effect for dates shown in human-readable format, such - as when using "--pretty". log.date config variable sets a default - value for log command's --date option. + as when using --pretty. log.date config variable sets a default + value for the log command's --date option. By default, dates + are shown in the original time zone (either committer's or + author's). If -local is appended to the format (e.g., + iso-local), the user's local time zone is used instead. --date=relative shows dates relative to the current time, -e.g. "2 hours ago". ---date=local shows timestamps in user's local timezone. ---date=iso (or --date=iso8601) shows timestamps in ISO 8601 format. +e.g. 2 hours ago. The -local option cannot be used with +--raw or --relative. +--date=local is an alias for --date=default-local. +--date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like format. +The differences to the strict ISO 8601 format are: + + + +a space instead of the T date/time delimiter + + + + +a space between time and time zone + + + + +no colon between hours and minutes of the time zone + + + +--date=iso-strict (or --date=iso8601-strict) shows timestamps in strict +ISO 8601 format. --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 -format, often found in E-mail messages. ---date=short shows only date but not time, in YYYY-MM-DD format. ---date=raw shows the date in the internal raw git format %s %z format. ---date=default shows timestamps in the original timezone -(either committer's or author's). +format, often found in email messages. +--date=short shows only the date, but not the time, in YYYY-MM-DD format. +--date=raw shows the date in the internal raw Git format %s %z format. +--date=format:... feeds the format ... to your system strftime. +Use --date=format:%c to show the date in your system locale's +preferred format. See the strftime manual for a complete list of +format placeholders. When using -local, the correct syntax is +--date=format-local:.... +--date=default is the default format, and is similar to +--date=rfc2822, with a few exceptions: + + + +there is no comma after the day-of-week + + + + +the time zone is omitted when the local time zone is used + + + @@ -1396,6 +1520,7 @@ format, often found in E-mail messages. on the left hand side of the output. This may cause extra lines to be printed in between commits, in order for the graph history to be drawn properly. + Cannot be combined with --no-walk. This enables parent rewriting, see History Simplification below. This implies the --topo-order option by default, but the @@ -1404,6 +1529,20 @@ format, often found in E-mail messages. +--show-linear-break[=<barrier>] + + + + When --graph is not used, all history branches are flattened + which can make it hard to see that the two consecutive commits + do not belong to a linear branch. This option puts a barrier + in between them in that case. If <barrier> is specified, it + is the string that will be shown instead of the default one. + + + + + --count @@ -1501,11 +1640,14 @@ Subject: [PATCH] <title line> raw The raw format shows the entire commit exactly as -stored in the commit object. Notably, the SHA1s are +stored in the commit object. Notably, the SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and parents information show the -true parent commits, without taking grafts nor history -simplification into account. +true parent commits, without taking grafts or history +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +git log --raw. To get full object names in a raw diff format, +use --no-abbrev. @@ -1558,7 +1700,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%aN: author name (respecting .mailmap, see or ) +%aN: author name (respecting .mailmap, see + or ) @@ -1568,7 +1711,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%aE: author email (respecting .mailmap, see or ) +%aE: author email (respecting .mailmap, see + or ) @@ -1593,7 +1737,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%ai: author date, ISO 8601 format +%ai: author date, ISO 8601-like format + + + + +%aI: author date, strict ISO 8601 format @@ -1603,7 +1752,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%cN: committer name (respecting .mailmap, see or ) +%cN: committer name (respecting .mailmap, see + or ) @@ -1613,12 +1763,13 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%cE: committer email (respecting .mailmap, see or ) +%cE: committer email (respecting .mailmap, see + or ) -%cd: committer date +%cd: committer date (format respects --date= option) @@ -1638,7 +1789,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%ci: committer date, ISO 8601 format +%ci: committer date, ISO 8601-like format + + + + +%cI: committer date, strict ISO 8601 format @@ -1648,6 +1804,11 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff +%D: ref names without the " (", ")" wrapping. + + + + %e: encoding @@ -1673,22 +1834,23 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%N: commit notes +%GG: raw verification message from GPG for a signed commit -%GG: raw verification message from GPG for a signed commit +%G?: show "G" for a Good signature, "B" for a Bad signature, "U" for a good, + untrusted signature and "N" for no signature -%G?: show either "G" for Good or "B" for Bad for a signed commit +%GS: show the name of the signer for a signed commit -%GS: show the name of the signer for a signed commit +%GK: show the key used to sign a signed commit @@ -1708,7 +1870,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%gN: reflog identity name (respecting .mailmap, see or ) +%gN: reflog identity name (respecting .mailmap, see + or ) @@ -1718,7 +1881,8 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%gE: reflog identity email (respecting .mailmap, see or ) +%gE: reflog identity email (respecting .mailmap, see + or ) @@ -1748,7 +1912,12 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff -%C(…): color specification, as described in color.branch.* config option +%C(…): color specification, as described in color.branch.* config option; + adding auto, at the beginning will emit color only when colors are + enabled for log output (by color.diff, color.ui, or --color, and + respecting the auto settings of the former if we are going to a + terminal). auto alone (i.e. %C(auto)) will turn on auto coloring + on the next placeholders until the color is switched again. @@ -1777,14 +1946,49 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff . + + +%<(<N>[,trunc|ltrunc|mtrunc]): make the next placeholder take at + least N columns, padding spaces on the right if necessary. + Optionally truncate at the beginning (ltrunc), the middle (mtrunc) + or the end (trunc) if the output is longer than N columns. + Note that truncating only works correctly with N >= 2. + + + + +%<|(<N>): make the next placeholder take at least until Nth + columns, padding spaces on the right if necessary + + + + +%>(<N>), %>|(<N>): similar to %<(<N>), %<|(<N>) + respectively, but padding spaces on the left + + + + +%>>(<N>), %>>|(<N>): similar to %>(<N>), %>|(<N>) + respectively, except that if the next placeholder takes more spaces + than given and there are spaces on its left, use those spaces + + + + +%><(<N>), %><|(<N>): similar to % <(<N>), %<|(<N>) + respectively, but padding both sides (i.e. the text is centered) + + Some placeholders may depend on other options given to the revision traversal engine. For example, the %g* reflog options will insert an empty string unless we are traversing reflog entries (e.g., by -git log -g). The %d placeholder will use the "short" decoration -format if --decorate was not already provided on the command line. +git log -g). The %d and %D placeholders will use the "short" +decoration format if --decorate was not already provided on the command +line. If you add a + (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string. diff --git a/doc/source/en/TortoiseGit/git_doc/git-rev-parse.xml b/doc/source/en/TortoiseGit/git_doc/git-rev-parse.xml index ef53f2ca0..bc21cea14 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-rev-parse.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-rev-parse.xml @@ -18,7 +18,7 @@ DESCRIPTION -Many git porcelainish commands take mixture of flags +Many Git porcelainish commands take mixture of flags (i.e. parameters that begin with a dash -) and parameters meant for the underlying git rev-list command they use internally and flags and parameters for the other commands they use @@ -27,6 +27,9 @@ distinguish between them. OPTIONS +
+Operation Modes +Each of these options must appear first on the command line. @@ -40,6 +43,23 @@ distinguish between them. +--sq-quote + + + + Use git rev-parse in shell quoting mode (see SQ-QUOTE + section below). In contrast to the --sq option below, this + mode does only quoting. Nothing else is done to command input. + + + + +
+
+Options for --parseopt + + + --keep-dashdash @@ -63,16 +83,20 @@ distinguish between them. ---sq-quote +--stuck-long - Use git rev-parse in shell quoting mode (see SQ-QUOTE - section below). In contrast to the --sq option below, this - mode does only quoting. Nothing else is done to command input. + Only meaningful in --parseopt mode. Output the options in their + long form if available, and with their arguments stuck. + +
+
+Options for Filtering + --revs-only @@ -115,6 +139,11 @@ distinguish between them. + +
+
+Options for Output + --default <arg> @@ -128,13 +157,42 @@ distinguish between them. +--prefix <arg> + + + + Behave as if git rev-parse was invoked from the <arg> + subdirectory of the working tree. Any relative filenames are + resolved as if they are prefixed by <arg> and will be printed + in that form. + +This can be used to convert arguments to a command run in a subdirectory +so that they can still be used after moving to the top-level of the +repository. For example: +prefix=$(git rev-parse --show-prefix) +cd "$(git rev-parse --show-toplevel)" +eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" + + + + --verify - The parameter given must be usable as a single, valid - object name. Otherwise barf and abort. + Verify that exactly one parameter is provided, and that it + can be turned into a raw 20-byte SHA-1 that can be used to + access the object database. If so, emit it to the standard + output; otherwise, error out. +If you want to make sure that the output actually names an object in +your object database and/or can be used as a specific type of object +you require, you can add the ^{type} peeling operator to the parameter. +For example, git rev-parse "$VAR^{commit}" will make sure $VAR +names an existing object that is a commit-ish (i.e. a commit, or an +annotated tag that points at a commit). To make sure that $VAR +names an existing object of any type, git rev-parse "$VAR^{object}" +can be used. @@ -149,6 +207,7 @@ distinguish between them. Only meaningful in --verify mode. Do not output an error message if the first argument is not a valid object name; instead exit with non-zero status silently. + SHA-1s for valid object names are printed to stdout on success. @@ -182,56 +241,63 @@ distinguish between them. ---symbolic +--abbrev-ref[=(strict|loose)] - Usually the object names are output in SHA1 form (with - possible ^ prefix); this option makes them output in a - form as close to the original input as possible. + A non-ambiguous short name of the objects name. + The option core.warnAmbiguousRefs is used to select the strict + abbreviation mode. ---symbolic-full-name +--short + + +--short=number - This is similar to --symbolic, but it omits input that - are not refs (i.e. branch or tag names; or more - explicitly disambiguating "heads/master" form, when you - want to name the "master" branch when there is an - unfortunately named tag "master"), and show them as full - refnames (e.g. "refs/heads/master"). + Instead of outputting the full SHA-1 values of object names try to + abbreviate them to a shorter unique name. When no length is specified + 7 is used. The minimum length is 4. ---abbrev-ref[=(strict|loose)] +--symbolic - A non-ambiguous short name of the objects name. - The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. + Usually the object names are output in SHA-1 form (with + possible ^ prefix); this option makes them output in a + form as close to the original input as possible. ---disambiguate=<prefix> +--symbolic-full-name - Show every object whose name begins with the given prefix. - The <prefix> must be at least 4 hexadecimal digits long to - avoid listing each and every object in the repository by - mistake. + This is similar to --symbolic, but it omits input that + are not refs (i.e. branch or tag names; or more + explicitly disambiguating "heads/master" form, when you + want to name the "master" branch when there is an + unfortunately named tag "master"), and show them as full + refnames (e.g. "refs/heads/master"). + +
+
+Options for Objects + --all @@ -279,35 +345,52 @@ shown. If the pattern does not contain a globbing character (? ---show-toplevel +--exclude=<glob-pattern> - Show the absolute path of the top-level directory. + Do not include refs matching <glob-pattern> that the next --all, + --branches, --tags, --remotes, or --glob would otherwise + consider. Repetitions of this option accumulate exclusion patterns + up to the next --all, --branches, --tags, --remotes, or + --glob option (other options or arguments do not clear + accumulated patterns). +The patterns given should not begin with refs/heads, refs/tags, or +refs/remotes when applied to --branches, --tags, or --remotes, +respectively, and they must begin with refs/ when applied to --glob +or --all. If a trailing /* is intended, it must be given +explicitly. ---show-prefix +--disambiguate=<prefix> - When the command is invoked from a subdirectory, show the - path of the current directory relative to the top-level - directory. + Show every object whose name begins with the given prefix. + The <prefix> must be at least 4 hexadecimal digits long to + avoid listing each and every object in the repository by + mistake. + +
+
+Options for Files + ---show-cdup +--local-env-vars - When the command is invoked from a subdirectory, show the - path of the top-level directory relative to the current - directory (typically a sequence of "../", or an empty string). + List the GIT_* environment variables that are local to the + repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). + Only the names of the variables are listed, not their value, + even if they are set. @@ -322,12 +405,22 @@ shown. If the pattern does not contain a globbing character (? If $GIT_DIR is not defined and the current directory -is not detected to lie in a git repository or work tree +is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status. +--git-common-dir + + + + Show $GIT_COMMON_DIR if defined, else $GIT_DIR. + + + + + --is-inside-git-dir @@ -360,34 +453,83 @@ print a message to stderr and exit with nonzero status. ---local-env-vars +--resolve-git-dir <path> - List the GIT_* environment variables that are local to the - repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). - Only the names of the variables are listed, not their value, - even if they are set. + Check if <path> is a valid repository or a gitfile that + points at a valid repository, and print the location of the + repository. If <path> is a gitfile then the resolved path + to the real repository is printed. ---short +--git-path <path> + + + Resolve "$GIT_DIR/<path>" and takes other path relocation + variables such as $GIT_OBJECT_DIRECTORY, + $GIT_INDEX_FILE… into account. For example, if + $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse + --git-path objects/abc" returns /foo/bar/abc. + + + + ---short=number +--show-cdup - Instead of outputting the full SHA1 values of object names try to - abbreviate them to a shorter unique name. When no length is specified - 7 is used. The minimum length is 4. + When the command is invoked from a subdirectory, show the + path of the top-level directory relative to the current + directory (typically a sequence of "../", or an empty string). + + + + + +--show-prefix + + + + When the command is invoked from a subdirectory, show the + path of the current directory relative to the top-level + directory. +--show-toplevel + + + + Show the absolute path of the top-level directory. + + + + + +--shared-index-path + + + + Show the path to the shared index file in split index mode, or + empty if not in split-index mode. + + + + +
+
+Other Options + + + --since=datestring @@ -424,24 +566,13 @@ print a message to stderr and exit with nonzero status. - - ---resolve-git-dir <path> - - - - Check if <path> is a valid git-dir or a git-file pointing to a valid - git-dir. If <path> is a valid git-dir the resolved path to git-dir will - be printed. - - - +
 SPECIFYING REVISIONS A revision parameter <rev> typically, but not necessarily, names a -commit object. It uses what is called an extended SHA1 +commit object. It uses what is called an extended SHA-1 syntax. Here are various ways to spell object names. The ones listed near the end of this list name trees and blobs contained in a commit. @@ -452,7 +583,7 @@ blobs contained in a commit. - The full SHA1 object name (40-byte hexadecimal string), or + The full SHA-1 object name (40-byte hexadecimal string), or a leading substring that is unique within the repository. E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the same commit object if there is no other object in @@ -481,7 +612,7 @@ blobs contained in a commit. A symbolic ref name. E.g. master typically means the commit object referenced by refs/heads/master. If you happen to have both heads/master and tags/master, you can - explicitly say heads/master to tell git which one you mean. + explicitly say heads/master to tell Git which one you mean. When ambiguous, a <refname> is disambiguated by taking the first match in the following rules: @@ -530,7 +661,7 @@ when you run git merge. when you run git cherry-pick. Note that any of the refs/* cases above may come either from the $GIT_DIR/refs directory or from the $GIT_DIR/packed-refs file. -While the ref name encoding is unspecified, UTF-8 is prefered as +While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. @@ -538,6 +669,16 @@ some output processing may assume ref names in UTF-8. +@ + + + + @ alone is a shortcut for HEAD. + + + + + <refname>@{<date>}, e.g. master@{yesterday}, HEAD@{5 minutes ago} @@ -589,21 +730,50 @@ some output processing may assume ref names in UTF-8. - The construct @{-<n>} means the <n>th branch checked out + The construct @{-<n>} means the <n>th branch/commit checked out before the current one. -<refname>@{upstream}, e.g. master@{upstream}, @{u} +<branchname>@{upstream}, e.g. master@{upstream}, @{u} + + + + The suffix @{upstream} to a branchname (short form <branchname>@{u}) + refers to the branch that the branch specified by branchname is set to build on + top of (configured with branch.<name>.remote and + branch.<name>.merge). A missing branchname defaults to the + current one. + + + + + +<branchname>@{push}, e.g. master@{push}, @{push} - The suffix @{upstream} to a ref (short form <refname>@{u}) refers to - the branch the ref is set to build on top of. A missing ref defaults - to the current branch. + The suffix @{push} reports the branch "where we would push to" if + git push were run while branchname was checked out (or the current + HEAD if no branchname is specified). Since our push destination is + in a remote repository, of course, we report the local tracking branch + that corresponds to that branch (i.e., something in refs/remotes/). +Here's an example to make it more clear: +$ git config push.default current +$ git config remote.pushdefault myfork +$ git checkout -b mybranch origin/master + +$ git rev-parse --symbolic-full-name @{upstream} +refs/remotes/origin/master + +$ git rev-parse --symbolic-full-name @{push} +refs/remotes/myfork/mybranch +Note in the example that we set up a triangular workflow, where we pull +from one location and push to another. In a non-triangular workflow, +@{push} is the same as @{upstream}, and there is no need for it. @@ -643,12 +813,22 @@ some output processing may assume ref names in UTF-8. A suffix ^ followed by an object type name enclosed in - brace pair means the object - could be a tag, and dereference the tag recursively until an - object of that type is found or the object cannot be - dereferenced anymore (in which case, barf). <rev>^0 + brace pair means dereference the object at <rev> recursively until + an object of type <type> is found or the object cannot be + dereferenced anymore (in which case, barf). + For example, if <rev> is a commit-ish, <rev>^{commit} + describes the corresponding commit object. + Similarly, if <rev> is a tree-ish, <rev>^{tree} + describes the corresponding tree object. + <rev>^0 is a short-hand for <rev>^{commit}. +rev^{object} can be used to make sure rev names an +object that exists, without requiring rev to be a tag, and +without dereferencing rev; because a tag is already an object, +it does not have to be dereferenced even once to get to an object. +rev^{tag} can be used to ensure that rev identifies an +existing tag object. @@ -687,11 +867,12 @@ some output processing may assume ref names in UTF-8. A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is - reachable from any ref. If the commit message starts with a - ! you have to repeat that; the special sequence :/!, - followed by something else than !, is reserved for now. - The regular expression can match any part of the commit message. To - match messages starting with a string, one can use e.g. :/^foo. + reachable from any ref. The regular expression can match any part of the + commit message. To match messages starting with a string, one can use + e.g. :/^foo. The special sequence :/! is reserved for modifiers to what + is matched. :/!-foo performs a negative match, while :/!!foo matches a + literal ! character, followed by foo. Any other sequence beginning with + :/! is reserved for now. @@ -816,7 +997,8 @@ all of its parents. Include commits that are reachable from <rev2> but exclude - those that are reachable from <rev1>. + those that are reachable from <rev1>. When either <rev1> or + <rev2> is omitted, it defaults to HEAD. @@ -827,7 +1009,8 @@ all of its parents. Include commits that are reachable from either <rev1> or - <rev2> but exclude those that are reachable from both. + <rev2> but exclude those that are reachable from both. When + either <rev1> or <rev2> is omitted, it defaults to HEAD. @@ -884,21 +1067,21 @@ below for an example. Input Format git rev-parse --parseopt input format is fully text based. It has two parts, separated by a line that contains only --. The lines before the separator -(should be more than one) are used for the usage. +(should be one or more) are used for the usage. The lines after the separator describe the options. Each line of options has this format: -<opt_spec><flags>* SP+ help LF +<opt-spec><flags>*<arg-hint>? SP+ help LF -<opt_spec> +<opt-spec> its format is the short option character, then the long option name separated by a comma. Both parts are not required, though at least one - is necessary. h,help, dry-run and f are all three correct - <opt_spec>. + is necessary. May not contain any of the <flags> characters. + h,help, dry-run and f are examples of correct <opt-spec>. @@ -918,7 +1101,9 @@ Use = if the option takes an argument. -Use ? to mean that the option is optional (though its use is discouraged). +Use ? to mean that the option takes an optional argument. You + probably want to use the --stuck-long mode to be able to + unambiguously parse the optional argument. @@ -936,6 +1121,19 @@ Use ! to not make the corresponding negated long option ava + + +<arg-hint> + + + + <arg-hint>, if specified, is used as a name of the argument in the + help output, for options that take arguments. <arg-hint> is + terminated by the first whitespace. It is customary to use a + dash to separate words in a multi-word argument hint. + + + The remainder of the line, after stripping the spaces, is used as the help associated to the option. @@ -954,12 +1152,31 @@ h,help show the help foo some nifty option --foo bar= some cool option --bar with an argument +baz=arg another cool option --baz with a named argument +qux?path qux may take a path argument but has meaning by itself An option group Header C? option C with an optional argument" eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
+
+Usage text +When "$@" is -h or --help in the above example, the following +usage text would be shown: +usage: some-command [options] <args>... + + some-command does foo and bar! + + -h, --help show the help + --foo some nifty option --foo + --bar ... some cool option --bar with an argument + --baz <arg> another cool option --baz with a named argument + --qux[=<path>] qux may take a path argument but has meaning by itself + +An option group Header + -C[...] option C with an optional argument +
 SQ-QUOTE @@ -996,12 +1213,12 @@ Print the object name of the current commit: Print the commit object name from the revision in the $REV shell variable: -$ git rev-parse --verify $REV +$ git rev-parse --verify $REV^{commit} This will error out if $REV is empty or not a valid revision. -Same as above: +Similar to above: $ git rev-parse --default master --verify $REV but if $REV is empty, the commit object name from master will be printed. diff --git a/doc/source/en/TortoiseGit/git_doc/git-revert.xml b/doc/source/en/TortoiseGit/git_doc/git-revert.xml index 90d46ffe2..ed85fbfcf 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-revert.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-revert.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git revert [--edit | --no-edit] [-n] [-m parent-number] [-s] <commit>… +git revert [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>… git revert --continue git revert --quit git revert --abort @@ -86,7 +86,7 @@ both will discard uncommitted changes in your working directory. brought in by the merge. As a result, later merges will only bring in tree changes introduced by commits that are not ancestors of the previously reverted merge. This may or may not be what you want. -See the link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for +See the link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for more details. @@ -125,6 +125,21 @@ effect to your index in a row. +-S[<keyid>] + + +--gpg-sign[=<keyid>] + + + + GPG-sign commits. The keyid argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. + + + + + -s @@ -133,6 +148,7 @@ effect to your index in a row. Add Signed-off-by line at the end of the commit message. + See the signoff option in for more information. diff --git a/doc/source/en/TortoiseGit/git_doc/git-rm.xml b/doc/source/en/TortoiseGit/git_doc/git-rm.xml index 44ec8773c..756975ba0 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-rm.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-rm.xml @@ -39,7 +39,7 @@ allowing the file to be removed from just the index. Files to remove. Fileglobs (e.g. *.c) can be given to - remove all matching files. If you want git to expand + remove all matching files. If you want Git to expand file glob characters, you may need to shell-escape them. A leading directory name (e.g. dir to remove dir/file1 and dir/file2) can be @@ -142,8 +142,8 @@ allowing the file to be removed from just the index. DISCUSSION The <file> list given to the command can be exact pathnames, file glob patterns, or leading directory names. The command -removes only the paths that are known to git. Giving the name of -a file that you have not told git about does not remove that file. +removes only the paths that are known to Git. Giving the name of +a file that you have not told Git about does not remove that file. File globbing matches across directory boundaries. Thus, given two directories d and d2, there is a difference between using git rm 'd*' and git rm 'd/*', as the former will @@ -187,20 +187,25 @@ your working tree is dirty so that you cannot use git commit -a git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached -
-Submodules + + +SUBMODULES Only submodules using a gitfile (which means they were cloned -with a git version 1.7.8 or newer) will be removed from the work +with a Git version 1.7.8 or newer) will be removed from the work tree, as their repository lives inside the .git directory of the superproject. If a submodule (or one of those nested inside it) still uses a .git directory, git rm will fail - no matter if forced -or not - to protect the submodule's history. +or not - to protect the submodule's history. If it exists the +submodule.<name> section in the file will also +be removed and that file will be staged (unless --cached or -n are used). A submodule is considered up-to-date when the HEAD is the same as recorded in the index, no tracked files are modified and no untracked files that aren't ignored are present in the submodules work tree. Ignored files are deemed expendable and won't stop a submodule's work tree from being removed. -
+If you only want to remove the local checkout of a submodule from your +work tree without committing the removal, +use deinit instead. EXAMPLES @@ -215,7 +220,7 @@ tree from being removed. Documentation directory and any of its subdirectories. Note that the asterisk * is quoted from the shell in this -example; this lets git, and not the shell, expand the pathnames +example; this lets Git, and not the shell, expand the pathnames of files and subdirectories under the Documentation/ directory. @@ -233,6 +238,15 @@ of files and subdirectories under the Documentation/ direct + +BUGS +Each time a superproject update removes a populated submodule +(e.g. when switching between commits before and after the removal) a +stale submodule checkout will remain in the old location. Removing the +old directory is only safe when it uses a gitfile, as otherwise the +history of the submodule will be deleted too. This step will be +obsolete when recursive submodule update has been implemented. + SEE ALSO diff --git a/doc/source/en/TortoiseGit/git_doc/git-send-email.xml b/doc/source/en/TortoiseGit/git_doc/git-send-email.xml index b786326f0..3a55432d9 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-send-email.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-send-email.xml @@ -13,7 +13,8 @@ SYNOPSIS
-git send-email [options] <file|directory|rev-list options>… +git send-email [options] <file|directory|rev-list options>… +git send-email --dump-aliases
@@ -23,7 +24,7 @@ Patches can be specified as files, directories (which will send all files in the directory), or directly as a revision list. In the last case, any format accepted by can be passed to git send-email. -The header of the email is configurable by command line options. If not +The header of the email is configurable via command-line options. If not specified on the command line, the user will be prompted with a ReadLine enabled interface to provide the necessary information. There are two formats accepted for patch files: @@ -56,33 +57,34 @@ and the "Subject:" of the message as the second line. - Review and edit each patch you're about to send. See the - CONFIGURATION section for sendemail.multiedit. + Review and edit each patch you're about to send. Default is the value + of sendemail.annotate. See the CONFIGURATION section for + sendemail.multiEdit. ---bcc=<address> +--bcc=<address>,… Specify a "Bcc:" value for each email. Default is the value of sendemail.bcc. -The --bcc option must be repeated for each user you want on the bcc list. +This option may be specified multiple times. ---cc=<address> +--cc=<address>,… Specify a starting "Cc:" value for each email. Default is the value of sendemail.cc. -The --cc option must be repeated for each user you want on the cc list. +This option may be specified multiple times. @@ -97,10 +99,10 @@ and the "Subject:" of the message as the second line. When --compose is used, git send-email will use the From, Subject, and In-Reply-To headers specified in the message. If the body of the message (what you type after the headers and a blank line) only contains blank -(or GIT: prefixed) lines the summary won't be sent, but From, Subject, +(or Git: prefixed) lines, the summary won't be sent, but From, Subject, and In-Reply-To headers will be used unless they are removed. Missing From or In-Reply-To headers will be prompted for. -See the CONFIGURATION section for sendemail.multiedit. +See the CONFIGURATION section for sendemail.multiEdit. @@ -111,7 +113,7 @@ and In-Reply-To headers will be used unless they are removed. Specify the sender of the emails. If not specified on the command line, the value of the sendemail.from configuration option is used. If - neither the command line option nor sendemail.from are set, then the + neither the command-line option nor sendemail.from are set, then the user will be prompted for the value. The default for the prompt will be the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not set, as returned by "git var -l". @@ -158,7 +160,7 @@ is not set, this will be prompted for. ---to=<address> +--to=<address>,… @@ -167,7 +169,7 @@ is not set, this will be prompted for. value of the sendemail.to configuration value; if that is unspecified, and --to-cmd is not specified, this will be prompted for. -The --to option must be repeated for each user you want on the to list. +This option may be specified multiple times. @@ -196,6 +198,38 @@ is not set, this will be prompted for. + + +--transfer-encoding=(7bit|8bit|quoted-printable|base64) + + + + Specify the transfer encoding to be used to send the message over SMTP. + 7bit will fail upon encountering a non-ASCII message. quoted-printable + can be useful when the repository contains files that contain carriage + returns, but makes the raw patch email file (as saved from a MUA) much + harder to inspect manually. base64 is even more fool proof, but also + even more opaque. Default is the value of the sendemail.transferEncoding + configuration value; if that is unspecified, git will use 8bit and not + add a Content-Transfer-Encoding header. + + + + + +--xmailer + + +--no-xmailer + + + + Add (or prevent adding) the "X-Mailer:" header. By default, + the header is added, but it can be turned off by setting the + sendemail.xmailer configuration variable to false. + + +
@@ -212,7 +246,7 @@ is not set, this will be prompted for. subscribed to a list. In order to use the From address, set the value to "auto". If you use the sendmail binary, you must have suitable privileges for the -f parameter. Default is the value of the - sendemail.envelopesender configuration variable; if that is + sendemail.envelopeSender configuration variable; if that is unspecified, choosing the envelope sender is left to your MTA. @@ -225,7 +259,7 @@ is not set, this will be prompted for. Specify the encryption to use, either ssl or tls. Any other value reverts to plain SMTP. Default is the value of - sendemail.smtpencryption. + sendemail.smtpEncryption. @@ -239,8 +273,24 @@ is not set, this will be prompted for. HELO/EHLO command to the SMTP server. Some servers require the FQDN to match your IP address. If not set, git send-email attempts to determine your FQDN automatically. Default is the value of - sendemail.smtpdomain. + sendemail.smtpDomain. + + + + + +--smtp-auth=<mechanisms> + + + + Whitespace-separated list of allowed SMTP-AUTH mechanisms. This setting + forces using only the listed mechanisms. Example: +$ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ... +If at least one of the specified mechanisms matches the ones advertised by the +SMTP server and if it is supported by the utilized SASL library, the mechanism +is used for authentication. If neither sendemail.smtpAuth nor --smtp-auth +is specified, all mechanisms supported by the SASL library can be used. @@ -251,14 +301,14 @@ is not set, this will be prompted for. Password for SMTP-AUTH. The argument is optional: If no argument is specified, then the empty string is used as - the password. Default is the value of sendemail.smtppass, + the password. Default is the value of sendemail.smtpPass, however --smtp-pass always overrides this value. Furthermore, passwords need not be specified in configuration files or on the command line. If a username has been specified (with ---smtp-user or a sendemail.smtpuser), but no password has been -specified (with --smtp-pass or sendemail.smtppass), then the -user is prompted for a password while the input is masked for privacy. +--smtp-user or a sendemail.smtpUser), but no password has been +specified (with --smtp-pass or sendemail.smtpPass), then +a password is obtained using git-credential. @@ -271,7 +321,7 @@ user is prompted for a password while the input is masked for privacy. smtp.example.com or a raw IP address). Alternatively it can specify a full pathname of a sendmail-like program instead; the program must support the -i option. Default value can - be specified by the sendemail.smtpserver configuration + be specified by the sendemail.smtpServer configuration option; the built-in default is /usr/sbin/sendmail or /usr/lib/sendmail if such program is available, or localhost otherwise. @@ -289,7 +339,7 @@ user is prompted for a password while the input is masked for privacy. submission port 587, or the common SSL smtp port 465); symbolic port names (e.g. "submission" instead of 587) are also accepted. The port can also be set with the - sendemail.smtpserverport configuration variable. + sendemail.smtpServerPort configuration variable. @@ -300,7 +350,7 @@ user is prompted for a password while the input is masked for privacy. If set, specifies the outgoing SMTP server option to use. - Default value can be specified by the sendemail.smtpserveroption + Default value can be specified by the sendemail.smtpServerOption configuration option. The --smtp-server-option option must be repeated for each option you want @@ -320,12 +370,30 @@ must be used for each option. +--smtp-ssl-cert-path + + + + Path to a store of trusted CA certificates for SMTP SSL/TLS + certificate validation (either a directory that has been processed + by c_rehash, or a single file containing one or more PEM format + certificates concatenated together: see verify(1) -CAfile and + -CApath for more information on these). Set it to an empty string + to disable certificate verification. Defaults to the value of the + sendemail.smtpsslcertpath configuration variable, if set, or the + backing SSL library's compiled-in default otherwise (which should + be the best choice on most platforms). + + + + + --smtp-user=<user> - Username for SMTP-AUTH. Default is the value of sendemail.smtpuser; - if a username is not specified (with --smtp-user or sendemail.smtpuser), + Username for SMTP-AUTH. Default is the value of sendemail.smtpUser; + if a username is not specified (with --smtp-user or sendemail.smtpUser), then authentication is not attempted. @@ -369,7 +437,7 @@ must be used for each option. Specify a command to execute once per patch file which should generate patch file specific "Cc:" entries. Output of this command must be single email address per line. - Default is the value of sendemail.cccmd configuration value. + Default is the value of sendemail.ccCmd configuration value. @@ -383,7 +451,7 @@ must be used for each option. email sent. If disabled with "--no-chain-reply-to", all emails after the first will be sent as replies to the first email sent. When using this, it is recommended that the first file given be an overview of the - entire patch series. Disabled by default, but the sendemail.chainreplyto + entire patch series. Disabled by default, but the sendemail.chainReplyTo configuration variable can be used to enable it. @@ -415,6 +483,32 @@ must be used for each option. +--[no-]cc-cover + + + + If this is set, emails found in Cc: headers in the first patch of + the series (typically the cover letter) are added to the cc list + for each email set. Default is the value of sendemail.cccover + configuration value; if that is unspecified, default to --no-cc-cover. + + + + + +--[no-]to-cover + + + + If this is set, emails found in To: headers in the first patch of + the series (typically the cover letter) are added to the to list + for each email set. Default is the value of sendemail.tocover + configuration value; if that is unspecified, default to --no-to-cover. + + + + + --suppress-cc=<category> @@ -479,7 +573,7 @@ specified, as well as body if --no-signed-off-cc is specifi If this is set, do not add the From: address to the cc: list. - Default is the value of sendemail.suppressfrom configuration + Default is the value of sendemail.suppressFrom configuration value; if that is unspecified, default to --no-suppress-from. @@ -620,35 +714,92 @@ default to --validate.
+
+Information + + + +--dump-aliases + + + + Instead of the normal operation, dump the shorthand alias names from + the configured alias file(s), one per line in alphabetical order. Note, + this only includes the alias name and not its expanded email addresses. + See sendemail.aliasesfile for more information about aliases. + + + + +
 CONFIGURATION -sendemail.aliasesfile +sendemail.aliasesFile To avoid typing long email addresses, point this to one or more - email aliases files. You must also supply sendemail.aliasfiletype. + email aliases files. You must also supply sendemail.aliasFileType. -sendemail.aliasfiletype +sendemail.aliasFileType - Format of the file(s) specified in sendemail.aliasesfile. Must be - one of mutt, mailrc, pine, elm, or gnus. + Format of the file(s) specified in sendemail.aliasesFile. Must be + one of mutt, mailrc, pine, elm, or gnus, or sendmail. +What an alias file in each format looks like can be found in +the documentation of the email program of the same name. The +differences and limitations from the standard formats are +described below: + + + +sendmail + + + + + +Quoted aliases and quoted addresses are not supported: lines that + contain a " symbol are ignored. + + + + +Redirection to a file (/path/name) or pipe (|command) is not + supported. + + + + +File inclusion (:include: /path/name) is not supported. + + + + +Warnings are printed on the standard error output for any + explicitly unsupported constructs, and any other lines that are not + recognized by the parser. + + + + + + -sendemail.multiedit +sendemail.multiEdit @@ -680,10 +831,10 @@ sendemail.confirm To use git send-email to send your patches through the GMail SMTP server, edit ~/.gitconfig to specify your account settings: [sendemail] - smtpencryption = tls - smtpserver = smtp.gmail.com - smtpuser = yourname@gmail.com - smtpserverport = 587 + smtpEncryption = tls + smtpServer = smtp.gmail.com + smtpUser = yourname@gmail.com + smtpServerPort = 587 Once your commits are ready to be sent to the mailing list, run the following commands: $ git format-patch --cover-letter -M origin/master -o outgoing/ diff --git a/doc/source/en/TortoiseGit/git_doc/git-send-pack.xml b/doc/source/en/TortoiseGit/git_doc/git-send-pack.xml index 3ba672a85..ee1553779 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-send-pack.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-send-pack.xml @@ -8,12 +8,15 @@ NAME -git-send-pack - Push objects over git protocol to another repository +git-send-pack - Push objects over Git protocol to another repository SYNOPSIS
-git send-pack [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>…] +git send-pack [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] + [--verbose] [--thin] [--atomic] + [--[no-]signed|--sign=(true|false|if-asked)] + [<host>:]<directory> [<ref>…]
@@ -62,6 +65,22 @@ updates it from the current repository, sending named refs. +--stdin + + + + Take the list of refs from stdin, one per line. If there + are refs specified on the command line in addition to this + option, then the refs from stdin are processed after those + on the command line. + +If --stateless-rpc is specified together with this option then +the list of refs must be in packet format (pkt-line). Each ref must +be in a separate packet, and the list must end with a flush packet. + + + + --dry-run @@ -107,6 +126,38 @@ updates it from the current repository, sending named refs. +--atomic + + + + Use an atomic transaction for updating the refs. If any of the refs + fails to update then the entire push will fail without changing any + refs. + + + + + +--[no-]signed + + +--sign=(true|false|if-asked) + + + + GPG-sign the push request to update refs on the receiving + side, to allow it to be checked by the hooks and/or be + logged. If false or --no-signed, no signing will be + attempted. If true or --signed, the push will fail if the + server does not support signed pushes. If set to if-asked, + sign if and only if the server supports signed pushes. The push + will also fail if the actual call to gpg --sign fails. See + for the details on the receiving end. + + + + + <host> @@ -148,7 +199,8 @@ the remote side. You cannot specify any <ref> if you this flag. Without --all and without any <ref>, the heads that exist both on the local side and on the remote side are updated. -When one or more <ref> are specified explicitly, it can be either a +When one or more <ref> are specified explicitly (whether on the +command line or via --stdin), it can be either a single pattern, or a pair of such pattern 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>. diff --git a/doc/source/en/TortoiseGit/git_doc/git-sh-setup.xml b/doc/source/en/TortoiseGit/git_doc/git-sh-setup.xml index 2499e768c..fcfb19655 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-sh-setup.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-sh-setup.xml @@ -8,7 +8,7 @@ NAME -git-sh-setup - Common git shell script setup code +git-sh-setup - Common Git shell script setup code SYNOPSIS @@ -23,7 +23,7 @@ This documentation is meant for people who are studying the Porcelain-ish scripts and/or are writing new ones. The git sh-setup scriptlet is designed to be sourced (using .) by other shell scripts to set up some variables pointing at -the normal git directories and a few helper shell functions. +the normal Git directories and a few helper shell functions. Before sourcing it, your script should set up a few variables; USAGE (and LONG_USAGE, if any) is used to define message given by usage() shell function. SUBDIRECTORY_OK can be set @@ -62,9 +62,11 @@ set_reflog_action - set the message that will be recorded to describe the - end-user action in the reflog, when the script updates a - ref. + Set GIT_REFLOG_ACTION environment to a given string (typically + the name of the program) unless it is already set. Whenever + the script runs a git command that updates refs, a reflog + entry is created using the value of this string to leave the + record of what command updated the ref. @@ -151,6 +153,19 @@ get_author_ident_from_commit + + +create_virtual_base + + + + modifies the first file so only lines in common with the + second file remain. If there is insufficient common material, + then the first file is left empty. The result is suitable + as a virtual base input for a 3-way merge. + + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-shell.xml b/doc/source/en/TortoiseGit/git_doc/git-shell.xml index be0a254d6..a7b350c69 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-shell.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-shell.xml @@ -13,23 +13,92 @@ SYNOPSIS
-git shell [-c <command> <argument>] +chsh -s $(command -v git-shell) <user> +git clone <user>@localhost:/path/to/repo.git +ssh <user>@localhost
DESCRIPTION -A login shell for SSH accounts to provide restricted Git access. When --c is given, the program executes <command> non-interactively; -<command> can be one of git receive-pack, git upload-pack, git -upload-archive, cvs server, or a command in COMMAND_DIR. The shell -is started in interactive mode when no arguments are given; in this -case, COMMAND_DIR must exist, and any of the executables in it can be -invoked. -cvs server is a special command which executes git-cvsserver. -COMMAND_DIR is the path "$HOME/git-shell-commands". The user must have -read and execute permissions to the directory in order to execute the -programs in it. The programs are executed with a cwd of $HOME, and -<argument> is parsed as a command-line string. +This is a login shell for SSH accounts to provide restricted Git access. +It permits execution only of server-side Git commands implementing the +pull/push functionality, plus custom commands present in a subdirectory +named git-shell-commands in the user's home directory. + + +COMMANDS +git shell accepts the following commands after the -c option: + + + +git receive-pack <argument> + + +git upload-pack <argument> + + +git upload-archive <argument> + + + + Call the corresponding server-side command to support + the client's git push, git fetch, or git archive --remote + request. + + + + + +cvs server + + + + Imitate a CVS server. See . + + + + +If a ~/git-shell-commands directory is present, git shell will +also handle other, custom commands by running +"git-shell-commands/<command> <arguments>" from the user's home +directory. + + +INTERACTIVE USE +By default, the commands above can be executed only with the -c +option; the shell is not interactive. +If a ~/git-shell-commands directory is present, git shell +can also be run interactively (with no arguments). If a help +command is present in the git-shell-commands directory, it is +run to provide the user with an overview of allowed actions. Then a +"git> " prompt is presented at which one can enter any of the +commands from the git-shell-commands directory, or exit to close +the connection. +Generally this mode is used as an administrative interface to allow +users to list repositories they have access to, create, delete, or +rename repositories, or change repository descriptions and +permissions. +If a no-interactive-login command exists, then it is run and the +interactive shell is aborted. + + +EXAMPLE +To disable interactive logins, displaying a greeting instead: +$ chsh -s /usr/bin/git-shell +$ mkdir $HOME/git-shell-commands +$ cat >$HOME/git-shell-commands/no-interactive-login <<\EOF +#!/bin/sh +printf '%s\n' "Hi $USER! You've successfully authenticated, but I do not" +printf '%s\n' "provide interactive shell access." +exit 128 +EOF +$ chmod +x $HOME/git-shell-commands/no-interactive-login + + +SEE ALSO +ssh(1), +, +contrib/git-shell-commands/README GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-shortlog.xml b/doc/source/en/TortoiseGit/git_doc/git-shortlog.xml index eb3dcc1ef..c8302af11 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-shortlog.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-shortlog.xml @@ -13,8 +13,8 @@ SYNOPSIS
-git log --pretty=short | git shortlog [-h] [-n] [-s] [-e] [-w] -git shortlog [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] <commit>… +git log --pretty=short | git shortlog [<options>] +git shortlog [<options>] [<revision range>] [[--] <path>…]
@@ -32,19 +32,6 @@ reference to the current repository. --h - - ---help - - - - Print a short usage message and exit. - - - - - -n @@ -108,6 +95,37 @@ reference to the current repository. and subsequent lines are indented by indent2 spaces. width, indent1, and indent2 default to 76, 6 and 9 respectively. +If width is 0 (zero) then indent the lines of the output without wrapping +them. + + + + +<revision range> + + + + Show only commits in the specified revision range. When no + <revision range> is specified, it defaults to HEAD (i.e. the + whole history leading to the current commit). origin..HEAD + specifies all the commits reachable from the current commit + (i.e. HEAD), but not from origin. For a complete list of + ways to spell <revision range>, see the "Specifying Ranges" + section of . + + + + + +[--] <path>… + + + + Consider only commits that are enough to explain how the files + that match the specified paths came to be. + +Paths may need to be prefixed with "-- " to separate them from +options or the revision range, when confusion arises. @@ -118,7 +136,8 @@ reference to the current repository. person in the shortlog, where their name and/or email address was spelled differently. If the file .mailmap exists at the toplevel of the repository, or at -the location pointed to by the mailmap.file configuration option, it +the location pointed to by the mailmap.file or mailmap.blob +configuration options, it is used to map author and committer names and email addresses to canonical real names and email addresses. In the simple form, each line in the file consists of the canonical diff --git a/doc/source/en/TortoiseGit/git_doc/git-show-branch.xml b/doc/source/en/TortoiseGit/git_doc/git-show-branch.xml index 2ed259593..263c67926 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-show-branch.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-show-branch.xml @@ -28,7 +28,7 @@ with <rev>s or <globs>s (or all refs under refs/heads and/or refs/tags) semi-visually. It cannot show more than 29 branches and commits at a time. It uses showbranch.default multi-valued configuration items if -no <rev> nor <glob> is given on the command line. +no <rev> or <glob> is given on the command line. OPTIONS @@ -39,7 +39,7 @@ no <rev> nor <glob> is given on the command line. - Arbitrary extended SHA1 expression (see ) + Arbitrary extended SHA-1 expression (see ) that typically names a branch head or a tag. @@ -276,7 +276,7 @@ displayed, indented N places. If a commit is on the I-th branch, the I-th indentation character shows a + sign; otherwise it shows a space. Merge commits are denoted by a - sign. Each commit shows a short name that -can be used as an extended SHA1 to name that commit. +can be used as an extended SHA-1 to name that commit. The following example shows three branches, "master", "fixes" and "mhf": $ git show-branch master fixes mhf diff --git a/doc/source/en/TortoiseGit/git_doc/git-show-index.xml b/doc/source/en/TortoiseGit/git_doc/git-show-index.xml index 04cbb8c6c..80c742e39 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-show-index.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-show-index.xml @@ -13,16 +13,17 @@ SYNOPSIS
-git show-index < idx-file +git show-index
DESCRIPTION -Reads given idx file for packed git archive created with -git pack-objects command, and dumps its contents. +Read the idx file for a Git packfile created with +git pack-objects command from the standard input, and +dump its contents. The information it outputs is subset of what you can get from git verify-pack -v; this command only shows the packfile -offset and SHA1 of each object. +offset and SHA-1 of each object. GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-show-ref.xml b/doc/source/en/TortoiseGit/git_doc/git-show-ref.xml index 46dc8331b..5833799ee 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-show-ref.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-show-ref.xml @@ -16,7 +16,7 @@ git show-ref [-q|--quiet] [--verify] [--head] [-d|--dereference] [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>…] -git show-ref --exclude-existing[=<pattern>] < ref-list +git show-ref --exclude-existing[=<pattern>]
@@ -25,8 +25,10 @@ commit IDs. Results can be filtered using a pattern and tags can be dereferenced into object IDs. Additionally, it can be used to test whether a particular ref exists. -The --exclude-existing form is a filter that does the inverse, it shows the -refs from stdin that don't exist in the local repository. +By default, shows the tags, heads, and remote refs. +The --exclude-existing form is a filter that does the inverse. It reads +refs from stdin, one ref per line, and shows those that don't exist in +the local repository. Use of this utility is encouraged in favor of directly accessing files under the .git directory. @@ -39,7 +41,7 @@ the .git directory. - Show the HEAD reference. + Show the HEAD reference, even if it would normally be filtered out. @@ -52,9 +54,9 @@ the .git directory. - 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. + Limit to "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. @@ -81,8 +83,8 @@ the .git directory. - Only show the SHA1 hash, not the reference name. When combined with - --dereference the dereferenced tag will still be shown after the SHA1. + Only show the SHA-1 hash, not the reference name. When combined with + --dereference the dereferenced tag will still be shown after the SHA-1. @@ -149,7 +151,7 @@ the .git directory. Show references matching one or more patterns. Patterns are matched from the end of the full name, and only complete parts are matched, e.g. master matches refs/heads/master, refs/remotes/origin/master, - refs/tags/jedi/master but not refs/heads/mymaster nor + refs/tags/jedi/master but not refs/heads/mymaster or refs/remotes/master/jedi. @@ -209,7 +211,8 @@ flag, so you can do SEE ALSO -, +, +, , diff --git a/doc/source/en/TortoiseGit/git_doc/git-diff-tree.xml b/doc/source/en/TortoiseGit/git_doc/git-show.xml similarity index 71% copy from doc/source/en/TortoiseGit/git_doc/git-diff-tree.xml copy to doc/source/en/TortoiseGit/git_doc/git-show.xml index 31a797357..84630dcdf 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-diff-tree.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-show.xml @@ -1,1901 +1,1691 @@ - - git-diff-tree(1) + + git-show(1) -git-diff-tree(1) +git-show(1) - + NAME -git-diff-tree - Compares the content and mode of blobs found via two tree objects +git-show - Show various types of objects - + SYNOPSIS
-git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] - [-t] [-r] [-c | --cc] [--root] [<common diff options>] - <tree-ish> [<tree-ish>] [<path>…] +git show [options] <object>…
- + 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. +Shows one or more objects (blobs, trees, tags and commits). +For commits it shows the log message and textual diff. It also +presents the merge commit in a special format as produced by +git diff-tree --cc. +For tags, it shows the tag message and the referenced objects. +For trees, it shows the names (equivalent to git ls-tree +with --name-only). +For plain blobs, it shows the plain contents. +The command takes options applicable to the git diff-tree command to +control how the changes the commit introduces are shown. +This manual page describes only the most frequently used options. - + OPTIONS --p - - --u - - ---patch +<object>… - Generate patch (see section on generating patches). - + The names of objects to show. + For a more complete list of ways to spell object names, see + "SPECIFYING REVISIONS" section in . --U<n> +--pretty[=<format>] ---unified=<n> +--format=<format> - Generate diffs with <n> lines of context instead of - the usual three. - Implies -p. + Pretty-print the contents of the commit logs in a given format, + where <format> can be one of oneline, short, medium, + full, fuller, email, raw, format:<string> + and tformat:<string>. When <format> is none of the above, + and has %placeholder in it, it acts as if + --pretty=tformat:<format> were given. +See the "PRETTY FORMATS" section for some additional details for each +format. When =<format> part is omitted, it defaults to medium. +Note: you can specify the default pretty format in the repository +configuration (see ). ---raw +--abbrev-commit - Generate the raw format. - This is the default. + Instead of showing the full 40-byte hexadecimal commit object + name, show only a partial prefix. Non default number of + digits can be specified with "--abbrev=<n>" (which also modifies + diff output, if it is displayed). +This should make "--pretty=oneline" a whole lot more readable for +people using 80-column terminals. ---patch-with-raw +--no-abbrev-commit - Synonym for -p --raw. + Show the full 40-byte hexadecimal commit object name. This negates + --abbrev-commit and those options which imply it such as + "--oneline". It also overrides the log.abbrevCommit variable. ---minimal +--oneline - Spend extra time to make sure the smallest possible - diff is produced. + This is a shorthand for "--pretty=oneline --abbrev-commit" + used together. ---patience +--encoding=<encoding> - Generate a diff using the "patience diff" algorithm. + The commit objects record the encoding used for the log message + in their encoding header; this option can be used to tell the + command to re-code the commit log message in the encoding + preferred by the user. For non plumbing commands this + defaults to UTF-8. Note that if an object claims to be encoded + in X and we are outputting in X, we will output the object + verbatim; this means that invalid sequences in the original + commit may be copied to the output. ---histogram +--expand-tabs=<n> - - - Generate a diff using the "histogram diff" algorithm. - - - - ---stat[=<width>[,<name-width>[,<count>]]] +--expand-tabs + + +--no-expand-tabs - Generate a diffstat. By default, as much space as necessary - will be used for the filename part, and the rest for the graph - part. Maximum width defaults to terminal width, or 80 columns - if not connected to a terminal, and can be overridden by - <width>. The width of the filename part can be limited by - giving another width <name-width> after a comma. The width - of the graph part can be limited by using - --stat-graph-width=<width> (affects all commands generating - a stat graph) or by setting diff.statGraphWidth=<width> - (does not affect git format-patch). - By giving a third parameter <count>, you can limit the - output to the first <count> lines, followed by ... if - there are more. + Perform a tab expansion (replace each tab with enough spaces + to fill to the next display column that is multiple of <n>) + in the log message before showing it in the output. + --expand-tabs is a short-hand for --expand-tabs=8, and + --no-expand-tabs is a short-hand for --expand-tabs=0, + which disables tab expansion. -These parameters can also be set individually with --stat-width=<width>, ---stat-name-width=<name-width> and --stat-count=<count>. +By default, tabs are expanded in pretty formats that indent the log +message by 4 spaces (i.e. medium, which is the default, full, +and fuller). ---numstat +--notes[=<treeish>] - Similar to --stat, but shows number of added and - deleted lines in decimal notation and pathname without - abbreviation, to make it more machine friendly. For - binary files, outputs two - instead of saying - 0 0. + Show the notes (see ) that annotate the + commit, when showing the commit log message. This is the default + for git log, git show and git whatchanged commands when + there is no --pretty, --format, or --oneline option given + on the command line. +By default, the notes shown are from the notes refs listed in the +core.notesRef and notes.displayRef variables (or corresponding +environment overrides). See for more details. +With an optional <treeish> argument, use the treeish to find the notes +to display. The treeish can specify the full refname when it begins +with refs/notes/; when it begins with notes/, refs/ and otherwise +refs/notes/ is prefixed to form a full name of the ref. +Multiple --notes options can be combined to control which notes are +being displayed. Examples: "--notes=foo" will show only notes from +"refs/notes/foo"; "--notes=foo --notes" will show both notes from +"refs/notes/foo" and from the default notes ref(s). ---shortstat +--no-notes - Output only the last line of the --stat format containing total - number of modified files, as well as number of added and deleted - lines. + Do not show notes. This negates the above --notes option, by + resetting the list of notes refs from which notes are shown. + Options are parsed in the order given on the command line, so e.g. + "--notes --notes=foo --no-notes --notes=bar" will only show notes + from "refs/notes/bar". ---dirstat[=<param1,param2,…>] +--show-notes[=<treeish>] - - - Output the distribution of relative amount of changes for each - sub-directory. The behavior of --dirstat can be customized by - passing it a comma separated list of parameters. - The defaults are controlled by the diff.dirstat configuration - variable (see ). - The following parameters are available: - - - -changes +--[no-]standard-notes - Compute the dirstat numbers by counting the lines that have been - removed from the source, or added to the destination. This ignores - the amount of pure code movements within a file. In other words, - rearranging lines in a file is not counted as much as other changes. - This is the default behavior when no parameter is given. + These options are deprecated. Use the above --notes/--no-notes + options instead. -lines +--show-signature - Compute the dirstat numbers by doing the regular line-based diff - analysis, and summing the removed/added line counts. (For binary - files, count 64-byte chunks instead, since binary files have no - natural concept of lines). This is a more expensive --dirstat - behavior than the changes behavior, but it does count rearranged - lines within a file as much as other changes. The resulting output - is consistent with what you get from the other --*stat options. + Check the validity of a signed commit object by passing the signature + to gpg --verify and show the output. - - -files - + + + +PRETTY FORMATS +If the commit is a merge, and if the pretty-format +is not oneline, email or raw, an additional line is +inserted before the Author: line. This line begins with +"Merge: " and the sha1s of ancestral commits are printed, +separated by spaces. Note that the listed commits may not +necessarily be the list of the direct parent commits if you +have limited your view of history: for example, if you are +only interested in changes related to a certain directory or +file. +There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +format: string, as described below (see +). Here are the details of the +built-in formats: + - Compute the dirstat numbers by counting the number of files changed. - Each changed file counts equally in the dirstat analysis. This is - the computationally cheapest --dirstat behavior, since it does - not have to look at the file contents at all. +oneline +<sha1> <title line> +This is designed to be as compact as possible. - - - -cumulative - - Count changes in a child directory for the parent directory as well. - Note that when using cumulative, the sum of the percentages - reported may exceed 100%. The default (non-cumulative) behavior can - be specified with the noncumulative parameter. +short +commit <sha1> +Author: <author> +<title line> - - - -<limit> - - An integer parameter specifies a cut-off percent (3% by default). - Directories contributing less than this percentage of the changes - are not shown in the output. +medium +commit <sha1> +Author: <author> +Date: <author date> +<title line> +<full commit message> - - -Example: The following will count changed files, while ignoring -directories with less than 10% of the total amount of changed files, -and accumulating child directory counts in the parent directories: ---dirstat=files,10,cumulative. - - - - ---summary - - Output a condensed summary of extended header information - such as creations, renames and mode changes. +full +commit <sha1> +Author: <author> +Commit: <committer> +<title line> +<full commit message> - - - ---patch-with-stat - - Synonym for -p --stat. +fuller +commit <sha1> +Author: <author> +AuthorDate: <author date> +Commit: <committer> +CommitDate: <committer date> +<title line> +<full commit message> - - - --z - - When --raw, --numstat, --name-only or --name-status has been - given, do not munge pathnames and use NULs as output field terminators. +email -Without this option, each pathname output will have TAB, LF, double quotes, -and backslash characters replaced with \t, \n, \", and \\, -respectively, and the pathname will be enclosed in double quotes if -any of those replacements occurred. +From <sha1> <date> +From: <author> +Date: <author date> +Subject: [PATCH] <title line> +<full commit message> - - - ---name-only - - Show only names of changed files. +raw +The raw format shows the entire commit exactly as +stored in the commit object. Notably, the SHA-1s are +displayed in full, regardless of whether --abbrev or +--no-abbrev are used, and parents information show the +true parent commits, without taking grafts or history +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +git log --raw. To get full object names in a raw diff format, +use --no-abbrev. - - - ---name-status - - Show only names and status of changed files. See the description - of the --diff-filter option on what the status letters mean. +format:<string> - - - - ---submodule[=<format>] - +The format:<string> format allows you to specify which information +you want to show. It works a little bit like printf format, +with the notable exception that you get a newline with %n +instead of \n. +E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n" +would show something like this: +The author of fe6e0ee was Junio C Hamano, 23 hours ago +The title was >>t4119: test autocomputing -p<n> for traditional diff input.<< +The placeholders are: + - Specify how differences in submodules are shown. When --submodule - or --submodule=log is given, the log format is used. This format lists - the commits in the range like summary does. - Omitting the --submodule option or specifying --submodule=short, - uses the short format. This format just shows the names of the commits - at the beginning and end of the range. Can be tweaked via the - diff.submodule configuration variable. +%H: commit hash - - - ---color[=<when>] - - Show colored diff. - The value must be always (the default for <when>), never, or auto. - The default value is never. +%h: abbreviated commit hash - - - ---no-color - - Turn off colored diff. - It is the same as --color=never. +%T: tree hash - - - ---word-diff[=<mode>] - - Show a word diff, using the <mode> to delimit changed words. - By default, words are delimited by whitespace; see - --word-diff-regex below. The <mode> defaults to plain, and - must be one of: +%t: abbreviated tree hash - - - -color - + - Highlight changed words using only colors. Implies --color. +%P: parent hashes - - - -plain - - Show words as [-removed-] and {+added+}. Makes no - attempts to escape the delimiters if they appear in the input, - so the output may be ambiguous. +%p: abbreviated parent hashes - - - -porcelain - - Use a special line-based format intended for script - consumption. Added/removed/unchanged runs are printed in the - usual unified diff format, starting with a +/-/` ` - character at the beginning of the line and extending to the - end of the line. Newlines in the input are represented by a - tilde ~ on a line of its own. +%an: author name - - - -none - - Disable word diff again. +%aN: author name (respecting .mailmap, see + or ) - - -Note that despite the name of the first mode, color is used to -highlight the changed parts in all modes if enabled. + + +%ae: author email + - - - ---word-diff-regex=<regex> - - Use <regex> to decide what a word is, instead of considering - runs of non-whitespace to be a word. Also implies - --word-diff unless it was already enabled. +%aE: author email (respecting .mailmap, see + or ) -Every non-overlapping match of the -<regex> is considered a word. Anything between these matches is -considered whitespace and ignored(!) for the purposes of finding -differences. You may want to append |[^[:space:]] to your regular -expression to make sure that it matches all non-whitespace characters. -A match that contains a newline is silently truncated(!) at the -newline. -The regex can also be set via a diff driver or configuration option, see - or . Giving it explicitly -overrides any diff driver or configuration setting. Diff drivers -override configuration settings. - - - ---color-words[=<regex>] - - Equivalent to --word-diff=color plus (if a regex was - specified) --word-diff-regex=<regex>. +%ad: author date (format respects --date= option) - - - ---no-renames - - Turn off rename detection, even when the configuration - file gives the default to do so. +%aD: author date, RFC2822 style - - - ---check - - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by core.whitespace - configuration. By default, trailing whitespaces (including - lines that solely consist of whitespaces) and a space character - that is immediately followed by a tab character inside the - initial indent of the line are considered whitespace errors. - Exits with non-zero status if problems are found. Not compatible - with --exit-code. +%ar: author date, relative - - - ---full-index - - Instead of the first handful of characters, show the full - pre- and post-image blob object names on the "index" - line when generating patch format output. +%at: author date, UNIX timestamp - - - ---binary - - In addition to --full-index, output a binary diff that - can be applied with git-apply. +%ai: author date, ISO 8601-like format - - - ---abbrev[=<n>] - - Instead of showing the full 40-byte hexadecimal object - name in diff-raw format output and diff-tree header - lines, show only a partial prefix. This is - independent of the --full-index option above, which controls - the diff-patch output format. Non default number of - digits can be specified with --abbrev=<n>. +%aI: author date, strict ISO 8601 format - - - --B[<n>][/<m>] - - ---break-rewrites[=[<n>][/<m>]] - - Break complete rewrite changes into pairs of delete and - create. This serves two purposes: +%cn: committer name -It affects the way a change that amounts to a total rewrite of a file -not as a series of deletion and insertion mixed together with a very -few lines that happen to match textually as the context, but as a -single deletion of everything old followed by a single insertion of -everything new, and the number m controls this aspect of the -B -option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for git to consider it a total -rewrite (i.e. otherwise the resulting patch will be a series of -deletion and insertion mixed together with context lines). -When used with -M, a totally-rewritten file is also considered as the -source of a rename (usually -M only considers a file that disappeared -as the source of a rename), and the number n controls this aspect of -the -B option (defaults to 50%). -B20% specifies that a change with -addition and deletion compared to 20% or more of the file's size are -eligible for being picked up as a possible source of a rename to -another file. - - - --M[<n>] - - ---find-renames[=<n>] - - Detect renames. - If n is specified, it is a threshold on the similarity - index (i.e. amount of addition/deletions compared to the - file's size). For example, -M90% means git should consider a - delete/add pair to be a rename if more than 90% of the file - hasn't changed. Without a % sign, the number is to be read as - a fraction, with a decimal point before it. I.e., -M5 becomes - 0.5, and is thus the same as -M50%. Similarly, -M05 is - the same as -M5%. To limit detection to exact renames, use - -M100%. +%cN: committer name (respecting .mailmap, see + or ) - - - --C[<n>] - - ---find-copies[=<n>] - - Detect copies as well as renames. See also --find-copies-harder. - If n is specified, it has the same meaning as for -M<n>. +%ce: committer email - - - ---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. Giving more than one - -C option has the same effect. +%cE: committer email (respecting .mailmap, see + or ) - - - --D - - ---irreversible-delete - - Omit the preimage for deletes, i.e. print only the header but not - the diff between the preimage and /dev/null. The resulting patch - is not meant to be applied with patch nor git apply; this is - solely for people who want to just concentrate on reviewing the - text after the change. In addition, the output obviously lack - enough information to apply such a patch in reverse, even manually, - hence the name of the option. +%cd: committer date (format respects --date= option) -When used together with -B, omit also the preimage in the deletion part -of a delete/create pair. - - - --l<num> - - The -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. +%cD: committer date, RFC2822 style - - - ---diff-filter=[(A|C|D|M|R|T|U|X|B)…[*]] - - Select only files that are Added (A), Copied (C), - Deleted (D), Modified (M), Renamed (R), have their - type (i.e. regular file, symlink, submodule, …) changed (T), - are Unmerged (U), are - Unknown (X), or have had their pairing Broken (B). - Any combination of the filter characters (including none) can be used. - When * (All-or-none) is added to the combination, all - paths are selected if there is any file that matches - other criteria in the comparison; if there is no file - that matches other criteria, nothing is selected. +%cr: committer date, relative - - - --S<string> - - Look for differences that introduce or remove an instance of - <string>. Note that this is different than the string simply - appearing in diff output; see the pickaxe entry in - for more details. +%ct: committer date, UNIX timestamp - - - --G<regex> - - Look for differences whose added or removed line matches - the given <regex>. +%ci: committer date, ISO 8601-like format - - - ---pickaxe-all - - When -S or -G finds a change, show all the changes in that - changeset, not just the files that contain the change - in <string>. +%cI: committer date, strict ISO 8601 format - - - ---pickaxe-regex - - Make the <string> not a plain string but an extended POSIX - regex to match. +%d: ref names, like the --decorate option of - - - --O<orderfile> - - Output the patch in the order specified in the - <orderfile>, which has one shell glob pattern per line. +%D: ref names without the " (", ")" wrapping. - - - --R - - Swap two inputs; that is, show differences from index or - on-disk file to tree contents. +%e: encoding - - - ---relative[=<path>] - - When run from a subdirectory of the project, it can be - told to exclude changes outside the directory and show - pathnames relative to it with this option. When you are - not in a subdirectory (e.g. in a bare repository), you - can name which subdirectory to make the output relative - to by giving a <path> as an argument. +%s: subject - - - --a - - ---text - - Treat all files as text. +%f: sanitized subject line, suitable for a filename - - - ---ignore-space-at-eol - - Ignore changes in whitespace at EOL. +%b: body - - - --b - - ---ignore-space-change - - Ignore changes in amount of whitespace. This ignores whitespace - at line end, and considers all other sequences of one or - more whitespace characters to be equivalent. +%B: raw body (unwrapped subject and body) - - - --w - - ---ignore-all-space - - Ignore whitespace when comparing lines. This ignores - differences even if one line has whitespace where the other - line has none. +%N: commit notes - - - ---inter-hunk-context=<lines> - - Show the context between diff hunks, up to the specified number - of lines, thereby fusing hunks that are close to each other. +%GG: raw verification message from GPG for a signed commit - - - --W - - ---function-context - - Show whole surrounding functions of changes. +%G?: show "G" for a Good signature, "B" for a Bad signature, "U" for a good, + untrusted signature and "N" for no signature - - - ---exit-code - - Make the program exit with codes similar to diff(1). - That is, it exits with 1 if there were differences and - 0 means no differences. +%GS: show the name of the signer for a signed commit - - - ---quiet - - Disable all output of the program. Implies --exit-code. +%GK: show the key used to sign a signed commit - - - ---ext-diff - - Allow an external diff helper to be executed. If you set an - external diff driver with , you need - to use this option with and friends. +%gD: reflog selector, e.g., refs/stash@{1} - - - ---no-ext-diff - - Disallow external diff drivers. +%gd: shortened reflog selector, e.g., stash@{1} - - - ---textconv - - ---no-textconv - - Allow (or disallow) external text conversion filters to be run - when comparing binary files. See for - details. Because textconv filters are typically a one-way - conversion, the resulting diff is suitable for human - consumption, but cannot be applied. For this reason, textconv - filters are enabled by default only for and - , but not for or - diff plumbing commands. +%gn: reflog identity name - - - ---ignore-submodules[=<when>] - - Ignore changes to submodules in the diff generation. <when> can be - either "none", "untracked", "dirty" or "all", which is the default - Using "none" will consider the submodule modified when it either contains - untracked or modified files or its HEAD differs from the commit recorded - in the superproject and can be used to override any settings of the - ignore option in or . When - "untracked" is used submodules are not considered dirty when they only - contain untracked content (but they are still scanned for modified - content). Using "dirty" ignores all changes to the work tree of submodules, - only changes to the commits stored in the superproject are shown (this was - the behavior until 1.7.0). Using "all" hides all changes to submodules. +%gN: reflog identity name (respecting .mailmap, see + or ) - - - ---src-prefix=<prefix> - - Show the given source prefix instead of "a/". +%ge: reflog identity email - - - ---dst-prefix=<prefix> - - Show the given destination prefix instead of "b/". +%gE: reflog identity email (respecting .mailmap, see + or ) - - - ---no-prefix - - Do not show any source or destination prefix. +%gs: reflog subject - - -For more detailed explanation on these common options, see also -. - - - -<tree-ish> - - The id of a tree object. +%Cred: switch color to red - - - -<path>… - - If provided, the results are limited to a subset of files - matching one of these prefix strings. - i.e., file matches /^<pattern1>|<pattern2>|.../ - Note that this parameter does not provide any wildcard or regexp - features. +%Cgreen: switch color to green - - - --r - - recurse into sub-trees +%Cblue: switch color to blue - - - --t - - show tree entry itself as well as subtrees. Implies -r. +%Creset: reset color - - - ---root - - When --root is specified the initial commit will be shown as a big - creation event. This is equivalent to a diff against the NULL tree. +%C(…): color specification, as described in color.branch.* config option; + adding auto, at the beginning will emit color only when colors are + enabled for log output (by color.diff, color.ui, or --color, and + respecting the auto settings of the former if we are going to a + terminal). auto alone (i.e. %C(auto)) will turn on auto coloring + on the next placeholders until the color is switched again. - - - ---stdin - - When --stdin is specified, the command does not take - <tree-ish> arguments from the command line. Instead, it - reads lines containing either two <tree>, one <commit>, or a - list of <commit> from its standard input. (Use a single space - as separator.) +%m: left, right or boundary mark -When two trees are given, it compares the first tree with the second. -When a single commit is given, it compares the commit with its -parents. The remaining commits, when given, are used as if they are -parents of the first commit. -When comparing two trees, the ID of both trees (separated by a space -and terminated by a newline) is printed before the difference. When -comparing commits, the ID of the first (or only) commit, followed by a -newline, is printed. -The following flags further affect the behavior when comparing -commits (but not trees). - - - --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. See - also -c. +%n: newline - - - --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. +%%: a raw % - - - --v - - This flag causes git diff-tree --stdin to also show - the commit message before the differences. +%x00: print a byte from a hex code - - - ---pretty[=<format>] - + + +%w([<w>[,<i1>[,<i2>]]]): switch line wrapping, like the -w option of + . + + + + +%<(<N>[,trunc|ltrunc|mtrunc]): make the next placeholder take at + least N columns, padding spaces on the right if necessary. + Optionally truncate at the beginning (ltrunc), the middle (mtrunc) + or the end (trunc) if the output is longer than N columns. + Note that truncating only works correctly with N >= 2. + + + + +%<|(<N>): make the next placeholder take at least until Nth + columns, padding spaces on the right if necessary + + + + +%>(<N>), %>|(<N>): similar to %<(<N>), %<|(<N>) + respectively, but padding spaces on the left + + + + +%>>(<N>), %>>|(<N>): similar to %>(<N>), %>|(<N>) + respectively, except that if the next placeholder takes more spaces + than given and there are spaces on its left, use those spaces + + + + +%><(<N>), %><|(<N>): similar to % <(<N>), %<|(<N>) + respectively, but padding both sides (i.e. the text is centered) + + + + + +Some placeholders may depend on other options given to the +revision traversal engine. For example, the %g* reflog options will +insert an empty string unless we are traversing reflog entries (e.g., by +git log -g). The %d and %D placeholders will use the "short" +decoration format if --decorate was not already provided on the command +line. +If you add a + (plus sign) after % of a placeholder, a line-feed +is inserted immediately before the expansion if and only if the +placeholder expands to a non-empty string. +If you add a - (minus sign) after % of a placeholder, line-feeds that +immediately precede the expansion are deleted if and only if the +placeholder expands to an empty string. +If you add a ` ` (space) after % of a placeholder, a space +is inserted immediately before the expansion if and only if the +placeholder expands to a non-empty string. + + + +tformat: + +The tformat: format works exactly like format:, except that it +provides "terminator" semantics instead of "separator" semantics. In +other words, each commit has the message terminator character (usually a +newline) appended, rather than a separator placed between entries. +This means that the final entry of a single-line format will be properly +terminated with a new line, just as the "oneline" format does. +For example: +$ git log -2 --pretty=format:%h 4da45bef \ + | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/' +4da45be +7134973 -- NO NEWLINE + +$ git log -2 --pretty=tformat:%h 4da45bef \ + | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/' +4da45be +7134973 +In addition, any unrecognized string that has a % in it is interpreted +as if it has tformat: in front of it. For example, these two are +equivalent: +$ git log -2 --pretty=tformat:%h 4da45bef +$ git log -2 --pretty=%h 4da45bef + + + + +COMMON DIFF OPTIONS + + ---format=<format> +-p + + +-u + + +--patch - Pretty-print the contents of the commit logs in a given format, - where <format> can be one of oneline, short, medium, - full, fuller, email, raw and format:<string>. See - the "PRETTY FORMATS" section for some additional details for each - format. When omitted, the format defaults to medium. + Generate patch (see section on generating patches). -Note: you can specify the default pretty format in the repository -configuration (see ). ---abbrev-commit +-s + + +--no-patch - Instead of showing the full 40-byte hexadecimal commit object - name, show only a partial prefix. Non default number of - digits can be specified with "--abbrev=<n>" (which also modifies - diff output, if it is displayed). + Suppress diff output. Useful for commands like git show that + show the patch by default, or to cancel the effect of --patch. -This should make "--pretty=oneline" a whole lot more readable for -people using 80-column terminals. ---no-abbrev-commit +-U<n> + + +--unified=<n> - Show the full 40-byte hexadecimal commit object name. This negates - --abbrev-commit and those options which imply it such as - "--oneline". It also overrides the log.abbrevCommit variable. + Generate diffs with <n> lines of context instead of + the usual three. + Implies -p. ---oneline +--raw - This is a shorthand for "--pretty=oneline --abbrev-commit" - used together. + For each commit, show a summary of changes using the raw diff + format. See the "RAW OUTPUT FORMAT" section of + . This is different from showing the log + itself in raw format, which you can achieve with + --format=raw. ---encoding[=<encoding>] +--patch-with-raw - The commit objects record the encoding used for the log message - in their encoding header; this option can be used to tell the - command to re-code the commit log message in the encoding - preferred by the user. For non plumbing commands this - defaults to UTF-8. + Synonym for -p --raw. ---notes[=<ref>] +--minimal - Show the notes (see ) that annotate the - commit, when showing the commit log message. This is the default - for git log, git show and git whatchanged commands when - there is no --pretty, --format nor --oneline option given - on the command line. + Spend extra time to make sure the smallest possible + diff is produced. -By default, the notes shown are from the notes refs listed in the -core.notesRef and notes.displayRef variables (or corresponding -environment overrides). See for more details. -With an optional <ref> argument, show this notes ref instead of the -default notes ref(s). The ref is taken to be in refs/notes/ if it -is not qualified. -Multiple --notes options can be combined to control which notes are -being displayed. Examples: "--notes=foo" will show only notes from -"refs/notes/foo"; "--notes=foo --notes" will show both notes from -"refs/notes/foo" and from the default notes ref(s). ---no-notes +--patience - Do not show notes. This negates the above --notes option, by - resetting the list of notes refs from which notes are shown. - Options are parsed in the order given on the command line, so e.g. - "--notes --notes=foo --no-notes --notes=bar" will only show notes - from "refs/notes/bar". + Generate a diff using the "patience diff" algorithm. ---show-notes[=<ref>] - - ---[no-]standard-notes +--histogram - These options are deprecated. Use the above --notes/--no-notes - options instead. + Generate a diff using the "histogram diff" algorithm. ---show-signature +--diff-algorithm={patience|minimal|histogram|myers} - Check the validity of a signed commit object by passing the signature - to gpg --verify and show the output. + Choose a diff algorithm. The variants are as follows: - - + ---no-commit-id +default, myers - git diff-tree outputs a line with the commit ID when - applicable. This flag suppressed the commit ID output. + The basic greedy diff algorithm. Currently, this is the default. --c +minimal - This flag changes 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 is what the -m option does). - Furthermore, it lists only files which were modified - from all parents. + Spend extra time to make sure the smallest possible diff is + produced. ---cc +patience - This flag changes the way a merge commit patch is displayed, - in a similar way to the -c option. It implies the -c - and -p options and further compresses the patch output - by omitting uninteresting hunks whose the contents in the parents - have only two variants and the merge result picks one of them - without modification. When all hunks are uninteresting, the commit - itself and the commit log message is not shown, just like in any other - "empty diff" case. + Use "patience diff" algorithm when generating patches. ---always +histogram - Show the commit itself and the commit log message even - if the diff itself is empty. + This algorithm extends the patience algorithm to "support + low-occurrence common elements". - - -PRETTY FORMATS -If the commit is a merge, and if the pretty-format -is not oneline, email or raw, an additional line is -inserted before the Author: line. This line begins with -"Merge: " and the sha1s of ancestral commits are printed, -separated by spaces. Note that the listed commits may not -necessarily be the list of the direct parent commits if you -have limited your view of history: for example, if you are -only interested in changes related to a certain directory or -file. -There are several built-in formats, and you can define -additional formats by setting a pretty.<name> -config option to either another format name, or a -format: string, as described below (see -). Here are the details of the -built-in formats: - - - -oneline - -<sha1> <title line> -This is designed to be as compact as possible. +For instance, if you configured diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option. + + + +--stat[=<width>[,<name-width>[,<count>]]] + -short + Generate a diffstat. By default, as much space as necessary + will be used for the filename part, and the rest for the graph + part. Maximum width defaults to terminal width, or 80 columns + if not connected to a terminal, and can be overridden by + <width>. The width of the filename part can be limited by + giving another width <name-width> after a comma. The width + of the graph part can be limited by using + --stat-graph-width=<width> (affects all commands generating + a stat graph) or by setting diff.statGraphWidth=<width> + (does not affect git format-patch). + By giving a third parameter <count>, you can limit the + output to the first <count> lines, followed by ... if + there are more. -commit <sha1> -Author: <author> -<title line> +These parameters can also be set individually with --stat-width=<width>, +--stat-name-width=<name-width> and --stat-count=<count>. + + + +--numstat + -medium + Similar to --stat, but shows number of added and + deleted lines in decimal notation and pathname without + abbreviation, to make it more machine friendly. For + binary files, outputs two - instead of saying + 0 0. -commit <sha1> -Author: <author> -Date: <author date> -<title line> -<full commit message> + + + +--shortstat + -full + Output only the last line of the --stat format containing total + number of modified files, as well as number of added and deleted + lines. -commit <sha1> -Author: <author> -Commit: <committer> -<title line> -<full commit message> + + + +--dirstat[=<param1,param2,…>] + -fuller + Output the distribution of relative amount of changes for each + sub-directory. The behavior of --dirstat can be customized by + passing it a comma separated list of parameters. + The defaults are controlled by the diff.dirstat configuration + variable (see ). + The following parameters are available: -commit <sha1> -Author: <author> -AuthorDate: <author date> -Commit: <committer> -CommitDate: <committer date> -<title line> -<full commit message> - + + + +changes + -email - -From <sha1> <date> -From: <author> -Date: <author date> -Subject: [PATCH] <title line> -<full commit message> - - - -raw + Compute the dirstat numbers by counting the lines that have been + removed from the source, or added to the destination. This ignores + the amount of pure code movements within a file. In other words, + rearranging lines in a file is not counted as much as other changes. + This is the default behavior when no parameter is given. -The raw format shows the entire commit exactly as -stored in the commit object. Notably, the SHA1s are -displayed in full, regardless of whether --abbrev or ---no-abbrev are used, and parents information show the -true parent commits, without taking grafts nor history -simplification into account. + + + +lines + -format:<string> - -The format:<string> format allows you to specify which information -you want to show. It works a little bit like printf format, -with the notable exception that you get a newline with %n -instead of \n. -E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n" -would show something like this: -The author of fe6e0ee was Junio C Hamano, 23 hours ago -The title was >>t4119: test autocomputing -p<n> for traditional diff input.<< -The placeholders are: - - - -%H: commit hash + Compute the dirstat numbers by doing the regular line-based diff + analysis, and summing the removed/added line counts. (For binary + files, count 64-byte chunks instead, since binary files have no + natural concept of lines). This is a more expensive --dirstat + behavior than the changes behavior, but it does count rearranged + lines within a file as much as other changes. The resulting output + is consistent with what you get from the other --*stat options. + + + +files + -%h: abbreviated commit hash + Compute the dirstat numbers by counting the number of files changed. + Each changed file counts equally in the dirstat analysis. This is + the computationally cheapest --dirstat behavior, since it does + not have to look at the file contents at all. + + + +cumulative + -%T: tree hash + Count changes in a child directory for the parent directory as well. + Note that when using cumulative, the sum of the percentages + reported may exceed 100%. The default (non-cumulative) behavior can + be specified with the noncumulative parameter. + + + +<limit> + -%t: abbreviated tree hash + An integer parameter specifies a cut-off percent (3% by default). + Directories contributing less than this percentage of the changes + are not shown in the output. - - -%P: parent hashes - + + +Example: The following will count changed files, while ignoring +directories with less than 10% of the total amount of changed files, +and accumulating child directory counts in the parent directories: +--dirstat=files,10,cumulative. + + + +--summary + -%p: abbreviated parent hashes + Output a condensed summary of extended header information + such as creations, renames and mode changes. + + + +--patch-with-stat + -%an: author name + Synonym for -p --stat. + + + +-z + -%aN: author name (respecting .mailmap, see or ) + Separate the commits with NULs instead of with new newlines. +Also, when --raw or --numstat has been given, do not munge +pathnames and use NULs as output field terminators. +Without this option, each pathname output will have TAB, LF, double quotes, +and backslash characters replaced with \t, \n, \", and \\, +respectively, and the pathname will be enclosed in double quotes if +any of those replacements occurred. + + + +--name-only + -%ae: author email + Show only names of changed files. + + + +--name-status + -%aE: author email (respecting .mailmap, see or ) + Show only names and status of changed files. See the description + of the --diff-filter option on what the status letters mean. + + + +--submodule[=<format>] + -%ad: author date (format respects --date= option) + Specify how differences in submodules are shown. When --submodule + or --submodule=log is given, the log format is used. This format lists + the commits in the range like summary does. + Omitting the --submodule option or specifying --submodule=short, + uses the short format. This format just shows the names of the commits + at the beginning and end of the range. Can be tweaked via the + diff.submodule configuration variable. + + + +--color[=<when>] + -%aD: author date, RFC2822 style + Show colored diff. + --color (i.e. without =<when>) is the same as --color=always. + <when> can be one of always, never, or auto. + + + +--no-color + -%ar: author date, relative + Turn off colored diff. + It is the same as --color=never. + + + +--word-diff[=<mode>] + -%at: author date, UNIX timestamp + Show a word diff, using the <mode> to delimit changed words. + By default, words are delimited by whitespace; see + --word-diff-regex below. The <mode> defaults to plain, and + must be one of: - + + + +color + -%ai: author date, ISO 8601 format + Highlight changed words using only colors. Implies --color. + + + +plain + -%cn: committer name + Show words as [-removed-] and {+added+}. Makes no + attempts to escape the delimiters if they appear in the input, + so the output may be ambiguous. + + + +porcelain + -%cN: committer name (respecting .mailmap, see or ) + Use a special line-based format intended for script + consumption. Added/removed/unchanged runs are printed in the + usual unified diff format, starting with a +/-/` ` + character at the beginning of the line and extending to the + end of the line. Newlines in the input are represented by a + tilde ~ on a line of its own. + + + +none + -%ce: committer email + Disable word diff again. - - -%cE: committer email (respecting .mailmap, see or ) - + + +Note that despite the name of the first mode, color is used to +highlight the changed parts in all modes if enabled. + + + +--word-diff-regex=<regex> + -%cd: committer date + Use <regex> to decide what a word is, instead of considering + runs of non-whitespace to be a word. Also implies + --word-diff unless it was already enabled. +Every non-overlapping match of the +<regex> is considered a word. Anything between these matches is +considered whitespace and ignored(!) for the purposes of finding +differences. You may want to append |[^[:space:]] to your regular +expression to make sure that it matches all non-whitespace characters. +A match that contains a newline is silently truncated(!) at the +newline. +For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character. +The regex can also be set via a diff driver or configuration option, see + or . Giving it explicitly +overrides any diff driver or configuration setting. Diff drivers +override configuration settings. + + + +--color-words[=<regex>] + -%cD: committer date, RFC2822 style + Equivalent to --word-diff=color plus (if a regex was + specified) --word-diff-regex=<regex>. + + + +--no-renames + -%cr: committer date, relative + Turn off rename detection, even when the configuration + file gives the default to do so. + + + +--check + -%ct: committer date, UNIX timestamp + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by core.whitespace + configuration. By default, trailing whitespaces (including + lines that solely consist of whitespaces) and a space character + that is immediately followed by a tab character inside the + initial indent of the line are considered whitespace errors. + Exits with non-zero status if problems are found. Not compatible + with --exit-code. + + + +--ws-error-highlight=<kind> + -%ci: committer date, ISO 8601 format + Highlight whitespace errors on lines specified by <kind> + in the color specified by color.diff.whitespace. <kind> + is a comma separated list of old, new, context. When + this option is not given, only whitespace errors in new + lines are highlighted. E.g. --ws-error-highlight=new,old + highlights whitespace errors on both deleted and added lines. + all can be used as a short-hand for old,new,context. + + + +--full-index + -%d: ref names, like the --decorate option of - - - - -%e: encoding - - - - -%s: subject - - - - -%f: sanitized subject line, suitable for a filename - - - - -%b: body - - - - -%B: raw body (unwrapped subject and body) - - - - -%N: commit notes - - - - -%GG: raw verification message from GPG for a signed commit - - - - -%G?: show either "G" for Good or "B" for Bad for a signed commit - - - - -%GS: show the name of the signer for a signed commit - - - - -%gD: reflog selector, e.g., refs/stash@{1} - - - - -%gd: shortened reflog selector, e.g., stash@{1} - - - - -%gn: reflog identity name - - - - -%gN: reflog identity name (respecting .mailmap, see or ) - - - - -%ge: reflog identity email - - - - -%gE: reflog identity email (respecting .mailmap, see or ) - - - - -%gs: reflog subject - - - - -%Cred: switch color to red - - - - -%Cgreen: switch color to green + Instead of the first handful of characters, show the full + pre- and post-image blob object names on the "index" + line when generating patch format output. + + + +--binary + -%Cblue: switch color to blue + In addition to --full-index, output a binary diff that + can be applied with git-apply. + + + +--abbrev[=<n>] + -%Creset: reset color + Instead of showing the full 40-byte hexadecimal object + name in diff-raw format output and diff-tree header + lines, show only a partial prefix. This is + independent of the --full-index option above, which controls + the diff-patch output format. Non default number of + digits can be specified with --abbrev=<n>. + + + +-B[<n>][/<m>] + + +--break-rewrites[=[<n>][/<m>]] + -%C(…): color specification, as described in color.branch.* config option + Break complete rewrite changes into pairs of delete and + create. This serves two purposes: +It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number m controls this aspect of the -B +option (defaults to 60%). -B/70% specifies that less than 30% of the +original should remain in the result for Git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines). +When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number n controls this aspect of +the -B option (defaults to 50%). -B20% specifies that a change with +addition and deletion compared to 20% or more of the file's size are +eligible for being picked up as a possible source of a rename to +another file. + + + +-M[<n>] + + +--find-renames[=<n>] + -%m: left, right or boundary mark + If generating diffs, detect and report renames for each commit. + For following files across renames while traversing history, see + --follow. + If n is specified, it is a threshold on the similarity + index (i.e. amount of addition/deletions compared to the + file's size). For example, -M90% means Git should consider a + delete/add pair to be a rename if more than 90% of the file + hasn't changed. Without a % sign, the number is to be read as + a fraction, with a decimal point before it. I.e., -M5 becomes + 0.5, and is thus the same as -M50%. Similarly, -M05 is + the same as -M5%. To limit detection to exact renames, use + -M100%. The default similarity index is 50%. + + + +-C[<n>] + + +--find-copies[=<n>] + -%n: newline + Detect copies as well as renames. See also --find-copies-harder. + If n is specified, it has the same meaning as for -M<n>. + + + +--find-copies-harder + -%%: a raw % + 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. Giving more than one + -C option has the same effect. + + + +-D + + +--irreversible-delete + -%x00: print a byte from a hex code + Omit the preimage for deletes, i.e. print only the header but not + the diff between the preimage and /dev/null. The resulting patch + is not meant to be applied with patch or git apply; this is + solely for people who want to just concentrate on reviewing the + text after the change. In addition, the output obviously lack + enough information to apply such a patch in reverse, even manually, + hence the name of the option. +When used together with -B, omit also the preimage in the deletion part +of a delete/create pair. + + + +-l<num> + -%w([<w>[,<i1>[,<i2>]]]): switch line wrapping, like the -w option of - . + The -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. - - - -Some placeholders may depend on other options given to the -revision traversal engine. For example, the %g* reflog options will -insert an empty string unless we are traversing reflog entries (e.g., by -git log -g). The %d placeholder will use the "short" decoration -format if --decorate was not already provided on the command line. -If you add a + (plus sign) after % of a placeholder, a line-feed -is inserted immediately before the expansion if and only if the -placeholder expands to a non-empty string. -If you add a - (minus sign) after % of a placeholder, line-feeds that -immediately precede the expansion are deleted if and only if the -placeholder expands to an empty string. -If you add a ` ` (space) after % of a placeholder, a space -is inserted immediately before the expansion if and only if the -placeholder expands to a non-empty string. - + + + +--diff-filter=[(A|C|D|M|R|T|U|X|B)…[*]] + -tformat: + Select only files that are Added (A), Copied (C), + Deleted (D), Modified (M), Renamed (R), have their + type (i.e. regular file, symlink, submodule, …) changed (T), + are Unmerged (U), are + Unknown (X), or have had their pairing Broken (B). + Any combination of the filter characters (including none) can be used. + When * (All-or-none) is added to the combination, all + paths are selected if there is any file that matches + other criteria in the comparison; if there is no file + that matches other criteria, nothing is selected. -The tformat: format works exactly like format:, except that it -provides "terminator" semantics instead of "separator" semantics. In -other words, each commit has the message terminator character (usually a -newline) appended, rather than a separator placed between entries. -This means that the final entry of a single-line format will be properly -terminated with a new line, just as the "oneline" format does. -For example: -$ git log -2 --pretty=format:%h 4da45bef \ - | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/' -4da45be -7134973 -- NO NEWLINE - -$ git log -2 --pretty=tformat:%h 4da45bef \ - | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/' -4da45be -7134973 -In addition, any unrecognized string that has a % in it is interpreted -as if it has tformat: in front of it. For example, these two are -equivalent: -$ git log -2 --pretty=tformat:%h 4da45bef -$ git log -2 --pretty=%h 4da45bef - - - -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 --abbrev 5319e4 -:100664 100664 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). - - -Raw output format -The raw output format from "git-diff-index", "git-diff-tree", -"git-diff-files" and "git diff --raw" are very similar. -These commands all compare two sets of things; what is -compared differs: - + -git-diff-index <tree-ish> +-S<string> - compares the <tree-ish> and the files on the filesystem. + Look for differences that change the number of occurrences of + the specified string (i.e. addition/deletion) in a file. + Intended for the scripter's use. +It is useful when you're looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block. -git-diff-index --cached <tree-ish> +-G<regex> - compares the <tree-ish> and the index. + Look for differences whose patch text contains added/removed + lines that match <regex>. +To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file: ++ return !regexec(regexp, two->ptr, 1, &regmatch, 0); +... +- hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0); +While git log -G"regexec\(regexp" will show this commit, git log +-S"regexec\(regexp" --pickaxe-regex will not (because the number of +occurrences of that string did not change). +See the pickaxe entry in for more +information. -git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…] +--pickaxe-all - compares the trees named by the two arguments. + When -S or -G finds a change, show all the changes in that + changeset, not just the files that contain the change + in <string>. -git-diff-files [<pattern>…] +--pickaxe-regex - compares the index and the files on the filesystem. + Treat the <string> given to -S as an extended POSIX regular + expression to match. - -The "git-diff-tree" command begins its output by printing the hash of -what is being compared. After that, all the commands print one output -line per changed file. -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. - - + + +-O<orderfile> + -path for "src" + Output the patch in the order specified in the + <orderfile>, which has one shell glob pattern per line. + This overrides the diff.orderFile configuration variable + (see ). To cancel diff.orderFile, + use -O/dev/null. + + + +-R + -a tab or a NUL when -z option is used; only exists for C or R. + Swap two inputs; that is, show differences from index or + on-disk file to tree contents. + + + +--relative[=<path>] + -path for "dst"; only exists for C or R. + When run from a subdirectory of the project, it can be + told to exclude changes outside the directory and show + pathnames relative to it with this option. When you are + not in a subdirectory (e.g. in a bare repository), you + can name which subdirectory to make the output relative + to by giving a <path> as an argument. + + + +-a + + +--text + -an LF or a NUL when -z option is used, to terminate the record. + Treat all files as text. - -Possible status letters are: - + + + +--ignore-space-at-eol + -A: addition of a file + Ignore changes in whitespace at EOL. + + + +-b + + +--ignore-space-change + -C: copy of a file into a new one + Ignore changes in amount of whitespace. This ignores whitespace + at line end, and considers all other sequences of one or + more whitespace characters to be equivalent. + + + +-w + + +--ignore-all-space + -D: deletion of a file + Ignore whitespace when comparing lines. This ignores + differences even if one line has whitespace where the other + line has none. + + + +--ignore-blank-lines + -M: modification of the contents or mode of a file + Ignore changes whose lines are all blank. + + + +--inter-hunk-context=<lines> + -R: renaming of a file + Show the context between diff hunks, up to the specified number + of lines, thereby fusing hunks that are close to each other. + + + +-W + + +--function-context + -T: change in the type of the file + Show whole surrounding functions of changes. + + + +--ext-diff + -U: file is unmerged (you must complete the merge before it can -be committed) + Allow an external diff helper to be executed. If you set an + external diff driver with , you need + to use this option with and friends. + + + +--no-ext-diff + -X: "unknown" change type (most probably a bug, please report it) + Disallow external diff drivers. - -Status letters C and R are always followed by a score (denoting the -percentage of similarity between the source and target of the move or -copy), and are the only ones to be so. -<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. - - -diff format for merges -"git-diff-tree", "git-diff-files" and "git-diff --raw" -can take -c or --cc option -to generate diff output also for merge commits. The output differs -from the format described above in the following way: - + + + +--textconv + + +--no-textconv + -there is a colon for each parent + Allow (or disallow) external text conversion filters to be run + when comparing binary files. See for + details. Because textconv filters are typically a one-way + conversion, the resulting diff is suitable for human + consumption, but cannot be applied. For this reason, textconv + filters are enabled by default only for and + , but not for or + diff plumbing commands. + + + +--ignore-submodules[=<when>] + -there are more "src" modes and "src" sha1 + Ignore changes to submodules in the diff generation. <when> can be + either "none", "untracked", "dirty" or "all", which is the default. + Using "none" will consider the submodule modified when it either contains + untracked or modified files or its HEAD differs from the commit recorded + in the superproject and can be used to override any settings of the + ignore option in or . When + "untracked" is used submodules are not considered dirty when they only + contain untracked content (but they are still scanned for modified + content). Using "dirty" ignores all changes to the work tree of submodules, + only changes to the commits stored in the superproject are shown (this was + the behavior until 1.7.0). Using "all" hides all changes to submodules. + + + +--src-prefix=<prefix> + -status is concatenated status characters for each parent + Show the given source prefix instead of "a/". + + + +--dst-prefix=<prefix> + -no optional "score" number + Show the given destination prefix instead of "b/". + + + +--no-prefix + -single path, only for "dst" + Do not show any source or destination prefix. - -Example: -::100644 100644 100644 fabadb8... cc95eb0... 4866510... MM describe.c -Note that combined diff lists only files which were modified from -all parents. + + +For more detailed explanation on these common options, see also +. - + Generating patches with -p When "git-diff-index", "git-diff-tree", or "git-diff-files" are run with a -p option, "git diff" without the --raw option, or @@ -1970,12 +1760,12 @@ rename to a - + combined diff format -Any diff-generating command can take the -c` or --cc option to +Any diff-generating command can take the -c or --cc option to produce a combined diff when showing a merge. This is the default format when showing merges with or -. Note also that you can give the `-m option to any +. Note also that you can give the -m option to any of these commands to force generation of diffs with individual parents of a merge. A combined diff format looks like this: @@ -2070,7 +1860,7 @@ added, from the point of view of that parent). 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 eight other lines are the same +in either file1 or file2). Also eight 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 @@ -2079,113 +1869,148 @@ 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"). - -other diff formats -The --summary option describes newly added, deleted, renamed and -copied files. The --stat option adds diffstat(1) graph to the -output. These options can be combined with other options, such as --p, and are meant for human consumption. -When showing a change that involves a rename or a copy, --stat output -formats the pathnames compactly by combining common prefix and suffix of -the pathnames. For example, a change that moves arch/i386/Makefile to -arch/x86/Makefile while modifying 4 lines will be shown like this: -arch/{i386 => x86}/Makefile | 4 +-- -The --numstat option gives the diffstat(1) information but is designed -for easier machine consumption. An entry in --numstat output looks -like this: -1 2 README -3 1 arch/{i386 => x86}/Makefile -That is, from left to right: - - - -the number of added lines; - - - - -a tab; - - - - -the number of deleted lines; - - - - -a tab; - - - - -pathname (possibly with rename/copy information); - - + +EXAMPLES + + + +git show v1.0.0 + -a newline. + Shows the tag v1.0.0, along with the object the tags + points at. - -When -z output option is in effect, the output is formatted this way: -1 2 README NUL -3 1 NUL arch/i386/Makefile NUL arch/x86/Makefile NUL -That is: - + + + +git show v1.0.0^{tree} + -the number of added lines; + Shows the tree pointed to by the tag v1.0.0. + + + +git show -s --format=%s v1.0.0^{commit} + -a tab; + Shows the subject of the commit pointed to by the + tag v1.0.0. + + + +git show next~10:Documentation/README + -the number of deleted lines; + Shows the contents of the file Documentation/README as + they were current in the 10th last commit of the branch + next. + + + +git show master:Makefile master:t/Makefile + -a tab; + Concatenates the contents of said Makefiles in the head + of the branch master. + + + + +Discussion +Git is to some extent character encoding agnostic. + -a NUL (only exists if renamed/copied); +The contents of the blob objects are uninterpreted sequences + of bytes. There is no encoding translation at the core + level. -pathname in preimage; +Path names are encoded in UTF-8 normalization form C. This + applies to tree objects, the index file, ref names, as well as + path names in command line arguments, environment variables + and config files (.git/config (see ), + , and + ). +Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly. -a NUL (only exists if renamed/copied); +Commit log messages are typically encoded in UTF-8, but other + extended ASCII encodings are also supported. This includes + ISO-8859-x, CP125x and many others, but not UTF-16/32, + EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, + EUC-x, CP9xx etc.). + +Although we encourage that the commit log messages are encoded +in UTF-8, both the core and Git Porcelain are designed not to +force UTF-8 on projects. If all participants of a particular +project find it more convenient to use legacy encodings, Git +does not forbid it. However, there are a few things to keep in +mind. + -pathname in postimage (only exists if renamed/copied); +git commit and git commit-tree issues + a warning if the commit log message given to it does not look + like a valid UTF-8 string, unless you explicitly say your + project uses a legacy encoding. The way to say this is to + have i18n.commitencoding in .git/config file, like this: +[i18n] + commitencoding = ISO-8859-1 +Commit objects created with the above setting record the value +of i18n.commitencoding in its encoding header. This is to +help other people who look at them later. Lack of this header +implies that the commit log message is encoded in UTF-8. -a NUL. +git log, git show, git blame and friends look at the + encoding header of a commit object, and try to re-code the + log message into UTF-8 unless otherwise specified. You can + specify the desired output encoding with + i18n.logoutputencoding in .git/config file, like this: +[i18n] + logoutputencoding = ISO-8859-1 +If you do not have this configuration variable, the value of +i18n.commitencoding is used instead. -The extra NUL before the preimage path in renamed case is to allow -scripts that read the output to tell if the current record being read is -a single-path record or a rename/copy record without reading ahead. -After reading added and deleted lines, reading up to NUL would yield -the pathname, but if that is NUL, the record will show two paths. +Note that we deliberately chose not to re-code the commit log +message when a commit is made to force UTF-8 at the commit +object level, because re-coding to UTF-8 is not necessarily a +reversible operation. - + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/git-stash.xml b/doc/source/en/TortoiseGit/git_doc/git-stash.xml index a7ebbc7a3..cc5f85b4a 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-stash.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-stash.xml @@ -18,10 +18,11 @@ git stash drop [-q|--quiet] [<stash>] git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>] git stash branch <branchname> [<stash>] -git stash [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] +git stash [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] [-u|--include-untracked] [-a|--all] [<message>]] git stash clear -git stash create +git stash create [<message>] +git stash store [-m|--message <message>] [-q|--quiet] <commit> @@ -48,7 +49,7 @@ is also possible). -save [-p|--patch] [--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>] +save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>] @@ -105,6 +106,8 @@ show [<stash>] shows the latest one. By default, the command shows the diffstat, but it will accept any format known to git diff (e.g., git stash show -p stash@{1} to view the second most recent stash in patch form). + You can use stash.showStat and/or stash.showPatch config variables + to change the default behavior. @@ -195,6 +198,21 @@ create Create a stash (which is a regular commit object) and return its object name, without storing it anywhere in the ref namespace. + This is intended to be useful for scripts. It is probably not + the command you want to use; see "save" above. + + + + + +store + + + + Store a given stash created via git stash create (which is a + dangling merge commit) in the stash ref, updating the stash + reflog. This is intended to be useful for scripts. It is + probably not the command you want to use; see "save" above. diff --git a/doc/source/en/TortoiseGit/git_doc/git-status.xml b/doc/source/en/TortoiseGit/git_doc/git-status.xml index d62ffac78..57f87c658 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-status.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-status.xml @@ -21,7 +21,7 @@ Displays paths that have differences between the index file and the current HEAD commit, paths that have differences between the working tree and the index file, and paths in the working tree that are not -tracked by git (and are not ignored by ). The first +tracked by Git (and are not ignored by ). The first are what you would commit by running git commit; the second and third are what you could commit by running git add before running git commit. @@ -63,7 +63,7 @@ third are what you could commit by running git ad Give the output in an easy-to-parse format for scripts. This is similar to the short output, but will remain stable - across git versions and regardless of user configuration. See + across Git versions and regardless of user configuration. See below for details. @@ -80,6 +80,23 @@ third are what you could commit by running git ad +-v + + +--verbose + + + + In addition to the names of files that have been changed, also + show the textual changes that are staged to be committed + (i.e., like the output of git diff --cached). If -v is specified + twice, then also show the changes in the working tree that + have not yet been staged (i.e., like the output of git diff). + + + + + -u[<mode>] @@ -89,25 +106,34 @@ third are what you could commit by running git ad Show untracked files. -The mode parameter is optional (defaults to all), and is used to -specify the handling of untracked files; when -u is not used, the -default is normal, i.e. show untracked files and directories. +The mode parameter is used to specify the handling of untracked files. +It is optional: it defaults to all, and if specified, it must be +stuck to the option (e.g. -uno, but not -u no). The possible options are: -no - Show no untracked files +no - Show no untracked files. -normal - Shows untracked files and directories +normal - Shows untracked files and directories. all - Also shows individual files in untracked directories. +When -u option is not used, untracked files and directories are +shown (i.e. the same as specifying normal), to help you avoid +forgetting to add newly created files. Because it takes extra work +to find untracked files in the filesystem, this mode may take some +time in a large working tree. +Consider enabling untracked cache and split index if supported (see +git update-index --untracked-cache and git update-index +--split-index), Otherwise you can use no to have git status +return more quickly without showing untracked files. The default can be changed using the status.showUntrackedFiles configuration variable documented in . @@ -132,7 +158,7 @@ configuration variable documented in . only changes to the commits stored in the superproject are shown (this was the behavior before 1.7.0). Using "all" hides all changes to submodules (and suppresses the output of submodule summaries when the config option - status.submodulesummary is set). + status.submoduleSummary is set). @@ -178,11 +204,11 @@ configuration variable documented in . OUTPUT The output from this command is designed to be used as a commit -template comment, and all the output lines are prefixed with #. +template comment. The default, long format, is designed to be human readable, verbose and descriptive. Its contents and format are subject to change at any time. -The paths mentioned in the output, unlike many other git commands, are +The paths mentioned in the output, unlike many other Git commands, are made relative to the current directory if you are working in a subdirectory (this is on purpose, to help cutting and pasting). See the status.relativePaths config option below. @@ -272,7 +298,7 @@ U U unmerged, both modified
Porcelain Format The porcelain format is similar to the short format, but is guaranteed -not to change in a backwards-incompatible way between git versions or +not to change in a backwards-incompatible way between Git versions or based on user configuration. This makes it ideal for parsing by scripts. The description of the short format above also describes the porcelain format, with a few exceptions: @@ -310,10 +336,16 @@ to colorize its output. If the config variable status.relativePaths is set to false, then all paths shown are relative to the repository root, not to the current directory. -If status.submodulesummary is set to a non zero number or true (identical +If status.submoduleSummary is set to a non zero number or true (identical to -1 or an unlimited number), the submodule summary will be enabled for the long format and a summary of commits for modified submodules will be -shown (see --summary-limit option of ). +shown (see --summary-limit option of ). Please note +that the summary output from the status command will be suppressed for all +submodules when diff.ignoreSubmodules is set to all or only for those +submodules where submodule.<name>.ignore=all. To also view the summary for +ignored submodules you can either use the --ignore-submodules=dirty command +line option or the git submodule summary command, which shows a similar +output but does not honor these settings. SEE ALSO diff --git a/doc/source/en/TortoiseGit/git_doc/git-stripspace.xml b/doc/source/en/TortoiseGit/git_doc/git-stripspace.xml index acccd17c6..195ad3fa9 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-stripspace.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-stripspace.xml @@ -13,13 +13,15 @@ SYNOPSIS
-git stripspace [-s | --strip-comments] < input +git stripspace [-s | --strip-comments] +git stripspace [-c | --comment-lines]
DESCRIPTION -Clean the input in the manner used by git for text such as commit -messages, notes, tags and branch descriptions. +Read text, such as commit messages, notes, tags and branch +descriptions, from the standard input and clean it in the manner +used by Git. With no arguments, this will: @@ -61,7 +63,22 @@ the repository. - Skip and remove all lines starting with #. + Skip and remove all lines starting with comment character (default #). + + + + + +-c + + +--comment-lines + + + + Prepend comment character and blank to each line. Lines will automatically + be terminated with a newline. On empty lines, only the comment character + will be prepended. diff --git a/doc/source/en/TortoiseGit/git_doc/git-submodule.xml b/doc/source/en/TortoiseGit/git_doc/git-submodule.xml index 19053eaa9..bb041b51b 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-submodule.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-submodule.xml @@ -14,24 +14,40 @@ SYNOPSIS
git submodule [--quiet] add [-b <branch>] [-f|--force] [--name <name>] - [--reference <repository>] [--] <repository> [<path>] + [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] git submodule [--quiet] status [--cached] [--recursive] [--] [<path>…] git submodule [--quiet] init [--] [<path>…] -git submodule [--quiet] update [--init] [-N|--no-fetch] [--rebase] - [--reference <repository>] [--merge] [--recursive] [--] [<path>…] +git submodule [--quiet] deinit [-f|--force] [--] <path>… +git submodule [--quiet] update [--init] [--remote] [-N|--no-fetch] + [-f|--force] [--rebase|--merge] [--reference <repository>] + [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>…] git submodule [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>…] git submodule [--quiet] foreach [--recursive] <command> -git submodule [--quiet] sync [--] [<path>…] +git submodule [--quiet] sync [--recursive] [--] [<path>…]
DESCRIPTION -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. -They are not to be confused with remotes, which are meant mainly -for branches of the same project; submodules are meant for +Inspects, updates and manages submodules. +A submodule allows you to keep another Git repository in a subdirectory +of your repository. The other repository has its own history, which does not +interfere with the history of the current repository. This can be used to +have external dependencies such as third party libraries for example. +When cloning or pulling a repository containing submodules however, +these will not be checked out by default; the init and update +subcommands will maintain submodules checked out and at +appropriate revision in your working tree. +Submodules are composed from a so-called gitlink tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the .gitmodules (see ) file at the +root of the source tree assigns a logical name to the submodule and +describes the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see submodule init). +Submodules are not to be confused with remotes, which are other +repositories of the same project; submodules are meant for different projects you would like to make part of your source tree, while the history of the two projects still stays completely independent and you cannot modify the contents of the submodule @@ -42,26 +58,6 @@ add a remote for the other project and use the subtree merg instead of treating the other project as a submodule. Directories that come from both projects can be cloned and checked out as a whole if you choose to go that route. -Submodules are composed from a so-called gitlink tree entry -in the main repository that refers to a particular commit object -within the inner repository that is completely separate. -A record in the .gitmodules (see ) file at the -root of the source tree assigns a logical name to the submodule and -describes the default URL the submodule shall be cloned from. -The logical name can be used for overriding this URL within your -local repository configuration (see submodule init). -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. -When adding a new submodule to the tree, the add subcommand -is to be used. However, when pulling a tree containing submodules, -these will not be checked out by default; -the init and update subcommands will maintain submodules -checked out and at appropriate revision in your working tree. -You can briefly inspect the up-to-date status of your submodules -using the status subcommand and get a detailed overview of the -difference between the index and checkouts using the summary -subcommand. COMMANDS @@ -80,7 +76,9 @@ add argument <path> is the relative location for the cloned submodule to exist in the superproject. If <path> is not given, the "humanish" part of the source repository is used ("repo" for -"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). +"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). +The <path> is also used as the submodule's logical name in its +configuration entries unless --name is used to specify a logical name. <repository> is the URL of the new submodule's origin repository. This may be either an absolute URL, or (if it begins with ./ or ../), the location relative to the superproject's origin @@ -95,7 +93,7 @@ working directory is used instead. <path> is the relative location for the cloned submodule to exist in the superproject. If <path> does not exist, then the submodule is created by cloning from the named URL. If <path> does -exist and is already a valid git repository, then this is added +exist and is already a valid Git repository, then this is added to the changeset without cloning. This second form is provided to ease creating a new submodule from scratch, and presumes the user will later push the submodule to the given URL. @@ -136,8 +134,10 @@ init - Initialize the submodules, i.e. register each submodule name - and url found in .gitmodules into .git/config. + Initialize the submodules recorded in the index (which were + added and committed elsewhere) by copying submodule + names and urls from .gitmodules to .git/config. + Optional <path> arguments limit which submodules will be initialized. It will also copy the value of submodule.$name.update into .git/config. The key used in .git/config is submodule.$name.url. @@ -152,26 +152,100 @@ init +deinit + + + + Unregister the given submodules, i.e. remove the whole + submodule.$name section from .git/config together with their work + tree. Further calls to git submodule update, git submodule foreach + and git submodule sync will skip any unregistered submodules until + they are initialized again, so use this command if you don't want to + have a local checkout of the submodule in your work tree anymore. If + you really want to remove a submodule from the repository and commit + that use instead. + +If --force is specified, the submodule's work tree will be removed even if +it contains local modifications. + + + + update +Update the registered submodules to match what the superproject +expects by cloning missing submodules and updating the working tree of +the submodules. The "updating" can be done in several ways depending +on command line options and the value of submodule.<name>.update +configuration variable. Supported update procedures are: + + + +checkout + + + +the commit recorded in the superproject will be + checked out in the submodule on a detached HEAD. This is + done when --checkout option is given, or no option is + given, and submodule.<name>.update is unset, or if it is + set to checkout. + +If --force is specified, the submodule will be checked out (using +git checkout --force if appropriate), even if the commit specified +in the index of the containing repository already matches the commit +checked out in the submodule. + + + + +rebase + + + +the current branch of the submodule will be rebased + onto the commit recorded in the superproject. This is done + when --rebase option is given, or no option is given, and + submodule.<name>.update is set to rebase. + + + + + +merge + + - Update the registered submodules, i.e. clone missing submodules and - checkout the commit specified in the index of the containing repository. - This will make the submodules HEAD be detached unless --rebase or - --merge is specified or the key submodule.$name.update is set to - rebase, merge or none. none can be overridden by specifying - --checkout. +the commit recorded in the superproject will be merged + into the current branch in the submodule. This is done + when --merge option is given, or no option is given, and + submodule.<name>.update is set to merge. + + + + +custom command + + + +arbitrary shell command that takes a single + argument (the sha1 of the commit recorded in the + superproject) is executed. This is done when no option is + given, and submodule.<name>.update has the form of + !command. + + + + +When no option is given and submodule.<name>.update is set to none, +the submodule is not updated. If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the submodule with the --init option. If --recursive is specified, this command will recurse into the registered submodules, and update any nested submodules within. -If --force is specified, the submodule will be checked out (using -git checkout --force if appropriate), even if the commit specified in the -index of the containing repository already matches the commit checked out in -the submodule. @@ -235,6 +309,8 @@ sync "git submodule sync" synchronizes all submodules while "git submodule sync -- A" synchronizes submodule "A" only. +If --recursive is specified, this command will recurse into the +registered submodules, and sync any nested submodules within. @@ -265,6 +341,8 @@ sync Branch of repository to add as submodule. + The name of the branch is recorded as submodule.<name>.branch in + .gitmodules for update --remote. @@ -277,12 +355,16 @@ sync - This option is only valid for add and update commands. + This option is only valid for add, deinit and update commands. When running add, allow adding an otherwise ignored submodule path. - When running update, throw away local changes in submodules when - switching to a different commit; and always run a checkout operation - in the submodule, even if the commit listed in the index of the - containing repository matches the commit checked out in the submodule. + When running deinit the submodule work trees will be removed even if + they contain local changes. + When running update (only effective with the checkout procedure), + throw away local changes in submodules when switching to a + different commit; and always run a checkout operation in the + submodule, even if the commit listed in the index of the + containing repository matches the commit checked out in the + submodule. @@ -329,6 +411,41 @@ sync +--remote + + + + This option is only valid for the update command. Instead of using + the superproject's recorded SHA-1 to update the submodule, use the + status of the submodule's remote-tracking branch. The remote used + is branch's remote (branch.<name>.remote), defaulting to origin. + The remote branch used defaults to master, but the branch name may + be overridden by setting the submodule.<name>.branch option in + either .gitmodules or .git/config (with .git/config taking + precedence). + +This works for any of the supported update procedures (--checkout, +--rebase, etc.). The only change is the source of the target SHA-1. +For example, submodule update --remote --merge will merge upstream +submodule changes into the submodules, while submodule update +--merge will merge superproject gitlink changes into the submodules. +In order to ensure a current tracking branch state, update --remote +fetches the submodule's remote repository before calculating the +SHA-1. If you don't want to fetch, you should use submodule update +--remote --no-fetch. +Use this option to integrate changes from the upstream subproject with +your submodule's current HEAD. Alternatively, you can run git pull +from the submodule, which is equivalent except for the remote branch +name: update --remote uses the default upstream repository and +submodule.<name>.branch, while git pull uses the submodule's +branch.<name>.merge. Prefer submodule.<name>.branch if you want +to distribute the default upstream branch with the superproject and +branch.<name>.merge if you want a more native feel while working in +the submodule itself. + + + + -N @@ -343,6 +460,22 @@ sync +--checkout + + + + This option is only valid for the update command. + Checkout the commit recorded in the superproject on a detached HEAD + in the submodule. This is the default behavior, the main use of + this option is to override submodule.$name.update when set to + a value other than checkout. + If the key submodule.$name.update is either not explicitly set or + set to checkout, this option is implicit. + + + + + --merge @@ -418,7 +551,7 @@ for 's --reference and - This option is only valid for foreach, update and status commands. + This option is only valid for foreach, update, status and sync commands. Traverse submodules recursively. The operation is performed not only in the submodules of the current repo, but also in any nested submodules inside those submodules (and so on). @@ -427,6 +560,33 @@ for 's --reference and +--depth + + + + This option is valid for add and update commands. Create a shallow + clone with a history truncated to the specified number of revisions. + See + + + + + +-j <n> + + +--jobs <n> + + + + This option is only valid for the update command. + Clone new submodules in parallel with as many jobs. + Defaults to the submodule.fetchJobs option. + + + + + <path>… diff --git a/doc/source/en/TortoiseGit/git_doc/git-svn.xml b/doc/source/en/TortoiseGit/git_doc/git-svn.xml index 003491a61..ffe3fc506 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-svn.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-svn.xml @@ -8,7 +8,7 @@ NAME -git-svn - Bidirectional operation between a Subversion repository and git +git-svn - Bidirectional operation between a Subversion repository and Git SYNOPSIS @@ -18,16 +18,16 @@ DESCRIPTION -git svn is a simple conduit for changesets between Subversion and git. -It provides a bidirectional flow of changes between a Subversion and a git +git svn is a simple conduit for changesets between Subversion and Git. +It provides a bidirectional flow of changes between a Subversion and a Git repository. git svn can track a standard Subversion repository, following the common "trunk/branches/tags" layout, with the --stdlayout option. It can also follow branches and tags in any layout with the -T/-t/-b options (see options to init below, and also the clone command). -Once tracking a Subversion repository (with any of the above methods), the git +Once tracking a Subversion repository (with any of the above methods), the Git repository can be updated from Subversion by the fetch command and -Subversion updated from git by the dcommit command. +Subversion updated from Git by the dcommit command. COMMANDS @@ -38,7 +38,7 @@ Subversion updated from git by the dcommit command. - Initializes an empty git repository with additional + Initializes an empty Git repository with additional metadata directories for git svn. The Subversion URL may be specified as a command-line argument, or as full URL arguments to -T/-t/-b. Optionally, the target @@ -147,8 +147,8 @@ Subversion updated from git by the dcommit command. For transports that SVN handles authentication for (http, https, and plain svn), specify the username. For other - transports (eg svn+ssh://), you must include the username in - the URL, eg svn+ssh://foo@svn.bar.com/project + transports (e.g. svn+ssh://), you must include the username in + the URL, e.g. svn+ssh://foo@svn.bar.com/project @@ -164,9 +164,21 @@ Subversion updated from git by the dcommit command.", which is + compatible with Git's own remote-tracking ref layout + (refs/remotes/$remote/). Setting a prefix is also useful + if you wish to track multiple projects that share a common + repository. + By default, the prefix is set to origin/. +Before Git v2.0, the default prefix was "" (no prefix). This +meant that SVN-tracking refs were put at "refs/remotes/*", which is +incompatible with how Git's own remote-tracking refs are organized. +If you still want the old default, you can get it by passing +--prefix "" on the command line (--prefix="" may not work if +your Perl's Getopt::Long is < v2.37). @@ -183,6 +195,18 @@ Subversion updated from git by the dcommit command. +--include-paths=<regex> + + + + When passed to init or clone this regular expression will + be preserved as a config key. See fetch for a description + of --include-paths. + + + + + --no-minimize-url @@ -211,9 +235,11 @@ Subversion updated from git by the dcommit command. Fetch unfetched revisions from the Subversion remote we are tracking. The name of the [svn-remote "…"] section in the - .git/config file may be specified as an optional command-line - argument. + $GIT_DIR/config file may be specified as an optional + command-line argument. +This automatically updates the rev_map if needed (see +$GIT_DIR/svn/**/.rev_map.* in the FILES section below for details). @@ -221,15 +247,15 @@ Subversion updated from git by the dcommit command. - Store Git commit times in the local timezone instead of UTC. This + Store Git commit times in the local time zone instead of UTC. This makes git log (even without --date=local) show the same times - that svn log would in the local timezone. + that svn log would in the local time zone. This doesn't interfere with interoperating with the Subversion repository you cloned from, but if you wish for your local Git repository to be able to interoperate with someone else's local Git repository, either don't use this option or you should both use it in -the same local timezone. +the same local time zone. @@ -257,8 +283,8 @@ the same local timezone.
config key: svn-remote.<name>.ignore-paths
-If the ignore-paths config key is set and the command line option is -also given, both regular expressions will be used. +If the ignore-paths configuration key is set, and the command-line +option is also given, both regular expressions will be used. Examples: @@ -282,15 +308,33 @@ Skip "branches" and "tags" of first level directories +--include-paths=<regex> + + + + This allows one to specify a Perl regular expression that will + cause the inclusion of only matching paths from checkout from SVN. + The --include-paths option should match for every fetch + (including automatic fetches due to clone, dcommit, + rebase, etc) on a given repository. --ignore-paths takes + precedence over --include-paths. + +
+config key: svn-remote.<name>.include-paths +
+ + + + --log-window-size=<n> - Fetch <n> log entries per request when scanning Subversion history. - The default is 100. For very large Subversion repositories, larger - values may be needed for clone/fetch to complete in reasonable - time. But overly large values may lead to higher memory usage and - request timeouts. + Fetch <n> log entries per request when scanning Subversion history. + The default is 100. For very large Subversion repositories, larger + values may be needed for clone/fetch to complete in reasonable + time. But overly large values may lead to higher memory usage and + request timeouts. @@ -359,6 +403,8 @@ accept. However, --fetch-all only fetches from the current [svn-remote], and not all [svn-remote] definitions. Like git rebase; this requires that the working tree be clean and have no uncommitted changes. +This automatically updates the rev_map if needed (see +$GIT_DIR/svn/**/.rev_map.* in the FILES section below for details). @@ -386,9 +432,9 @@ and have no uncommitted changes. Commit each diff from the current branch directly to the SVN repository, and then rebase or reset (depending on whether or not there is a diff between SVN and head). This will create - a revision in SVN for each commit in git. + a revision in SVN for each commit in Git. -When an optional git branch name (or a git commit object name) +When an optional Git branch name (or a Git commit object name) is specified as an argument, the subcommand works on the specified branch, not on the current branch. Use of dcommit is preferred to set-tree (below). @@ -419,6 +465,9 @@ branch, not on the current branch. config key: svn-remote.<name>.commiturl config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) +Note that the SVN URL of the commiturl config key includes the SVN branch. +If you rather want to set the commit URL for an entire SVN repository use +svn-remote.<name>.pushurl instead. Using this option for any other purpose (don't ask) is very strongly discouraged. @@ -454,10 +503,9 @@ first have already been pushed into SVN. Ask the user to confirm that a patch set should actually be sent to SVN. For each patch, one may answer "yes" (accept this patch), "no" (discard this patch), "all" (accept all patches), or "quit". - - git svn dcommit returns immediately if answer if "no" or "quit", without - commiting anything to SVN. +git svn dcommit returns immediately if answer is "no" or "quit", without +committing anything to SVN. @@ -501,18 +549,19 @@ first have already been pushed into SVN. --d +-d<path> ---destination +--destination=<path> If more than one --branches (or --tags) option was given to the init or clone command, you must provide the location of the branch (or - tag) you wish to create in the SVN repository. The value of this - option must match one of the paths specified by a --branches (or - --tags) option. You can see these paths with the commands + tag) you wish to create in the SVN repository. <path> specifies which + path to use to create the branch or tag and should match the pattern + on the left-hand side of one of the configured branches or tags + refspecs. You can see these refspecs with the commands git config --get-all svn-remote.<name>.branches git config --get-all svn-remote.<name>.tags @@ -545,6 +594,18 @@ git config --get-all svn-remote.<name>.tags git config --get-all svn-remote.<name>.commiturl + + +--parents + + + + Create parent folders. This parameter is equivalent to the parameter + --parents on svn cp commands and is useful for non-standard repository + layouts. + + + @@ -628,7 +689,7 @@ git config --get-all svn-remote.<name>.tags - shows the git commit sha1, as well + shows the Git commit sha1, as well @@ -655,12 +716,12 @@ environment). This command has the same behaviour. - Show what revision and author last modified each line of a file. The - output of this mode is format-compatible with the output of - svn blame by default. Like the SVN blame command, - local uncommitted changes in the working tree are ignored; - the version of the file in the HEAD revision is annotated. Unknown - arguments are passed directly to git blame. + Show what revision and author last modified each line of a file. The + output of this mode is format-compatible with the output of + svn blame by default. Like the SVN blame command, + local uncommitted changes in the working tree are ignored; + the version of the file in the HEAD revision is annotated. Unknown + arguments are passed directly to git blame. @@ -670,7 +731,7 @@ environment). This command has the same behaviour. Produce output in the same format as git blame, but with - SVN revision numbers instead of git commit hashes. In this mode, + SVN revision numbers instead of Git commit hashes. In this mode, changes that haven't been committed to SVN (including local working-copy edits) are shown as revision 0. @@ -686,10 +747,42 @@ environment). This command has the same behaviour. When given an SVN revision number of the form rN, returns the - corresponding git commit hash (this can optionally be followed by a + corresponding Git commit hash (this can optionally be followed by a tree-ish to specify which branch should be searched). When given a tree-ish, returns the corresponding SVN revision number. + + + +-B + + +--before + + + + Don't require an exact match if given an SVN revision, instead find + the commit corresponding to the state of the SVN repository (on the + current branch) at the specified revision. + + + + + +-A + + +--after + + + + Don't require an exact match if given an SVN revision; if there is + not an exact match return the closest match searching forward in the + history. + + + + @@ -739,7 +832,7 @@ environment). This command has the same behaviour. - Attempts to recreate empty directories that core git cannot track + Attempts to recreate empty directories that core Git cannot track based on information in $GIT_DIR/svn/<refname>/unhandled.log files. Empty directories are automatically recreated when using "git svn clone" and "git svn rebase", so "mkdirs" is intended @@ -819,8 +912,8 @@ environment). This command has the same behaviour. - Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn - and remove $GIT_DIR/svn/<refname>index files in .git/svn. + Compress $GIT_DIR/svn/<refname>/unhandled.log files and remove + $GIT_DIR/svn/<refname>/index files. @@ -840,9 +933,10 @@ environment). This command has the same behaviour. file cannot be ignored forever (with --ignore-paths) the only way to repair the repo is to use reset. -Only the rev_map and refs/remotes/git-svn are changed. Follow reset -with a fetch and then git reset or git rebase to move local -branches onto the new tree. +Only the rev_map and refs/remotes/git-svn are changed (see +$GIT_DIR/svn/**/.rev_map.* in the FILES section below for details). +Follow reset with a fetch and then git reset or git rebase to +move local branches onto the new tree. @@ -970,9 +1064,9 @@ order. Only the leading sha1 is read from each line, so Remove directories from the SVN tree if there are no files left behind. SVN can version empty directories, and they are not -removed by default if there are no files left in them. git +removed by default if there are no files left in them. Git cannot version empty directories. Enabling this flag will make -the commit to SVN act like git. +the commit to SVN act like Git.
config key: svn.rmdir
@@ -1068,28 +1162,6 @@ after the authors-file is modified should continue operation. ---repack[=<n>] - - ---repack-flags=<flags> - - - - These should help keep disk usage sane for large fetches with - many revisions. - ---repack takes an optional argument for the number of revisions -to fetch before repacking. This defaults to repacking every -1000 commits fetched if no argument is specified. ---repack-flags are passed directly to git repack. -
-config key: svn.repack -config key: svn.repackflags -
- - - - -m @@ -1127,7 +1199,7 @@ config key: svn.repackflags This can be used with the dcommit, rebase, branch and tag commands. -For dcommit, print out the series of git arguments that would show +For dcommit, print out the series of Git arguments that would show which diffs would be committed to SVN. For rebase, display the local branch associated with the upstream svn repository associated with the current branch and the URL of svn @@ -1142,7 +1214,7 @@ creating the branch or tag. - When retrieving svn commits into git (as part of fetch, rebase, or + When retrieving svn commits into Git (as part of fetch, rebase, or dcommit operations), look for the first From: or Signed-off-by: line in the log message and use that as the author string. @@ -1154,10 +1226,10 @@ creating the branch or tag. - When committing to svn from git (as part of commit-diff, set-tree or dcommit + When committing to svn from Git (as part of commit-diff, set-tree or dcommit operations), if the existing log message doesn't already have a From: or Signed-off-by: line, append a From: line based on the - git commit's author string. If you use this, then --use-log-author + Git commit's author string. If you use this, then --use-log-author will retrieve a valid author string for all commits. @@ -1208,7 +1280,7 @@ creating the branch or tag. one of the repository layout options --trunk, --tags, --branches, --stdlayout). For each tracked branch, try to find out where its revision was copied from, and set - a suitable parent in the first git commit for the branch. + a suitable parent in the first Git commit for the branch. This is especially helpful when we're tracking a directory that has been moved around within the repository. If this feature is disabled, the branches created by git svn will all @@ -1242,14 +1314,14 @@ svn-remote.<name>.noMetadata This option can only be used for one-shot imports as git svn will not be able to fetch again without metadata. Additionally, -if you lose your .git/svn/*/.rev_map. files, git svn will not +if you lose your $GIT_DIR/svn/**/.rev_map.* files, git svn will not be able to rebuild them. The git svn log command will not work on repositories using this, either. Using this conflicts with the useSvmProps option for (hopefully) obvious reasons. This option is NOT recommended as it makes it difficult to track down old references to SVN revision numbers in existing documentation, bug -reports and archives. If you plan to eventually migrate from SVN to git +reports and archives. If you plan to eventually migrate from SVN to Git and are certain about dropping SVN history, consider instead. filter-branch also allows reformatting of metadata for ease-of-reading and rewriting authorship @@ -1325,7 +1397,7 @@ svn-remote.<name>.pushurl - Similar to git's remote.<name>.pushurl, this key is designed + Similar to Git's remote.<name>.pushurl, this key is designed to be used in cases where url points to an SVN repository via a read-only transport, to provide an alternate read/write transport. It is assumed that both keys point to the same @@ -1398,29 +1470,29 @@ for rewriteRoot and rewriteUUID which can be used together. cd trunk # You should be on master branch, double-check with 'git branch' git branch -# Do some work and commit locally to git: +# Do some work and commit locally to Git: git commit ... # Something is committed to SVN, rebase your local changes against the # latest changes in SVN: git svn rebase -# Now commit your changes (that were committed previously using git) to SVN, +# Now commit your changes (that were committed previously using Git) to SVN, # as well as automatically updating your working HEAD: git svn dcommit -# Append svn:ignore settings to the default git exclude file: +# Append svn:ignore settings to the default Git exclude file: git svn show-ignore >> .git/info/exclude Tracking and contributing to an entire Subversion-managed project (complete with a trunk, tags and branches): # Clone a repo with standard SVN directory layout (like git clone): - git svn clone http://svn.example.com/project --stdlayout + git svn clone http://svn.example.com/project --stdlayout --prefix svn/ # Or, if the repo uses a non-standard directory layout: - git svn clone http://svn.example.com/project -T tr -b branch -t tag + git svn clone http://svn.example.com/project -T tr -b branch -t tag --prefix svn/ # View all branches and tags you have cloned: git branch -r # Create a new branch in SVN - git svn branch waldo + git svn branch waldo # Reset your master to trunk (or any other branch, replacing 'trunk' # with the appropriate name): - git reset --hard remotes/trunk + git reset --hard svn/trunk # You may only dcommit to one branch/tag/trunk at a time. The usage # of dcommit/rebase/show-ignore should be the same as above. The initial git svn clone can be quite time-consuming @@ -1430,7 +1502,7 @@ people (or one person with multiple machines) want to use do the initial git svn clone to a repository on a server and have each person clone that repository with git clone: # Do the initial import on a server - ssh server "cd /pub && git svn clone http://svn.example.com/project + ssh server "cd /pub && git svn clone http://svn.example.com/project [options...]" # Clone locally - make sure the refs/remotes/ space matches the server mkdir project cd project @@ -1438,13 +1510,14 @@ have each person clone that repository with git clone: @@ -1469,14 +1542,14 @@ commits unexpectedly reversing previous commits in SVN. copy history (including branches and tags) for repositories adopting a standard layout, it cannot yet represent merge history that happened inside git back upstream to SVN users. Therefore it is advised that -users keep history as linear as possible inside git to ease +users keep history as linear as possible inside Git to ease compatibility with SVN (see the CAVEATS section below). HANDLING OF SVN BRANCHES If git svn is configured to fetch branches (and --follow-branches -is in effect), it sometimes creates multiple git branches for one -SVN branch, where the addtional branches have names of the form +is in effect), it sometimes creates multiple Git branches for one +SVN branch, where the additional branches have names of the form branchname@nnn (with nnn an SVN revision number). These additional branches are created if git svn cannot find a parent commit for the first commit in an SVN branch, to connect the branch to the history of @@ -1484,17 +1557,17 @@ the other branches. Normally, the first commit in an SVN branch consists of a copy operation. git svn will read this commit to get the SVN revision the branch was created from. It will then try to find the -git commit that corresponds to this SVN revision, and use that as the +Git commit that corresponds to this SVN revision, and use that as the parent of the branch. However, it is possible that there is no suitable -git commit to serve as parent. This will happen, among other reasons, +Git commit to serve as parent. This will happen, among other reasons, if the SVN branch is a copy of a revision that was not fetched by git svn (e.g. because it is an old revision that was skipped with --revision), or if in SVN a directory was copied that is not tracked by git svn (such as a branch that is not tracked at all, or a subdirectory of a tracked branch). In these cases, git svn will still -create a git branch, but instead of using an existing git commit as the +create a Git branch, but instead of using an existing Git commit as the parent of the branch, it will read the SVN history of the directory the -branch was copied from and create appropriate git commits. This is +branch was copied from and create appropriate Git commits. This is indicated by the message "Initializing parent: <branchname>". Additionally, it will create a special branch named <branchname>@<SVN-Revision>, where <SVN-Revision> is the SVN revision @@ -1502,14 +1575,14 @@ number the branch was copied from. This branch will point to the newly created parent commit of the branch. If in SVN the branch was deleted and later recreated from a different version, there will be multiple such branches with an @. -Note that this may mean that multiple git commits are created for a +Note that this may mean that multiple Git commits are created for a single SVN revision. An example: in an SVN repository with a standard trunk/tags/branches layout, a directory trunk/sub is created in r.100. In r.200, trunk/sub is branched by copying it to branches/. git svn -clone -s will then create a branch sub. It will also create new git +clone -s will then create a branch sub. It will also create new Git commits for r.100 through r.199 and use these as the history of branch -sub. Thus there will be two git commits for each revision from r.100 +sub. Thus there will be two Git commits for each revision from r.100 to r.199 (one containing trunk/, one containing trunk/sub/). Finally, it will create a branch sub@200 pointing to the new parent commit of branch sub (i.e. the commit for r.200 and trunk/sub/). @@ -1519,12 +1592,12 @@ branch sub (i.e. the commit for r.200 and trunk/sub/).For the sake of simplicity and interoperating with Subversion, it is recommended that all git svn users clone, fetch and dcommit directly from the SVN server, and avoid all git clone/pull/merge/push -operations between git repositories and branches. The recommended -method of exchanging code between git branches and users is +operations between Git repositories and branches. The recommended +method of exchanging code between Git branches and users is git format-patch and git am, or just 'dcommit'ing to the SVN repository. Running git merge or git pull is NOT recommended on a branch you plan to dcommit from because Subversion users cannot see any -merges you've made. Furthermore, if you merge or pull from a git branch +merges you've made. Furthermore, if you merge or pull from a Git branch that is a mirror of an SVN branch, dcommit may commit to the wrong branch. If you do merge, note the following rule: git svn dcommit will @@ -1538,7 +1611,7 @@ the same SVN branch. any git svn metadata, or config. So repositories created and managed with using git svn should use rsync for cloning, if cloning is to be done at all. -Since dcommit uses rebase internally, any git branches you git push to +Since dcommit uses rebase internally, any Git branches you git push to before dcommit on will require forcing an overwrite of the existing ref on the remote repository. This is generally considered bad practice, see the documentation for details. @@ -1548,7 +1621,7 @@ you've already pushed to a remote repository for other users, and dcommit with SVN is analogous to that. When cloning an SVN repository, if none of the options for describing the repository layout is used (--trunk, --tags, --branches, ---stdlayout), git svn clone will create a git repository with +--stdlayout), git svn clone will create a Git repository with completely linear history, where branches and tags appear as separate directories in the working copy. While this is the easiest way to get a copy of a complete repository, for projects with many branches it will @@ -1563,9 +1636,9 @@ branches and tags is required, the options --trunk / When using multiple --branches or --tags, git svn does not automatically handle name collisions (for example, if two branches from different paths have the same name, or if a branch and a tag have the same name). In these cases, -use init to set up your git repository then, before your first fetch, edit -the .git/config file so that the branches and tags are associated with -different name spaces. For example: +use init to set up your Git repository then, before your first fetch, edit +the $GIT_DIR/config file so that the branches and tags are associated +with different name spaces. For example: branches = stable/*:refs/remotes/svn/stable/* branches = debug/*:refs/remotes/svn/debug/* @@ -1573,12 +1646,12 @@ branches = debug/*:refs/remotes/svn/debug/* BUGS We ignore all SVN properties except svn:executable. Any unhandled properties are logged to $GIT_DIR/svn/<refname>/unhandled.log -Renamed and copied directories are not detected by git and hence not +Renamed and copied directories are not detected by Git and hence not tracked when committing to SVN. I do not plan on adding support for this as it's quite difficult and time-consuming to get working for all -the possible corner cases (git doesn't do it, either). Committing +the possible corner cases (Git doesn't do it, either). Committing renamed and copied files is fully supported if they're similar enough -for git to detect them. +for Git to detect them. In SVN, it is possible (though discouraged) to commit changes to a tag (because a tag is just a directory copy, thus technically the same as a branch). When cloning an SVN repository, git svn cannot know if such a @@ -1588,7 +1661,7 @@ and imports all SVN tags as branches, prefixing the tag name with tags CONFIGURATION git svn stores [svn-remote] configuration information in the -repository .git/config file. It is similar the core git +repository $GIT_DIR/config file. It is similar the core Git [remote] sections except fetch keys do not accept glob arguments; but they are instead handled by the branches and tags keys. Since some SVN repositories are oddly @@ -1598,6 +1671,8 @@ listed below are allowed: url = http://server.org/svn fetch = trunk/project-a:refs/remotes/project-a/trunk branches = branches/*/project-a:refs/remotes/project-a/branches/* + branches = branches/release_*:refs/remotes/project-a/branches/release_* + branches = branches/re*se:refs/remotes/project-a/branches/* tags = tags/*/project-a:refs/remotes/project-a/tags/* Keep in mind that the * (asterisk) wildcard of the local ref (right of the :) must be the farthest right path component; @@ -1605,17 +1680,55 @@ however the remote wildcard may be anywhere as long as it's an independent path component (surrounded by / or EOL). This type of configuration is not automatically created by init and should be manually entered with a text-editor or using git config. +Also note that only one asterisk is allowed per word. For example: +branches = branches/re*se:refs/remotes/project-a/branches/* +will match branches release, rese, re123se, however +branches = branches/re*s*e:refs/remotes/project-a/branches/* +will produce an error. It is also possible to fetch a subset of branches or tags by using a comma-separated list of names within braces. For example: [svn-remote "huge-project"] url = http://server.org/svn fetch = trunk/src:refs/remotes/trunk - branches = branches/{red,green}/src:refs/remotes/branches/* - tags = tags/{1.0,2.0}/src:refs/remotes/tags/* + branches = branches/{red,green}/src:refs/remotes/project-a/branches/* + tags = tags/{1.0,2.0}/src:refs/remotes/project-a/tags/* +Multiple fetch, branches, and tags keys are supported: +[svn-remote "messy-repo"] + url = http://server.org/svn + fetch = trunk/project-a:refs/remotes/project-a/trunk + fetch = branches/demos/june-project-a-demo:refs/remotes/project-a/demos/june-demo + branches = branches/server/*:refs/remotes/project-a/branches/* + branches = branches/demos/2011/*:refs/remotes/project-a/2011-demos/* + tags = tags/server/*:refs/remotes/project-a/tags/* +Creating a branch in such a configuration requires disambiguating which +location to use using the -d or --destination flag: +$ git svn branch -d branches/server release-2-3-0 Note that git-svn keeps track of the highest revision in which a branch or tag has appeared. If the subset of branches or tags is changed after -fetching, then .git/svn/.metadata must be manually edited to remove (or -reset) branches-maxRev and/or tags-maxRev as appropriate. +fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove +(or reset) branches-maxRev and/or tags-maxRev as appropriate. + + +FILES + + + +$GIT_DIR/svn/**/.rev_map.* + + + + Mapping between Subversion revision numbers and Git commit + names. In a repository where the noMetadata option is not set, + this can be rebuilt from the git-svn-id: lines that are at the + end of every commit (see the svn.noMetadata section above for + details). + +git svn fetch and git svn rebase automatically update the rev_map +if it is missing or not up to date. git svn reset automatically +rewinds it. + + + SEE ALSO diff --git a/doc/source/en/TortoiseGit/git_doc/git-tag.xml b/doc/source/en/TortoiseGit/git_doc/git-tag.xml index c1deeae8f..6f0bec012 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-tag.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-tag.xml @@ -13,12 +13,12 @@ SYNOPSIS
-git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] +git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>] git tag -d <tagname>… git tag [-n[<num>]] -l [--contains <commit>] [--points-at <object>] - [--column[=<options>] | --no-column] [<pattern>…] - [<pattern>…] + [--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>] + [--format=<format>] [--[no-]merged [<commit>]] [<pattern>…] git tag -v <tagname>…
@@ -27,19 +27,28 @@ Add a tag reference in refs/tags/, unless -d/-l/-v is given to delete, list or verify tags. Unless -f is given, the named tag must not yet exist. -If one of -a, -s, or -u <key-id> is passed, the command +If one of -a, -s, or -u <keyid> is passed, the command creates a tag object, and requires a tag message. Unless -m <msg> or -F <file> is given, an editor is started for the user to type in the tag message. -If -m <msg> or -F <file> is given and -a, -s, and -u <key-id> +If -m <msg> or -F <file> is given and -a, -s, and -u <keyid> are absent, -a is implied. -Otherwise just a tag reference for the SHA1 object name of the commit object is +Otherwise just a tag reference for the SHA-1 object name of the commit object is created (i.e. a lightweight tag). A GnuPG signed tag object will be created when -s or -u -<key-id> is used. When -u <key-id> is not used, the +<keyid> is used. When -u <keyid> is not used, the committer identity for the current user is used to find the GnuPG key for signing. The configuration variable gpg.program is used to specify custom GnuPG binary. +Tag objects (created with -a, -s, or -u) are called "annotated" +tags; they contain a creation date, the tagger name and e-mail, a +tagging message, and an optional GnuPG signature. Whereas a +"lightweight" tag is simply a name for an object (usually a commit +object). +Annotated tags are meant for release while lightweight tags are meant +for private or temporary object labels. For this reason, some git +commands for naming objects (like git describe) will ignore +lightweight tags by default. OPTIONS @@ -72,10 +81,10 @@ is used to specify custom GnuPG binary. --u <key-id> +-u <keyid> ---local-user=<key-id> +--local-user=<keyid> @@ -155,6 +164,26 @@ is used to specify custom GnuPG binary. +--sort=<key> + + + + Sort based on the key given. Prefix - to sort in + descending order of the value. You may use the --sort=<key> option + multiple times, in which case the last key becomes the primary + key. Also supports "version:refname" or "v:refname" (tag + names are treated as versions). The "version:refname" sort + order can also be affected by the + "versionsort.prereleaseSuffix" configuration variable. + The keys supported are the same as those in git for-each-ref. + Sort order defaults to the value configured for the tag.sort + variable if it exists, or lexicographic order otherwise. See + . + + + + + --column[=<options>] @@ -171,11 +200,12 @@ is used to specify custom GnuPG binary. ---contains <commit> +--contains [<commit>] - Only list tags which contain the specified commit. + Only list tags which contain the specified commit (HEAD if not + specified). @@ -201,7 +231,7 @@ is used to specify custom GnuPG binary. Use the given tag message (instead of prompting). If multiple -m options are given, their values are concatenated as separate paragraphs. - Implies -a if none of -a, -s, or -u <key-id> + Implies -a if none of -a, -s, or -u <keyid> is given. @@ -217,7 +247,7 @@ is used to specify custom GnuPG binary. Take the tag message from the given file. Use - to read the message from the standard input. - Implies -a if none of -a, -s, or -u <key-id> + Implies -a if none of -a, -s, or -u <keyid> is given. @@ -238,6 +268,16 @@ is used to specify custom GnuPG binary. +--create-reflog + + + + Create a reflog for the tag. + + + + + <tagname> @@ -249,16 +289,55 @@ is used to specify custom GnuPG binary. + + +<commit> + + +<object> + + + + The object that the new tag will refer to, usually a commit. + Defaults to HEAD. + + + + + +<format> + + + + A string that interpolates %(fieldname) from the object + pointed at by a ref being shown. The format is the same as + that of . When unspecified, + defaults to %(refname:strip=2). + + + + + +--[no-]merged [<commit>] + + + + Only list tags whose tips are reachable, or not reachable + if --no-merged is used, from the specified commit (HEAD + if not specified). + + + CONFIGURATION By default, git tag in sign-with-default mode (-s) will use your -committer identity (of the form "Your Name <your@email.address>") to +committer identity (of the form Your Name <your@email.address>) to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows: [user] - signingkey = <gpg-key-id> + signingKey = <gpg-keyid> DISCUSSION @@ -348,7 +427,7 @@ to get the following updates... $ git pull git://git..../proj.git master In such a case, you do not want to automatically follow the other person's tags. -One important aspect of git is its distributed nature, which +One important aspect of Git is its distributed nature, which largely means there is no inherent "upstream" or "downstream" in the system. On the face of it, the above example might seem to indicate that the tag namespace is owned @@ -397,9 +476,9 @@ Git internal format - It is <unix timestamp> <timezone offset>, where <unix + It is <unix timestamp> <time zone offset>, where <unix timestamp> is the number of seconds since the UNIX epoch. - <timezone offset> is a positive or negative offset from UTC. + <time zone offset> is a positive or negative offset from UTC. For example CET (which is 2 hours ahead UTC) is +0200. @@ -433,7 +512,8 @@ ISO 8601 SEE ALSO -. +. +. GIT diff --git a/doc/source/en/TortoiseGit/git_doc/git-tar-tree.xml b/doc/source/en/TortoiseGit/git_doc/git-tar-tree.xml deleted file mode 100644 index 96269ac78..000000000 --- a/doc/source/en/TortoiseGit/git_doc/git-tar-tree.xml +++ /dev/null @@ -1,152 +0,0 @@ - - - - - git-tar-tree(1) - -git-tar-tree(1) - - -NAME -git-tar-tree - Create a tar archive of the files in the named tree object - - -SYNOPSIS -
-git tar-tree [--remote=<repo>] <tree-ish> [ <base> ] -
- - -DESCRIPTION -THIS COMMAND IS DEPRECATED. Use git archive with --format=tar -option instead (and move the <base> argument to --prefix=base/). -Creates a tar archive containing the tree structure for the named tree. -When <base> is specified it is added as a leading path to the files in the -generated tar archive. -git tar-tree behaves differently when given a tree ID versus when given -a commit ID or tag ID. In the first case the current time is used as -modification time of each file in the archive. In the latter case the -commit time as recorded in the referenced commit object is used instead. -Additionally the commit ID is stored in a global extended pax header. -It can be extracted using git get-tar-commit-id. - - -OPTIONS - - - -<tree-ish> - - - - The tree or commit to produce tar archive for. If it is - the object name of a commit object. - - - - - -<base> - - - - Leading path to the files in the resulting tar archive. - - - - - ---remote=<repo> - - - - Instead of making a tar archive from local repository, - retrieve a tar archive from a remote repository. - - - - - - -CONFIGURATION - - - -tar.umask - - - - This variable can be used to restrict the permission bits of - tar archive entries. The default is 0002, which turns off the - world write bit. The special value "user" indicates that the - archiving user's umask will be used instead. See umask(2) for - details. - - - - - - -EXAMPLES - - - -git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -) - - - - Create a tar archive that contains the contents of the - latest commit on the current branch, and extracts it in - /var/tmp/junk directory. - - - - - -git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz - - - - Create a tarball for v1.4.0 release. - - - - - -git tar-tree v1.4.0^{tree} git-1.4.0 | gzip >git-1.4.0.tar.gz - - - - Create a tarball for v1.4.0 release, but without a - global extended pax header. - - - - - -git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar - - - - Get a tarball v1.4.0 from example.com. - - - - - -git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar - - - - Put everything in the current head's Documentation/ directory - into git-1.4.0-docs.tar, with the prefix git-docs/. - - - - - - -GIT -Part of the suite - - diff --git a/doc/source/en/TortoiseGit/git_doc/git-unpack-objects.xml b/doc/source/en/TortoiseGit/git_doc/git-unpack-objects.xml index 742a7a81f..9ae741b5a 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-unpack-objects.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-unpack-objects.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git unpack-objects [-n] [-q] [-r] [--strict] <pack-file +git unpack-objects [-n] [-q] [-r] [--strict]
@@ -22,8 +22,8 @@ the objects contained within and writing them into the repository in "loose" (one object per file) format. Objects that already exist in the repository will not be unpacked -from the pack-file. Therefore, nothing will be unpacked if you use -this command on a pack-file that exists within the target repository. +from the packfile. Therefore, nothing will be unpacked if you use +this command on a packfile that exists within the target repository. See for options to generate new packs and replace existing ones. diff --git a/doc/source/en/TortoiseGit/git_doc/git-update-index.xml b/doc/source/en/TortoiseGit/git_doc/git-update-index.xml index db27faf9e..13d6ad2a8 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-update-index.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-update-index.xml @@ -16,11 +16,13 @@ git update-index [--add] [--remove | --force-remove] [--replace] [--refresh] [-q] [--unmerged] [--ignore-missing] - [(--cacheinfo <mode> <object> <file>)…] + [(--cacheinfo <mode>,<object>,<file>)…] [--chmod=(+|-)x] - [--assume-unchanged | --no-assume-unchanged] - [--skip-worktree | --no-skip-worktree] + [--[no-]assume-unchanged] + [--[no-]skip-worktree] [--ignore-submodules] + [--[no-]split-index] + [--[no-|test-|force-]untracked-cache] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] [-z] [--stdin] [--index-version <n>] @@ -123,11 +125,17 @@ using the various options: +--cacheinfo <mode>,<object>,<path> + + --cacheinfo <mode> <object> <path> - Directly insert the specified info into the index. + Directly insert the specified info into the index. For + backward compatibility, you can also give these three + arguments as three separate parameters, but new users are + encouraged to use a single-parameter form. @@ -153,28 +161,23 @@ using the various options: ---assume-unchanged - - ---no-assume-unchanged +--[no-]assume-unchanged - When these flags are specified, the object names recorded - for the paths are not updated. Instead, these options - set and unset the "assume unchanged" bit for the - paths. When the "assume unchanged" bit is on, git stops - checking the working tree files for possible - modifications, so you need to manually unset the bit to - tell git when you change the working tree file. This is + When this flag is specified, the object names recorded + for the paths are not updated. Instead, this option + sets/unsets the "assume unchanged" bit for the + paths. When the "assume unchanged" bit is on, the user + promises not to change the file and allows Git to assume + that the working tree file matches what is recorded in + the index. If you want to change the working tree file, + you need to unset the bit to tell Git. This is sometimes helpful when working with a big project on a filesystem that has very slow lstat(2) system call (e.g. cifs). -This option can be also used as a coarse file-level mechanism -to ignore uncommitted changes in tracked files (akin to what -.gitignore does for untracked files). -Git will fail (gracefully) in case it needs to modify this file +Git will fail (gracefully) in case it needs to modify this file in the index e.g. when merging in a commit; thus, in case the assumed-untracked file is changed upstream, you will need to handle the situation manually. @@ -193,10 +196,7 @@ you will need to handle the situation manually. ---skip-worktree - - ---no-skip-worktree +--[no-]skip-worktree @@ -299,8 +299,15 @@ you will need to handle the situation manually. Write the resulting index out in the named on-disk format version. - The current default version is 2. + Supported versions are 2, 3 and 4. The current default version is 2 + or 3, depending on whether extra features are used, such as + git add -N. +Version 4 performs a simple pathname compression that reduces index +size by 30%-50% on large repositories, which results in faster load +time. Version 4 is relatively young (first released in in 1.8.0 in +October 2012). Other Git implementations such as JGit and libgit2 +may not support it yet. @@ -316,6 +323,75 @@ you will need to handle the situation manually. +--split-index + + +--no-split-index + + + + Enable or disable split index mode. If enabled, the index is + split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex.<SHA-1>. + Changes are accumulated in $GIT_DIR/index while the shared + index file contains all index entries stays unchanged. If + split-index mode is already enabled and --split-index is + given again, all changes in $GIT_DIR/index are pushed back to + the shared index file. This mode is designed for very large + indexes that take a significant amount of time to read or write. + + + + + +--untracked-cache + + +--no-untracked-cache + + + + Enable or disable untracked cache feature. Please use + --test-untracked-cache before enabling it. + +These options take effect whatever the value of the core.untrackedCache +configuration variable (see ). But a warning is +emitted when the change goes against the configured value, as the +configured value will take effect next time the index is read and this +will remove the intended effect of the option. + + + + +--test-untracked-cache + + + + Only perform tests on the working directory to make sure + untracked cache can be used. You have to manually enable + untracked cache using --untracked-cache or + --force-untracked-cache or the core.untrackedCache + configuration variable afterwards if you really want to use + it. If a test fails the exit code is 1 and a message + explains what is not working as needed, otherwise the exit + code is 0 and OK is printed. + + + + + +--force-untracked-cache + + + + Same as --untracked-cache. Provided for backwards + compatibility with older versions of Git where + --untracked-cache used to imply --test-untracked-cache but + this option would enable the extension unconditionally. + + + + + -- @@ -356,7 +432,7 @@ up the stat index details with the proper files. current working directory. This is useful for minimum-checkout merging. To pretend you have a file with mode and sha1 at path, say: -$ git update-index --cacheinfo mode sha1 path +$ git update-index --cacheinfo <mode>,<sha1>,<path> --info-only is used to register files without placing them in the object database. This is useful for status-only repositories. Both --cacheinfo and --info-only behave similarly: the index is updated @@ -407,7 +483,7 @@ then feeding necessary input lines in the third format. 100644 8a1218a1024a212bb3db30becd860315f9f3ac52 1 frotz 100755 8a1218a1024a212bb3db30becd860315f9f3ac52 2 frotz The first line of the input feeds 0 as the mode to remove the -path; the SHA1 does not matter as long as it is well formatted. +path; the SHA-1 does not matter as long as it is well formatted. Then the second and third line feeds stage 1 and stage 2 entries for that path. After the above, we would end up with this: $ git ls-files -s @@ -416,18 +492,18 @@ for that path. After the above, we would end up with this: Using assume unchanged bit -Many operations in git depend on your filesystem to have an +Many operations in Git depend on your filesystem to have an efficient lstat(2) implementation, so that st_mtime information for working tree files can be cheaply checked to see if the file contents have changed from the version recorded in the index file. Unfortunately, some filesystems have inefficient lstat(2). If your filesystem is one of them, you can set "assume unchanged" bit to paths you have not changed to -cause git not to do this check. Note that setting this bit on a -path does not mean git will check the contents of the file to -see if it has changed -- it makes git to omit any checking and +cause Git not to do this check. Note that setting this bit on a +path does not mean Git will check the contents of the file to +see if it has changed -- it makes Git to omit any checking and assume it has not changed. When you make changes to working -tree files, you have to explicitly tell git about it by dropping +tree files, you have to explicitly tell Git about it by dropping "assume unchanged" bit, either before or after you modify them. In order to set "assume unchanged" bit, use --assume-unchanged option. To unset, use --no-assume-unchanged. To see which files @@ -435,7 +511,7 @@ have the "assume unchanged" bit set, use git ls-files -v (see ). The command looks at core.ignorestat configuration variable. When this is true, paths updated with git update-index paths... and -paths updated with other git commands that update both index and +paths updated with other Git commands that update both index and working tree (e.g. git apply --index, git checkout-index -u, and git read-tree -u) are automatically marked as "assume unchanged". Note that "assume unchanged" bit is not set if @@ -534,6 +610,33 @@ working directory version matches index version) different from assume-unchanged bit's. Skip-worktree also takes precedence over assume-unchanged bit when both are set. + +Untracked cache +This cache is meant to speed up commands that involve determining +untracked files such as git status. +This feature works by recording the mtime of the working tree +directories and then omitting reading directories and stat calls +against files in those directories whose mtime hasn't changed. For +this to work the underlying operating system and file system must +change the st_mtime field of directories if files in the directory +are added, modified or deleted. +You can test whether the filesystem supports that with the +--test-untracked-cache option. The --untracked-cache option used +to implicitly perform that test in older versions of Git, but that's +no longer the case. +If you want to enable (or disable) this feature, it is easier to use +the core.untrackedCache configuration variable (see +) than using the --untracked-cache option to +git update-index in each repository, especially if you want to do so +across all repositories you use, because you can set the configuration +variable to true (or false) in your $HOME/.gitconfig just once +and have it affect all repositories you touch. +When the core.untrackedCache configuration variable is changed, the +untracked cache is added to or removed from the index the next time a +command reads the index; while when --[no-|force-]untracked-cache +are used, the untracked cache is immediately added to or removed from +the index. + Configuration The command honors core.filemode configuration variable. If @@ -553,6 +656,9 @@ from symbolic link to regular file. It can be useful when the inode change time is regularly modified by something outside Git (file system crawlers and backup systems use ctime for marking files processed) (see ). +The untracked cache extension can be enabled by the +core.untrackedCache configuration variable (see +). SEE ALSO diff --git a/doc/source/en/TortoiseGit/git_doc/git-update-ref.xml b/doc/source/en/TortoiseGit/git_doc/git-update-ref.xml index 174d37a7a..9240eb3e5 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-update-ref.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-update-ref.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git update-ref [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>]) +git update-ref [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z])
@@ -53,6 +53,96 @@ ref symlink to some other tree, if you have copied a whole archive by creating a symlink tree). With -d flag, it deletes the named <ref> after verifying it still contains <oldvalue>. +With --stdin, update-ref reads instructions from standard input and +performs all modifications together. Specify commands of the form: +update SP <ref> SP <newvalue> [SP <oldvalue>] LF +create SP <ref> SP <newvalue> LF +delete SP <ref> [SP <oldvalue>] LF +verify SP <ref> [SP <oldvalue>] LF +option SP <opt> LF +With --create-reflog, update-ref will create a reflog for each ref +even if one would not ordinarily be created. +Quote fields containing whitespace as if they were strings in C source +code; i.e., surrounded by double-quotes and with backslash escapes. +Use 40 "0" characters or the empty string to specify a zero value. To +specify a missing value, omit the value and its preceding SP entirely. +Alternatively, use -z to specify in NUL-terminated format, without +quoting: +update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL +create SP <ref> NUL <newvalue> NUL +delete SP <ref> NUL [<oldvalue>] NUL +verify SP <ref> NUL [<oldvalue>] NUL +option SP <opt> NUL +In this format, use 40 "0" to specify a zero value, and use the empty +string to specify a missing value. +In either format, values can be specified in any form that Git +recognizes as an object name. Commands in any other format or a +repeated <ref> produce an error. Command meanings are: + + + +update + + + + Set <ref> to <newvalue> after verifying <oldvalue>, if given. + Specify a zero <newvalue> to ensure the ref does not exist + after the update and/or a zero <oldvalue> to make sure the + ref does not exist before the update. + + + + + +create + + + + Create <ref> with <newvalue> after verifying it does not + exist. The given <newvalue> may not be zero. + + + + + +delete + + + + Delete <ref> after verifying it exists with <oldvalue>, if + given. If given, <oldvalue> may not be zero. + + + + + +verify + + + + Verify <ref> against <oldvalue> but do not change it. If + <oldvalue> zero or missing, the ref must not exist. + + + + + +option + + + + Modify behavior of the next command naming a <ref>. + The only valid option is no-deref to avoid dereferencing + a symbolic ref. + + + + +If all <ref>s can be locked with matching <oldvalue>s +simultaneously, all modifications are performed. Otherwise, no +modifications are performed. Note that while each individual +<ref> is updated or deleted atomically, a concurrent reader may +still see a subset of the modifications. Logging Updates @@ -70,7 +160,7 @@ oldsha1 SP newsha1 SP committer LF Where "oldsha1" is the 40 character hexadecimal value previously stored in <ref>, "newsha1" is the 40 character hexadecimal value of <newvalue> and "committer" is the committer's name, email address -and date in the standard GIT committer ident format. +and date in the standard Git committer ident format. Optionally with -m: diff --git a/doc/source/en/TortoiseGit/git_doc/git-upload-archive.xml b/doc/source/en/TortoiseGit/git_doc/git-upload-archive.xml index ffa09cac1..456209efb 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-upload-archive.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-upload-archive.xml @@ -19,11 +19,51 @@ DESCRIPTION Invoked by git archive --remote and sends a generated archive to the -other end over the git protocol. +other end over the Git protocol. This command is usually not invoked directly by the end user. The UI for the protocol is on the git archive side, and the program pair is meant to be used to get an archive from a remote repository. + +SECURITY +In order to protect the privacy of objects that have been removed from +history but may not yet have been pruned, git-upload-archive avoids +serving archives for commits and trees that are not reachable from the +repository's refs. However, because calculating object reachability is +computationally expensive, git-upload-archive implements a stricter +but easier-to-check set of rules: + + + +Clients may request a commit or tree that is pointed to directly by + a ref. E.g., git archive --remote=origin v1.0. + + + + +Clients may request a sub-tree within a commit or tree using the + ref:path syntax. E.g., git archive --remote=origin v1.0:Documentation. + + + + +Clients may not use other sha1 expressions, even if the end + result is reachable. E.g., neither a relative commit like master^ + nor a literal sha1 like abcd1234 is allowed, even if the result + is reachable from the refs. + + + +Note that rule 3 disallows many cases that do not have any privacy +implications. These rules are subject to change in future versions of +git, and the server accessed by git archive --remote may or may not +follow these exact rules. +If the config option uploadArchive.allowUnreachable is true, these +rules are ignored, and clients may use arbitrary sha1 expressions. +This is useful if you do not care about the privacy of unreachable +objects, or if your object database is already publicly available for +access via non-smart-http. + OPTIONS diff --git a/doc/source/en/TortoiseGit/git_doc/git-upload-pack.xml b/doc/source/en/TortoiseGit/git_doc/git-upload-pack.xml index b5cc7925c..aea36abdc 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-upload-pack.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-upload-pack.xml @@ -34,7 +34,7 @@ repository. For push operations, see git send-pack. - Do not try <directory>/.git/ if <directory> is no git directory. + Do not try <directory>/.git/ if <directory> is no Git directory. diff --git a/doc/source/en/TortoiseGit/git_doc/git-var.xml b/doc/source/en/TortoiseGit/git_doc/git-var.xml index db38dcc5e..71837e2a3 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-var.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-var.xml @@ -8,7 +8,7 @@ NAME -git-var - Show a git logical variable +git-var - Show a Git logical variable SYNOPSIS @@ -18,7 +18,7 @@ DESCRIPTION -Prints a git logical variable. +Prints a Git logical variable. OPTIONS @@ -30,7 +30,7 @@ Cause the logical variables to be listed. In addition, all the - variables of the git configuration file .git/config are listed + variables of the Git configuration file .git/config are listed as well. (However, the configuration variables listing functionality is deprecated in favor of git config -l.) @@ -62,7 +62,7 @@ GIT_COMMITTER_IDENT - The person who put a piece of code into git. + The person who put a piece of code into Git. @@ -72,7 +72,7 @@ GIT_EDITOR - Text editor for use by git commands. The value is meant to be + Text editor for use by Git commands. The value is meant to be interpreted by the shell when it is used. Examples: ~/bin/vi, $SOME_ENVIRONMENT_VARIABLE, "C:\Program Files\Vim\gvim.exe" --nofork. The order of preference is the $GIT_EDITOR @@ -88,7 +88,7 @@ GIT_PAGER - Text viewer for use by git commands (e.g., less). The value + Text viewer for use by Git commands (e.g., less). The value is meant to be interpreted by the shell. The order of preference is the $GIT_PAGER environment variable, then core.pager configuration, then $PAGER, and then the default chosen at diff --git a/doc/source/en/TortoiseGit/git_doc/git-verify-commit.xml b/doc/source/en/TortoiseGit/git_doc/git-verify-commit.xml new file mode 100644 index 000000000..79368949b --- /dev/null +++ b/doc/source/en/TortoiseGit/git_doc/git-verify-commit.xml @@ -0,0 +1,66 @@ + + + + + git-verify-commit(1) + +git-verify-commit(1) + + +NAME +git-verify-commit - Check the GPG signature of commits + + +SYNOPSIS +
+git verify-commit <commit>… +
+ + +DESCRIPTION +Validates the gpg signature created by git commit -S. + + +OPTIONS + + + +--raw + + + + Print the raw gpg status output to standard error instead of the normal + human-readable output. + + + + + +-v + + +--verbose + + + + Print the contents of the commit object before validating it. + + + + + +<commit>… + + + + SHA-1 identifiers of Git commit objects. + + + + + + +GIT +Part of the suite + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-verify-pack.xml b/doc/source/en/TortoiseGit/git_doc/git-verify-pack.xml index 947a10a21..6eb024d2d 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-verify-pack.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-verify-pack.xml @@ -8,7 +8,7 @@ NAME -git-verify-pack - Validate packed git archive files +git-verify-pack - Validate packed Git archive files SYNOPSIS @@ -18,7 +18,7 @@ DESCRIPTION -Reads given idx file for packed git archive created with the +Reads given idx file for packed Git archive created with the git pack-objects command and verifies idx file and the corresponding pack file. @@ -78,9 +78,9 @@ corresponding pack file. OUTPUT FORMAT When specifying the -v option the format used is: -SHA1 type size size-in-pack-file offset-in-packfile +SHA-1 type size size-in-packfile offset-in-packfile for objects that are not deltified in the pack, and -SHA1 type size size-in-packfile offset-in-packfile depth base-SHA1 +SHA-1 type size size-in-packfile offset-in-packfile depth base-SHA-1 for objects that are deltified. diff --git a/doc/source/en/TortoiseGit/git_doc/git-verify-tag.xml b/doc/source/en/TortoiseGit/git_doc/git-verify-tag.xml index 866f51c66..c01b2e70f 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-verify-tag.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-verify-tag.xml @@ -25,6 +25,17 @@ +--raw + + + + Print the raw gpg status output to standard error instead of the normal + human-readable output. + + + + + -v @@ -42,7 +53,7 @@ - SHA1 identifiers of git tag objects. + SHA-1 identifiers of Git tag objects. diff --git a/doc/source/en/TortoiseGit/git_doc/git-web--browse.xml b/doc/source/en/TortoiseGit/git_doc/git-web--browse.xml index 42c150de7..b7b9c19cf 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-web--browse.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-web--browse.xml @@ -8,7 +8,7 @@ NAME -git-web--browse - git helper script to launch a web browser +git-web--browse - Git helper script to launch a web browser SYNOPSIS @@ -98,6 +98,16 @@ open (this is the default under Mac OS X GUI) start (this is the default under MinGW) + + +cygstart (this is the default under Cygwin) + + + + +xdg-open + + Custom commands may also be specified. @@ -140,7 +150,7 @@ start (this is the default under MinGW) - CONF.VAR is looked up in the git config files. If it's set, + CONF.VAR is looked up in the Git config files. If it's set, then its value specifies the browser that should be used. @@ -152,7 +162,7 @@ start (this is the default under MinGW)
CONF.VAR (from -c option) and web.browser The web browser can be specified using a configuration variable passed -with the -c (or --config) command line option, or the web.browser +with the -c (or --config) command-line option, or the web.browser configuration variable if the former is not used.
@@ -175,7 +185,7 @@ the URLs passed as arguments. Note about konqueror -When konqueror is specified by a command line option or a +When konqueror is specified by a command-line option or a configuration variable, we launch kfmclient to try to open the HTML man page on an already opened konqueror in a new tab if possible. For consistency, we also try such a trick if browser.konqueror.path is diff --git a/doc/source/en/TortoiseGit/git_doc/git-whatchanged.xml b/doc/source/en/TortoiseGit/git_doc/git-whatchanged.xml dissimilarity index 91% index 33f028dce..1784dc8c2 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-whatchanged.xml +++ b/doc/source/en/TortoiseGit/git_doc/git-whatchanged.xml @@ -1,658 +1,61 @@ - - - - - git-whatchanged(1) - -git-whatchanged(1) - - -NAME -git-whatchanged - Show logs with difference each commit introduces - - -SYNOPSIS -
-git whatchanged <option>… -
- - -DESCRIPTION -Shows commit logs and diff output each commit introduces. The -command internally invokes git rev-list piped to -git diff-tree, and takes command line options for both of -these commands. -This manual page describes only the most frequently used options. - - -OPTIONS - - - --p - - - - Show textual diffs, instead of the git internal diff - output format that is useful only to tell the changed - paths and their nature of changes. - - - - - --<n> - - - - Limit output to <n> commits. - - - - - -<since>..<until> - - - - Limit output to between the two named commits (bottom - exclusive, top inclusive). - - - - - --r - - - - Show git internal diff output, but for the whole tree, - not just the top level. - - - - - --m - - - - By default, differences for merge commits are not shown. - With this flag, show differences to that commit from all - of its parents. - -However, it is not very useful in general, although it -is useful on a file-by-file basis. - - - - ---pretty[=<format>] - - ---format=<format> - - - - Pretty-print the contents of the commit logs in a given format, - where <format> can be one of oneline, short, medium, - full, fuller, email, raw and format:<string>. See - the "PRETTY FORMATS" section for some additional details for each - format. When omitted, the format defaults to medium. - -Note: you can specify the default pretty format in the repository -configuration (see ). - - - - ---abbrev-commit - - - - Instead of showing the full 40-byte hexadecimal commit object - name, show only a partial prefix. Non default number of - digits can be specified with "--abbrev=<n>" (which also modifies - diff output, if it is displayed). - -This should make "--pretty=oneline" a whole lot more readable for -people using 80-column terminals. - - - - ---no-abbrev-commit - - - - Show the full 40-byte hexadecimal commit object name. This negates - --abbrev-commit and those options which imply it such as - "--oneline". It also overrides the log.abbrevCommit variable. - - - - - ---oneline - - - - This is a shorthand for "--pretty=oneline --abbrev-commit" - used together. - - - - - ---encoding[=<encoding>] - - - - The commit objects record the encoding used for the log message - in their encoding header; this option can be used to tell the - command to re-code the commit log message in the encoding - preferred by the user. For non plumbing commands this - defaults to UTF-8. - - - - - ---notes[=<ref>] - - - - Show the notes (see ) that annotate the - commit, when showing the commit log message. This is the default - for git log, git show and git whatchanged commands when - there is no --pretty, --format nor --oneline option given - on the command line. - -By default, the notes shown are from the notes refs listed in the -core.notesRef and notes.displayRef variables (or corresponding -environment overrides). See for more details. -With an optional <ref> argument, show this notes ref instead of the -default notes ref(s). The ref is taken to be in refs/notes/ if it -is not qualified. -Multiple --notes options can be combined to control which notes are -being displayed. Examples: "--notes=foo" will show only notes from -"refs/notes/foo"; "--notes=foo --notes" will show both notes from -"refs/notes/foo" and from the default notes ref(s). - - - - ---no-notes - - - - Do not show notes. This negates the above --notes option, by - resetting the list of notes refs from which notes are shown. - Options are parsed in the order given on the command line, so e.g. - "--notes --notes=foo --no-notes --notes=bar" will only show notes - from "refs/notes/bar". - - - - - ---show-notes[=<ref>] - - ---[no-]standard-notes - - - - These options are deprecated. Use the above --notes/--no-notes - options instead. - - - - - ---show-signature - - - - Check the validity of a signed commit object by passing the signature - to gpg --verify and show the output. - - - - - - -PRETTY FORMATS -If the commit is a merge, and if the pretty-format -is not oneline, email or raw, an additional line is -inserted before the Author: line. This line begins with -"Merge: " and the sha1s of ancestral commits are printed, -separated by spaces. Note that the listed commits may not -necessarily be the list of the direct parent commits if you -have limited your view of history: for example, if you are -only interested in changes related to a certain directory or -file. -There are several built-in formats, and you can define -additional formats by setting a pretty.<name> -config option to either another format name, or a -format: string, as described below (see -). Here are the details of the -built-in formats: - - - -oneline - -<sha1> <title line> -This is designed to be as compact as possible. - - - -short - -commit <sha1> -Author: <author> -<title line> - - - -medium - -commit <sha1> -Author: <author> -Date: <author date> -<title line> -<full commit message> - - - -full - -commit <sha1> -Author: <author> -Commit: <committer> -<title line> -<full commit message> - - - -fuller - -commit <sha1> -Author: <author> -AuthorDate: <author date> -Commit: <committer> -CommitDate: <committer date> -<title line> -<full commit message> - - - -email - -From <sha1> <date> -From: <author> -Date: <author date> -Subject: [PATCH] <title line> -<full commit message> - - - -raw - -The raw format shows the entire commit exactly as -stored in the commit object. Notably, the SHA1s are -displayed in full, regardless of whether --abbrev or ---no-abbrev are used, and parents information show the -true parent commits, without taking grafts nor history -simplification into account. - - - -format:<string> - -The format:<string> format allows you to specify which information -you want to show. It works a little bit like printf format, -with the notable exception that you get a newline with %n -instead of \n. -E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n" -would show something like this: -The author of fe6e0ee was Junio C Hamano, 23 hours ago -The title was >>t4119: test autocomputing -p<n> for traditional diff input.<< -The placeholders are: - - - -%H: commit hash - - - - -%h: abbreviated commit hash - - - - -%T: tree hash - - - - -%t: abbreviated tree hash - - - - -%P: parent hashes - - - - -%p: abbreviated parent hashes - - - - -%an: author name - - - - -%aN: author name (respecting .mailmap, see or ) - - - - -%ae: author email - - - - -%aE: author email (respecting .mailmap, see or ) - - - - -%ad: author date (format respects --date= option) - - - - -%aD: author date, RFC2822 style - - - - -%ar: author date, relative - - - - -%at: author date, UNIX timestamp - - - - -%ai: author date, ISO 8601 format - - - - -%cn: committer name - - - - -%cN: committer name (respecting .mailmap, see or ) - - - - -%ce: committer email - - - - -%cE: committer email (respecting .mailmap, see or ) - - - - -%cd: committer date - - - - -%cD: committer date, RFC2822 style - - - - -%cr: committer date, relative - - - - -%ct: committer date, UNIX timestamp - - - - -%ci: committer date, ISO 8601 format - - - - -%d: ref names, like the --decorate option of - - - - -%e: encoding - - - - -%s: subject - - - - -%f: sanitized subject line, suitable for a filename - - - - -%b: body - - - - -%B: raw body (unwrapped subject and body) - - - - -%N: commit notes - - - - -%GG: raw verification message from GPG for a signed commit - - - - -%G?: show either "G" for Good or "B" for Bad for a signed commit - - - - -%GS: show the name of the signer for a signed commit - - - - -%gD: reflog selector, e.g., refs/stash@{1} - - - - -%gd: shortened reflog selector, e.g., stash@{1} - - - - -%gn: reflog identity name - - - - -%gN: reflog identity name (respecting .mailmap, see or ) - - - - -%ge: reflog identity email - - - - -%gE: reflog identity email (respecting .mailmap, see or ) - - - - -%gs: reflog subject - - - - -%Cred: switch color to red - - - - -%Cgreen: switch color to green - - - - -%Cblue: switch color to blue - - - - -%Creset: reset color - - - - -%C(…): color specification, as described in color.branch.* config option - - - - -%m: left, right or boundary mark - - - - -%n: newline - - - - -%%: a raw % - - - - -%x00: print a byte from a hex code - - - - -%w([<w>[,<i1>[,<i2>]]]): switch line wrapping, like the -w option of - . - - - - - -Some placeholders may depend on other options given to the -revision traversal engine. For example, the %g* reflog options will -insert an empty string unless we are traversing reflog entries (e.g., by -git log -g). The %d placeholder will use the "short" decoration -format if --decorate was not already provided on the command line. -If you add a + (plus sign) after % of a placeholder, a line-feed -is inserted immediately before the expansion if and only if the -placeholder expands to a non-empty string. -If you add a - (minus sign) after % of a placeholder, line-feeds that -immediately precede the expansion are deleted if and only if the -placeholder expands to an empty string. -If you add a ` ` (space) after % of a placeholder, a space -is inserted immediately before the expansion if and only if the -placeholder expands to a non-empty string. - - - -tformat: - -The tformat: format works exactly like format:, except that it -provides "terminator" semantics instead of "separator" semantics. In -other words, each commit has the message terminator character (usually a -newline) appended, rather than a separator placed between entries. -This means that the final entry of a single-line format will be properly -terminated with a new line, just as the "oneline" format does. -For example: -$ git log -2 --pretty=format:%h 4da45bef \ - | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/' -4da45be -7134973 -- NO NEWLINE - -$ git log -2 --pretty=tformat:%h 4da45bef \ - | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/' -4da45be -7134973 -In addition, any unrecognized string that has a % in it is interpreted -as if it has tformat: in front of it. For example, these two are -equivalent: -$ git log -2 --pretty=tformat:%h 4da45bef -$ git log -2 --pretty=%h 4da45bef - - - - -Examples - - - -git whatchanged -p v2.6.12.. include/scsi drivers/scsi - - - - Show as patches the commits since version v2.6.12 that changed - any file in the include/scsi or drivers/scsi subdirectories - - - - - -git whatchanged --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 - - - - - - -GIT -Part of the suite - - + + + + + git-whatchanged(1) + +git-whatchanged(1) + + +NAME +git-whatchanged - Show logs with difference each commit introduces + + +SYNOPSIS +
+git whatchanged <option>… +
+ + +DESCRIPTION +Shows commit logs and diff output each commit introduces. +New users are encouraged to use instead. The +whatchanged command is essentially the same as +but defaults to show the raw format diff output and to skip merges. +The command is kept primarily for historical reasons; fingers of +many people who learned Git long before git log was invented by +reading Linux kernel mailing list are trained to type it. + + +Examples + + + +git whatchanged -p v2.6.12.. include/scsi drivers/scsi + + + + Show as patches the commits since version v2.6.12 that changed + any file in the include/scsi or drivers/scsi subdirectories + + + + + +git whatchanged --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 + + + + + + +GIT +Part of the suite + + diff --git a/doc/source/en/TortoiseGit/git_doc/git-worktree.xml b/doc/source/en/TortoiseGit/git_doc/git-worktree.xml new file mode 100644 index 000000000..050ba0cc3 --- /dev/null +++ b/doc/source/en/TortoiseGit/git_doc/git-worktree.xml @@ -0,0 +1,319 @@ + + + + + git-worktree(1) + +git-worktree(1) + + +NAME +git-worktree - Manage multiple working trees + + +SYNOPSIS +
+git worktree add [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>] +git worktree prune [-n] [-v] [--expire <expire>] +git worktree list [--porcelain] +
+ + +DESCRIPTION +Manage multiple working trees attached to the same repository. +A git repository can support multiple working trees, allowing you to check +out more than one branch at a time. With git worktree add a new working +tree is associated with the repository. This new working tree is called a +"linked working tree" as opposed to the "main working tree" prepared by "git +init" or "git clone". A repository has one main working tree (if it's not a +bare repository) and zero or more linked working trees. +When you are done with a linked working tree you can simply delete it. +The working tree's administrative files in the repository (see +"DETAILS" below) will eventually be removed automatically (see +gc.worktreePruneExpire in ), or you can run +git worktree prune in the main or any linked working tree to +clean up any stale administrative files. +If you move a linked working tree, you need to manually update the +administrative files so that they do not get pruned automatically. See +section "DETAILS" for more information. +If a linked working tree is stored on a portable device or network share +which is not always mounted, you can prevent its administrative files from +being pruned by creating a file named locked alongside the other +administrative files, optionally containing a plain text reason that +pruning should be suppressed. See section "DETAILS" for more information. + + +COMMANDS + + + +add <path> [<branch>] + + + +Create <path> and checkout <branch> into it. The new working directory +is linked to the current repository, sharing everything except working +directory specific files such as HEAD, index, etc. + +If <branch> is omitted and neither -b nor -B nor --detached used, +then, as a convenience, a new branch based at HEAD is created automatically, +as if -b $(basename <path>) was specified. + + + + +prune + + + +Prune working tree information in $GIT_DIR/worktrees. + + + + + +list + + + +List details of each worktree. The main worktree is listed first, followed by +each of the linked worktrees. The output details include if the worktree is +bare, the revision currently checked out, and the branch currently checked out +(or detached HEAD if none). + + + + + + +OPTIONS + + + +-f + + +--force + + + + By default, add refuses to create a new working tree when <branch> + is already checked out by another working tree. This option overrides + that safeguard. + + + + + +-b <new-branch> + + +-B <new-branch> + + + + With add, create a new branch named <new-branch> starting at + <branch>, and check out <new-branch> into the new working tree. + If <branch> is omitted, it defaults to HEAD. + By default, -b refuses to create a new branch if it already + exists. -B overrides this safeguard, resetting <new-branch> to + <branch>. + + + + + +--detach + + + + With add, detach HEAD in the new working tree. See "DETACHED HEAD" + in . + + + + + +--[no-]checkout + + + + By default, add checks out <branch>, however, --no-checkout can + be used to suppress checkout in order to make customizations, + such as configuring sparse-checkout. See "Sparse checkout" + in . + + + + + +-n + + +--dry-run + + + + With prune, do not remove anything; just report what it would + remove. + + + + + +--porcelain + + + + With list, output in an easy-to-parse format for scripts. + This format will remain stable across Git versions and regardless of user + configuration. See below for details. + + + + + +-v + + +--verbose + + + + With prune, report all removals. + + + + + +--expire <time> + + + + With prune, only expire unused working trees older than <time>. + + + + + + +DETAILS +Each linked working tree has a private sub-directory in the repository's +$GIT_DIR/worktrees directory. The private sub-directory's name is usually +the base name of the linked working tree's path, possibly appended with a +number to make it unique. For example, when $GIT_DIR=/path/main/.git the +command git worktree add /path/other/test-next next creates the linked +working tree in /path/other/test-next and also creates a +$GIT_DIR/worktrees/test-next directory (or $GIT_DIR/worktrees/test-next1 +if test-next is already taken). +Within a linked working tree, $GIT_DIR is set to point to this private +directory (e.g. /path/main/.git/worktrees/test-next in the example) and +$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR +(e.g. /path/main/.git). These settings are made in a .git file located at +the top directory of the linked working tree. +Path resolution via git rev-parse --git-path uses either +$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the +linked working tree git rev-parse --git-path HEAD returns +/path/main/.git/worktrees/test-next/HEAD (not +/path/other/test-next/.git/HEAD or /path/main/.git/HEAD) while git +rev-parse --git-path refs/heads/master uses +$GIT_COMMON_DIR and returns /path/main/.git/refs/heads/master, +since refs are shared across all working trees. +See for more information. The rule of +thumb is do not make any assumption about whether a path belongs to +$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something +inside $GIT_DIR. Use git rev-parse --git-path to get the final path. +If you move a linked working tree, you need to update the gitdir file +in the entry's directory. For example, if a linked working tree is moved +to /newpath/test-next and its .git file points to +/path/main/.git/worktrees/test-next, then update +/path/main/.git/worktrees/test-next/gitdir to reference /newpath/test-next +instead. +To prevent a $GIT_DIR/worktrees entry from being pruned (which +can be useful in some situations, such as when the +entry's working tree is stored on a portable device), add a file named +locked to the entry's directory. The file contains the reason in +plain text. For example, if a linked working tree's .git file points +to /path/main/.git/worktrees/test-next then a file named +/path/main/.git/worktrees/test-next/locked will prevent the +test-next entry from being pruned. See + for details. + + +LIST OUTPUT FORMAT +The worktree list command has two output formats. The default format shows the +details on a single line with columns. For example: +S git worktree list +/path/to/bare-source (bare) +/path/to/linked-worktree abcd1234 [master] +/path/to/other-linked-worktree 1234abc (detached HEAD) +
+Porcelain Format +The porcelain format has a line per attribute. Attributes are listed with a +label and value separated by a single space. Boolean attributes (like bare +and detached) are listed as a label only, and are only present if and only +if the value is true. An empty line indicates the end of a worktree. For +example: +S git worktree list --porcelain +worktree /path/to/bare-source +bare + +worktree /path/to/linked-worktree +HEAD abcd1234abcd1234abcd1234abcd1234abcd1234 +branch refs/heads/master + +worktree /path/to/other-linked-worktree +HEAD 1234abc1234abc1234abc1234abc1234abc1234a +detached +
+ + +EXAMPLES +You are in the middle of a refactoring session and your boss comes in and +demands that you fix something immediately. You might typically use + to store your changes away temporarily, however, your +working tree is in such a state of disarray (with new, moved, and removed +files, and other bits and pieces strewn around) that you don't want to risk +disturbing any of it. Instead, you create a temporary linked working tree to +make the emergency fix, remove it when done, and then resume your earlier +refactoring session. +$ git worktree add -b emergency-fix ../temp master +$ pushd ../temp +# ... hack hack hack ... +$ git commit -a -m 'emergency fix for boss' +$ popd +$ rm -rf ../temp +$ git worktree prune + + +BUGS +Multiple checkout in general is still experimental, and the support +for submodules is incomplete. It is NOT recommended to make multiple +checkouts of a superproject. +git-worktree could provide more automation for tasks currently +performed manually, such as: + + + +remove to remove a linked working tree and its administrative files (and + warn if the working tree is dirty) + + + + +mv to move or rename a working tree and update its administrative files + + + + +lock to prevent automatic pruning of administrative files (for instance, + for a working tree on a portable device) + + + + + +GIT +Part of the suite + + diff --git a/doc/source/en/TortoiseGit/git_doc/git.xml b/doc/source/en/TortoiseGit/git_doc/git.xml index ac265f658..438fd8e46 100644 --- a/doc/source/en/TortoiseGit/git_doc/git.xml +++ b/doc/source/en/TortoiseGit/git_doc/git.xml @@ -13,7 +13,7 @@ SYNOPSIS
-git [--version] [--help] [-c <name>=<value>] +git [--version] [--help] [-C <path>] [-c <name>=<value>] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] @@ -26,14 +26,14 @@ unusually rich command set that provides both high-level operations and full access to internals. See to get started, then see -link:everyday.html[Everyday Git] for a useful minimum set of + for a useful minimum set of commands. The link:user-manual.html[Git User's Manual] has a more in-depth introduction. After you mastered the basic concepts, you can come back to this -page to learn what commands git offers. You can learn more about -individual git commands with "git help command". -manual page gives you an overview of the command line command syntax. -Formatted and hyperlinked version of the latest git documentation +page to learn what commands Git offers. You can learn more about +individual Git commands with "git help command". +manual page gives you an overview of the command-line command syntax. +Formatted and hyperlinked version of the latest Git documentation can be viewed at http://git-htmldocs.googlecode.com/git/git.html. @@ -45,7 +45,7 @@ can be viewed at http://git-htmldocs.googlecode.com/git/git.html - Prints the git suite version that the git program came from. + Prints the Git suite version that the git program came from. @@ -57,7 +57,7 @@ can be viewed at http://git-htmldocs.googlecode.com/git/git.html Prints the synopsis and a list of the most commonly used commands. If the option --all or -a is given then all - available commands are printed. If a git command is named this + available commands are printed. If a Git command is named this option will bring up the manual page for that command. Other options are available to control how the manual page is @@ -68,6 +68,25 @@ help .... +-C <path> + + + + Run as if git was started in <path> instead of the current working + directory. When multiple -C options are given, each subsequent + non-absolute -C <path> is interpreted relative to the preceding -C + <path>. + +This option affects options that expect path name like --git-dir and +--work-tree in that their interpretations of the path names would be +made relative to the working directory caused by the -C option. For +example the following invocations are equivalent: +git --git-dir=a.git --work-tree=b -C c status +git --git-dir=c/a.git --work-tree=c/b status + + + + -c <name>=<value> @@ -77,6 +96,10 @@ help .... The <name> is expected in the same format as listed by git config (subkeys separated by dots). +Note that omitting the = in git -c foo.bar ... is allowed and sets +foo.bar to the boolean true value (just like [foo]bar would in a +config file). Including the equals but with an empty value (like git -c +foo.bar= ...) sets foo.bar to the empty string. @@ -85,7 +108,7 @@ help .... - Path to wherever your core git programs are installed. + Path to wherever your core Git programs are installed. This can also be controlled by setting the GIT_EXEC_PATH environment variable. If no path is given, git will print the current setting and then exit. @@ -98,7 +121,7 @@ help .... - Print the path, without trailing slash, where git's HTML + Print the path, without trailing slash, where Git's HTML documentation is installed and exit. @@ -110,7 +133,7 @@ help .... Print the manpath (see man(1)) for the man pages for - this version of git and exit. + this version of Git and exit. @@ -121,7 +144,7 @@ help .... Print the path where the Info files documenting this - version of git are installed and exit. + version of Git are installed and exit. @@ -147,7 +170,7 @@ help .... - Do not pipe git output into a pager. + Do not pipe Git output into a pager. @@ -184,7 +207,7 @@ help .... - Set the git namespace. See for more + Set the Git namespace. See for more details. Equivalent to setting the GIT_NAMESPACE environment variable. @@ -208,16 +231,65 @@ help .... - Do not use replacement refs to replace git objects. See + Do not use replacement refs to replace Git objects. See for more information. + + +--literal-pathspecs + + + + Treat pathspecs literally (i.e. no globbing, no pathspec magic). + This is equivalent to setting the GIT_LITERAL_PATHSPECS environment + variable to 1. + + + + + +--glob-pathspecs + + + + Add "glob" magic to all pathspec. This is equivalent to setting + the GIT_GLOB_PATHSPECS environment variable to 1. Disabling + globbing on individual pathspecs can be done using pathspec + magic ":(literal)" + + + + + +--noglob-pathspecs + + + + Add "literal" magic to all pathspec. This is equivalent to setting + the GIT_NOGLOB_PATHSPECS environment variable to 1. Enabling + globbing on individual pathspecs can be done using pathspec + magic ":(glob)" + + + + + +--icase-pathspecs + + + + Add "icase" magic to all pathspec. This is equivalent to setting + the GIT_ICASE_PATHSPECS environment variable to 1. + + + GIT COMMANDS -We divide git into high level ("porcelain") commands and low level +We divide Git into high level ("porcelain") commands and low level ("plumbing") commands. @@ -263,7 +335,7 @@ ancillary user utilities. - Find by binary search the change that introduced a bug. + Use binary search to find the commit that introduced a bug. @@ -293,7 +365,7 @@ ancillary user utilities. - Checkout a branch or paths to the working tree. + Switch branches or restore working tree files. @@ -353,7 +425,7 @@ ancillary user utilities. - Show the most recent tag that is reachable from a commit. + Describe a commit using the most recent tag reachable from it. @@ -423,7 +495,7 @@ ancillary user utilities. - Create an empty git repository or reinitialize an existing one. + Create an empty Git repository or reinitialize an existing one. @@ -473,7 +545,7 @@ ancillary user utilities. - Fetch from and merge with another repository or a local branch. + Fetch from and integrate with another repository or a local branch. @@ -493,7 +565,7 @@ ancillary user utilities. - Forward-port local commits to the updated upstream head. + Reapply commits on top of another base tip. @@ -589,11 +661,21 @@ ancillary user utilities. + + + + + Manage multiple working trees. + + + + + - The git repository browser. + The Git repository browser. @@ -645,16 +727,6 @@ ancillary user utilities. - - - - - (deprecated) Recover lost refs that luckily have not yet been pruned. - - - - - @@ -709,7 +781,7 @@ ancillary user utilities. - manage set of tracked repositories. + Manage set of tracked repositories. @@ -733,16 +805,6 @@ ancillary user utilities. - - - - - - - (deprecated) Get and set repository or global options. - - - Interrogators: @@ -772,7 +834,7 @@ ancillary user utilities. - Find commits not merged upstream. + Find commits yet to be applied to upstream. @@ -822,7 +884,7 @@ ancillary user utilities. - display help information about git. + Display help information about Git. @@ -878,6 +940,16 @@ ancillary user utilities. + + + + + Check the GPG signature of commits. + + + + + @@ -919,7 +991,7 @@ people via patch over e-mail. - Import an Arch repository into git. + Import an Arch repository into Git. @@ -949,7 +1021,7 @@ people via patch over e-mail. - A CVS server emulator for git. + A CVS server emulator for Git. @@ -1009,7 +1081,7 @@ people via patch over e-mail. - Bidirectional operation between a Subversion repository and git. + Bidirectional operation between a Subversion repository and Git. @@ -1018,7 +1090,7 @@ people via patch over e-mail. Low-level commands (plumbing) -Although git includes its +Although Git includes its own porcelain layer, its low-level commands are sufficient to support development of alternative porcelains. Developers of such porcelains might start by reading about and @@ -1238,7 +1310,7 @@ repositories. - Compares content and mode of blobs between the index and repository. + Compare a tree to the working tree or index. @@ -1354,16 +1426,6 @@ repositories. - - - - - (deprecated) Create a tar archive of the files in the named tree object. - - - - - @@ -1378,7 +1440,7 @@ repositories. - Show a git logical variable. + Show a Git logical variable. @@ -1388,7 +1450,7 @@ repositories. - Validate packed git archive files. + Validate packed Git archive files. @@ -1405,7 +1467,7 @@ the working tree. - A really simple server for git repositories. + A really simple server for Git repositories. @@ -1435,7 +1497,7 @@ the working tree. - Push objects over git protocol to another repository. + Push objects over Git protocol to another repository. @@ -1459,7 +1521,7 @@ typically do not use them directly. - Download from a remote git repository via HTTP. + Download from a remote Git repository via HTTP. @@ -1542,6 +1604,26 @@ users typically do not use them directly. + + + + + Debug gitignore / exclude files. + + + + + + + + + + Show canonical names and email addresses of contacts. + + + + + @@ -1602,51 +1684,51 @@ users typically do not use them directly. - + - Extracts patch and authorship from a single e-mail message. + help add structured information into commit messages. - + - Simple UNIX mbox splitter program. + Extracts patch and authorship from a single e-mail message. - + - The standard helper program to use with git-merge-index. + Simple UNIX mbox splitter program. - + - Compute unique ID for a patch. + The standard helper program to use with git-merge-index. - + - (deprecated) List the references in a remote repository. + Compute unique ID for a patch. @@ -1666,7 +1748,7 @@ users typically do not use them directly. - Common git shell script setup code. + Common Git shell script setup code. @@ -1685,10 +1767,9 @@ users typically do not use them directly. Configuration Mechanism -Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file -is used to hold per-repository configuration options. It is a -simple text file modeled after .ini format familiar to some -people. Here is an example: +Git uses a simple text format to store customizations that are per +repository and are per user. Such a configuration file may look +like this: # # A '#' or ';' character indicates a comment. # @@ -1701,10 +1782,10 @@ people. Here is an example: ; user identity [user] name = "Junio C Hamano" - email = "junkio@twinsun.com" + email = "gitster@pobox.com" Various commands read from the configuration file and adjust their operation accordingly. See for a -list. +list and more details about the configuration mechanism. Identifier Terminology @@ -1801,7 +1882,7 @@ list. Symbolic Identifiers -Any git command accepting any <object> can also use the following +Any Git command accepting any <object> can also use the following symbolic notation: @@ -1853,12 +1934,12 @@ HEAD Environment Variables -Various git commands use the following environment variables: +Various Git commands use the following environment variables:
-The git Repository -These environment variables apply to all core git commands. Nb: it +The Git Repository +These environment variables apply to all core Git commands. Nb: it is worth noting that they may be used/overridden by SCMS sitting above -git so take care if using Cogito etc. +Git so take care if using a foreign front-end. @@ -1874,6 +1955,19 @@ git so take care if using Cogito etc. +GIT_INDEX_VERSION + + + + This environment variable allows the specification of an index + version for new repositories. It won't affect existing index + files. By default index file version 2 or 3 is used. See + for more information. + + + + + GIT_OBJECT_DIRECTORY @@ -1891,10 +1985,10 @@ git so take care if using Cogito etc. - Due to the immutable nature of git objects, old objects can be + Due to the immutable nature of Git objects, old objects can be archived into shared, read-only directories. This variable specifies a ":" separated (on Windows ";" separated) list - of git object directories which can be used to search for git + of Git object directories which can be used to search for Git objects. New objects will not be written to these directories. @@ -1918,10 +2012,8 @@ git so take care if using Cogito etc. - Set the path to the working tree. The value will not be - used in combination with repositories found automatically in - a .git directory (i.e. $GIT_DIR is not set). - This can also be controlled by the --work-tree command line + Set the path to the root of the working tree. + This can also be controlled by the --work-tree command-line option and the core.worktree configuration variable. @@ -1932,7 +2024,7 @@ git so take care if using Cogito etc. - Set the git namespace; see for details. + Set the Git namespace; see for details. The --namespace command-line option also sets this value. @@ -1943,12 +2035,19 @@ git so take care if using Cogito etc. - This should be a colon-separated list of absolute paths. - If set, it is a list of directories that git should not chdir - up into while looking for a repository directory. - It will not exclude the current working directory or - a GIT_DIR set on the command line or in the environment. - (Useful for excluding slow-loading network directories.) + This should be a colon-separated list of absolute paths. If + set, it is a list of directories that Git should not chdir up + into while looking for a repository directory (useful for + excluding slow-loading network directories). It will not + exclude the current working directory or a GIT_DIR set on the + command line or in the environment. Normally, Git has to read + the entries in this list and resolve any symlink that + might be present in order to compare them with the current + directory. However, if even this access is slow, you + can add an empty entry to the list to tell Git that the + subsequent entries are not symlinks and needn't be resolved; + e.g., + GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink. @@ -1959,20 +2058,36 @@ git so take care if using Cogito etc. When run in a directory that does not have ".git" repository - directory, git tries to find such a directory in the parent + directory, Git tries to find such a directory in the parent directories to find the top of the working tree, but by default it does not cross filesystem boundaries. This environment variable - can be set to true to tell git not to stop at filesystem + can be set to true to tell Git not to stop at filesystem boundaries. Like GIT_CEILING_DIRECTORIES, this will not affect an explicit repository directory set via GIT_DIR or on the command line. + + +GIT_COMMON_DIR + + + + If this variable is set to a path, non-worktree files that are + normally in $GIT_DIR will be taken from this path + instead. Worktree-specific files such as HEAD or index are + taken from $GIT_DIR. See and + for + details. This variable has lower precedence than other path + variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY… + + +
-git Commits +Git Commits @@ -2005,7 +2120,7 @@ git so take care if using Cogito etc.
-git Diffs +Git Diffs @@ -2016,7 +2131,7 @@ git so take care if using Cogito etc. Only valid setting is "--unified=??" or "-u??" to set the number of context lines shown when a unified diff is created. This takes precedence over any "-U" or "--unified" option - value passed on the git diff command line. + value passed on the Git diff command line. @@ -2052,7 +2167,7 @@ are files GIT_EXTERNAL_DIFF can use to read the -are the 40-hexdigit SHA1 hashes, +are the 40-hexdigit SHA-1 hashes, @@ -2071,6 +2186,28 @@ index). GIT_EXTERNAL_DIFF should not worry about unlinking 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>. +For each path GIT_EXTERNAL_DIFF is called, two environment variables, +GIT_DIFF_PATH_COUNTER and GIT_DIFF_PATH_TOTAL are set. + + + + +GIT_DIFF_PATH_COUNTER + + + + A 1-based counter incremented by one for every path. + + + + + +GIT_DIFF_PATH_TOTAL + + + + The total number of paths. + @@ -2097,7 +2234,7 @@ parameter, <path>. This environment variable overrides $PAGER. If it is set - to an empty string or to the value "cat", git will not launch + to an empty string or to the value "cat", Git will not launch a pager. See also the core.pager option in . @@ -2110,7 +2247,7 @@ parameter, <path>. This environment variable overrides $EDITOR and $VISUAL. - It is used by several git commands when, on interactive mode, + It is used by several Git commands when, on interactive mode, an editor is to be launched. See also and the core.editor option in . @@ -2120,18 +2257,25 @@ parameter, <path>. GIT_SSH + +GIT_SSH_COMMAND + - If this environment variable is set then git fetch - and git push will use this command instead - of ssh when they need to connect to a remote system. - The $GIT_SSH command will be given exactly two arguments: - the username@host (or just host) from the URL and the - shell command to execute on that remote system. + If either of these environment variables is set then git fetch + and git push will use the specified command instead of ssh + when they need to connect to a remote system. + The command will be given exactly two or four arguments: the + username@host (or just host) from the URL and the shell + command to execute on that remote system, optionally preceded by + -p (literally) and the port from the URL when it specifies + something other than the default SSH port. -To pass options to the program that you want to list in GIT_SSH -you will need to wrap the program and options into a shell script, -then set GIT_SSH to refer to the shell script. +$GIT_SSH_COMMAND takes precedence over $GIT_SSH, and is interpreted +by the shell, which allows additional arguments to be included. +$GIT_SSH on the other hand must be just the path to a program +(which can be a wrapper shell script, if additional arguments are +needed). Usually it is easier to configure any desired options through your personal .ssh/config file. Please consult your ssh documentation for further details. @@ -2143,27 +2287,54 @@ for further details. - If this environment variable is set, then git commands which need to + If this environment variable is set, then Git commands which need to acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) - will call this program with a suitable prompt as command line argument - and read the password from its STDOUT. See also the core.askpass + will call this program with a suitable prompt as command-line argument + and read the password from its STDOUT. See also the core.askPass option in . +GIT_TERMINAL_PROMPT + + + + If this environment variable is set to 0, git will not prompt + on the terminal (e.g., when asking for HTTP authentication). + + + + + +GIT_CONFIG_NOSYSTEM + + + + Whether to skip reading settings from the system-wide + $(prefix)/etc/gitconfig file. This environment variable can + be used along with $HOME and $XDG_CONFIG_HOME to create a + predictable environment for a picky script, or you can set it + temporarily to avoid using a buggy /etc/gitconfig file while + waiting for someone with sufficient permissions to fix it. + + + + + GIT_FLUSH If this environment variable is set to "1", then commands such as git blame (in incremental mode), git rev-list, git log, - and git whatchanged will force a flush of the output stream - after each commit-oriented record have been flushed. If this + git check-attr and git check-ignore will + force a flush of the output stream after each record have been + flushed. If this variable is set to "0", the output of these commands will be done using completely buffered I/O. If this environment variable is - not set, git will choose buffered or record-oriented flushing + not set, Git will choose buffered or record-oriented flushing based on whether stdout appears to be redirected to a file or not. @@ -2174,30 +2345,247 @@ for further details. - If this variable is set to "1", "2" or "true" (comparison - is case insensitive), git will print trace: messages on - stderr telling about alias expansion, built-in command - execution and external command execution. - If this variable is set to an integer value greater than 1 - and lower than 10 (strictly) then git will interpret this - value as an open file descriptor and will try to write the - trace messages into this file descriptor. - Alternatively, if this variable is set to an absolute path - (starting with a / character), git will interpret this - as a file path and will try to write the trace messages - into it. + Enables general trace messages, e.g. alias expansion, built-in + command execution and external command execution. + +If this variable is set to "1", "2" or "true" (comparison +is case insensitive), trace messages will be printed to +stderr. +If the variable is set to an integer value greater than 2 +and lower than 10 (strictly) then Git will interpret this +value as an open file descriptor and will try to write the +trace messages into this file descriptor. +Alternatively, if the variable is set to an absolute path +(starting with a / character), Git will interpret this +as a file path and will try to write the trace messages +into it. +Unsetting the variable, or setting it to empty, "0" or +"false" (case insensitive) disables trace messages. + + + + +GIT_TRACE_PACK_ACCESS + + + + Enables trace messages for all accesses to any packs. For each + access, the pack file name and an offset in the pack is + recorded. This may be helpful for troubleshooting some + pack-related performance problems. + See GIT_TRACE for available trace output options. + + + + + +GIT_TRACE_PACKET + + + + Enables trace messages for all packets coming in or out of a + given program. This can help with debugging object negotiation + or other protocol issues. Tracing is turned off at a packet + starting with "PACK" (but see GIT_TRACE_PACKFILE below). + See GIT_TRACE for available trace output options. + + + + + +GIT_TRACE_PACKFILE + + + + Enables tracing of packfiles sent or received by a + given program. Unlike other trace output, this trace is + verbatim: no headers, and no quoting of binary data. You almost + certainly want to direct into a file (e.g., + GIT_TRACE_PACKFILE=/tmp/my.pack) rather than displaying it on + the terminal or mixing it with other trace output. + +Note that this is currently only implemented for the client side +of clones and fetches. + + + + +GIT_TRACE_PERFORMANCE + + + + Enables performance related trace messages, e.g. total execution + time of each Git command. + See GIT_TRACE for available trace output options. + + + + + +GIT_TRACE_SETUP + + + + Enables trace messages printing the .git, working tree and current + working directory after Git has completed its setup phase. + See GIT_TRACE for available trace output options. + + + + + +GIT_TRACE_SHALLOW + + + + Enables trace messages that can help debugging fetching / + cloning of shallow repositories. + See GIT_TRACE for available trace output options. + + +GIT_LITERAL_PATHSPECS + + + + Setting this variable to 1 will cause Git to treat all + pathspecs literally, rather than as glob patterns. For example, + running GIT_LITERAL_PATHSPECS=1 git log -- '*.c' will search + for commits that touch the path *.c, not any paths that the + glob *.c matches. You might want this if you are feeding + literal paths to Git (e.g., paths previously given to you by + git ls-tree, --raw diff output, etc). + + + + + +GIT_GLOB_PATHSPECS + + + + Setting this variable to 1 will cause Git to treat all + pathspecs as glob patterns (aka "glob" magic). + + + + + +GIT_NOGLOB_PATHSPECS + + + + Setting this variable to 1 will cause Git to treat all + pathspecs as literal (aka "literal" magic). + + + + + +GIT_ICASE_PATHSPECS + + + + Setting this variable to 1 will cause Git to treat all + pathspecs as case-insensitive. + + + + + +GIT_REFLOG_ACTION + + + + When a ref is updated, reflog entries are created to keep + track of the reason why the ref was updated (which is + typically the name of the high-level command that updated + the ref), in addition to the old and new values of the ref. + A scripted Porcelain command can use set_reflog_action + helper function in git-sh-setup to set its name to this + variable when it is invoked as the top level command by the + end user, to be recorded in the body of the reflog. + + + + + +GIT_REF_PARANOIA + + + + If set to 1, include broken or badly named refs when iterating + over lists of refs. In a normal, non-corrupted repository, this + does nothing. However, enabling it may help git to detect and + abort some operations in the presence of broken refs. Git sets + this variable automatically when performing destructive + operations like . You should not need to set + it yourself unless you want to be paranoid about making sure + an operation has touched every ref (e.g., because you are + cloning a repository to make a backup). + + + + + +GIT_ALLOW_PROTOCOL + + + + If set, provide a colon-separated list of protocols which are + allowed to be used with fetch/push/clone. This is useful to + restrict recursive submodule initialization from an untrusted + repository. Any protocol not mentioned will be disallowed (i.e., + this is a whitelist, not a blacklist). If the variable is not + set at all, all protocols are enabled. The protocol names + currently used by git are: + + + + +file: any local file-based path (including file:// URLs, + or local paths) + + + + +git: the anonymous git protocol over a direct TCP + connection (or proxy, if configured) + + + + +ssh: git over ssh (including host:path syntax, + ssh://, etc). + + + + +http: git over http, both "smart http" and "dumb http". + Note that this does not include https; if you want both, + you should specify both as http:https. + + + + +any external helpers are named by their protocol (e.g., use + hg to allow the git-remote-hg helper) + + + + +
Discussion<anchor id="git(1)_Discussion" xreflabel="[Discussion]"/> More detail on the following is available from the -git concepts chapter of the +Git concepts chapter of the user-manual and . -A git project normally consists of a working directory with a ".git" +A Git project normally consists of a working directory with a ".git" subdirectory at the top level. The .git directory contains, among other things, a compressed object database representing the complete history of the project, an "index" file which links that history to the current @@ -2211,7 +2599,7 @@ and some number of parent commits. "version", represents a step in the project's history, and each parent represents an immediately preceding step. Commits with more than one parent represent merges of independent lines of development. -All objects are named by the SHA1 hash of their contents, normally +All objects are named by the SHA-1 hash of their contents, normally written as a string of 40 hex digits. Such names are globally unique. The entire history leading up to a commit can be vouched for by signing just that commit. A fourth object type, the tag, is provided for this @@ -2219,9 +2607,9 @@ purpose. When first created, objects are stored in individual files, but for efficiency may later be compressed together into "pack files". Named pointers called refs mark interesting points in history. A ref -may contain the SHA1 name of an object or the name of another ref. Refs -with names beginning ref/head/ contain the SHA1 name of the most -recent commit (or "head") of a branch under development. SHA1 names of +may contain the SHA-1 name of an object or the name of another ref. Refs +with names beginning ref/head/ contain the SHA-1 name of the most +recent commit (or "head") of a branch under development. SHA-1 names of tags of interest are stored under ref/tags/. A special ref named HEAD contains the name of the currently checked-out branch. The index file is initialized with a list of all paths and, for each @@ -2239,24 +2627,24 @@ unmerged version of a file when a merge is in progress. FURTHER DOCUMENTATION See the references in the "description" section to get started -using git. The following is probably more detail than necessary +using Git. The following is probably more detail than necessary for a first-time user. -The git concepts chapter of the +The Git concepts chapter of the user-manual and both provide -introductions to the underlying git architecture. +introductions to the underlying Git architecture. See for an overview of recommended workflows. See also the link:howto-index.html[howto] documents for some useful examples. The internals are documented in the -link:technical/api-index.html[GIT API documentation]. +link:technical/api-index.html[Git API documentation]. Users migrating from CVS may also want to read . Authors Git was started by Linus Torvalds, and is currently maintained by Junio -C Hamano. Numerous contributions have come from the git mailing list -<git@vger.kernel.org>. http://www.ohloh.net/p/git/contributors/summary +C Hamano. Numerous contributions have come from the Git mailing list +<git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary gives you a more complete list of contributors. If you have a clone of git.git itself, the output of and can show you @@ -2271,7 +2659,7 @@ subscribed to the list to send a message there. SEE ALSO , , -link:everyday.html[Everyday Git], , +, , , , , link:user-manual.html[The Git User's Manual], diff --git a/doc/source/en/TortoiseGit/git_doc/gitattributes.xml b/doc/source/en/TortoiseGit/git_doc/gitattributes.xml index a6678a7f7..9763e1273 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitattributes.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitattributes.xml @@ -81,7 +81,7 @@ overrides an earlier line. This overriding is done per attribute. The rules how the pattern matches paths are the same as in .gitignore files; see . Unlike .gitignore, negative patterns are forbidden. -When deciding what attributes are assigned to a path, git +When deciding what attributes are assigned to a path, Git consults $GIT_DIR/info/attributes file (which has the highest precedence), .gitattributes file in the same directory as the path in question, and its parent directories up to the toplevel of the @@ -101,7 +101,7 @@ Attributes which should be version-controlled and distributed to other repositories (i.e., attributes of interest to all users) should go into .gitattributes files. Attributes that should affect all repositories for a single user should be placed in a file specified by the -core.attributesfile configuration option (see ). +core.attributesFile configuration option (see ). Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/attributes is used instead. Attributes for all users on a system should be placed in the @@ -112,7 +112,7 @@ the name of the attribute prefixed with an exclamation point ! EFFECTS -Certain operations by git can be influenced by assigning +Certain operations by Git can be influenced by assigning particular attributes to a path. Currently, the following operations are attributes-aware.
@@ -120,7 +120,7 @@ operations are attributes-aware. These attributes affect how the contents stored in the repository are copied to the working tree files when commands such as git checkout and git merge run. They also affect how -git stores the contents you prepare in the working tree in the +Git stores the contents you prepare in the working tree in the repository upon git add and git commit.
<emphasis>text</emphasis> @@ -148,7 +148,7 @@ Unset - Unsetting the text attribute on a path tells git not to + Unsetting the text attribute on a path tells Git not to attempt any end-of-line conversion upon checkin or checkout. @@ -160,7 +160,7 @@ Set to string value "auto" When text is set to "auto", the path is marked for automatic - end-of-line normalization. If git decides that the content is + end-of-line normalization. If Git decides that the content is text, its line endings are normalized to LF on checkin. @@ -171,14 +171,14 @@ Unspecified - If the text attribute is unspecified, git uses the + If the text attribute is unspecified, Git uses the core.autocrlf configuration variable to determine if the file should be converted. -Any other value causes git to act as if text has been left +Any other value causes Git to act as if text has been left unspecified.
@@ -193,7 +193,7 @@ Set to string value "crlf" - This setting forces git to normalize line endings for this + This setting forces Git to normalize line endings for this file on checkin and convert them to CRLF when the file is checked out. @@ -205,7 +205,7 @@ Set to string value "lf" - This setting forces git to normalize line endings to LF on + This setting forces Git to normalize line endings to LF on checkin and prevents conversion to CRLF when the file is checked out. @@ -223,10 +223,10 @@ crlf=input eol=lf
End-of-line conversion -While git normally leaves file contents alone, it can be configured to +While Git normally leaves file contents alone, it can be configured to normalize line endings to LF in the repository and, optionally, to convert them to CRLF when files are checked out. -Here is an example that will make git normalize .txt, .vcproj and .sh +Here is an example that will make Git normalize .txt, .vcproj and .sh files, ensure that .vcproj files have CRLF and .sh files have LF in the working directory, and prevent .jpg files from being normalized regardless of their content. @@ -236,7 +236,7 @@ regardless of their content. *.jpg -text Other source code management systems normalize all text files in their repositories, and there are two ways to enable similar automatic -normalization in git. +normalization in Git. If you simply want to have CRLF line endings in your working directory regardless of the repository you are working with, you can set the config variable "core.autocrlf" without changing any attributes. @@ -251,9 +251,9 @@ enforces end-of-line normalization, or you simply want all text files in your repository to be normalized, you should instead set the text attribute to "auto" for all files. * text=auto -This ensures that all files that git considers to be text will have +This ensures that all files that Git considers to be text will have normalized (LF) line endings in the repository. The core.eol -configuration variable controls which line endings git will use for +configuration variable controls which line endings Git will use for normalized files in your working directory; the default is to use the native line ending for your platform, or CRLF if core.autocrlf is set. @@ -263,7 +263,7 @@ they are not they will be normalized the next time someone tries to change them, causing unfortunate misattribution. From a clean working directory: $ echo "* text=auto" >>.gitattributes -$ rm .git/index # Remove the index to force git to +$ rm .git/index # Remove the index to force Git to $ git reset # re-scan the working directory $ git status # Show files that will be normalized $ git add -u @@ -272,13 +272,13 @@ $ git commit -m "Introduce end-of-line normalization" If any files that should not be normalized show up in git status, unset their text attribute before running git add -u. manual.pdf -text -Conversely, text files that git does not detect can have normalization +Conversely, text files that Git does not detect can have normalization enabled manually. weirdchars.txt text -If core.safecrlf is set to "true" or "warn", git verifies if +If core.safecrlf is set to "true" or "warn", Git verifies if the conversion is reversible for the current setting of -core.autocrlf. For "true", git rejects irreversible -conversions; for "warn", git only prints a warning but accepts +core.autocrlf. For "true", Git rejects irreversible +conversions; for "warn", Git only prints a warning but accepts an irreversible conversion. The safety triggers to prevent such a conversion done to the files in the work tree, but there are a few exceptions. Even though… @@ -308,7 +308,7 @@ few exceptions. Even though…
<emphasis>ident</emphasis> -When the attribute ident is set for a path, git replaces +When the attribute ident is set for a path, Git replaces $Id$ in the blob object with $Id:, followed by the 40-character hexadecimal blob object name, followed by a dollar sign $ upon checkout. Any byte sequence that begins with @@ -334,7 +334,7 @@ is that if someone unsets the filter driver definition, or does not have the appropriate filter program, the project should still be usable. Another use of the content filtering is to store the content that cannot be directly used in the repository (e.g. a UUID that refers to the true -content stored outside git, or an encrypted content) and turn it into a +content stored outside Git, or an encrypted content) and turn it into a usable form upon checkout (e.g. download the external content, or decrypt the encrypted content). These two filters behave differently, and by default, a filter is taken as @@ -394,7 +394,7 @@ repository format for that file to change, such as adding a clean/smudge filter or text/eol/ident attributes, merging anything where the attribute is not in place would normally cause merge conflicts. -To prevent these unnecessary merge conflicts, git can be told to run a +To prevent these unnecessary merge conflicts, Git can be told to run a virtual check-out and check-in of all three stages of a file when resolving a three-way merge by setting the merge.renormalize configuration variable. This prevents changes caused by check-in @@ -411,11 +411,11 @@ resolved manually. Generating diff text
<emphasis>diff</emphasis> -The attribute diff affects how git generates diffs for particular -files. It can tell git whether to generate a textual patch for the path +The attribute diff affects how Git generates diffs for particular +files. It can tell Git whether to generate a textual patch for the path or to treat the path as a binary file. It can also affect what line is -shown on the hunk header @@ -k,l +n,m @@ line, tell git to use an -external command to generate the diff, or ask git to convert binary +shown on the hunk header @@ -k,l +n,m @@ line, tell Git to use an +external command to generate the diff, or ask Git to convert binary files to a text format before generating the diff. @@ -450,8 +450,8 @@ Unspecified A path to which the diff attribute is unspecified first gets its contents inspected, and if it looks like - text, it is treated as text. Otherwise it would - generate Binary files differ. + text and is smaller than core.bigFileThreshold, it is treated + as text. Otherwise it would generate Binary files differ. @@ -465,7 +465,7 @@ String specify one or more options, as described in the following section. The options for the diff driver "foo" are defined by the configuration variables in the "diff.foo" section of the - git config file. + Git config file. @@ -480,7 +480,7 @@ wrong place to talk about it. However… $GIT_DIR/config file (or $HOME/.gitconfig file) like this: [diff "jcdiff"] command = j-c-diff -When git needs to show you a diff for the path with diff +When Git needs to show you a diff for the path with diff attribute set to jcdiff, it calls the command you specified with the above configuration, i.e. j-c-diff, with 7 parameters, just like GIT_EXTERNAL_DIFF program is called. @@ -543,6 +543,11 @@ patterns are available: +fountain suitable for Fountain documents. + + + + html suitable for HTML/XHTML documents. @@ -637,7 +642,7 @@ because it quickly conveys the changes you have made), you should generate it separately and send it as a comment in addition to the usual binary diff that you might send. Because text conversion can be slow, especially when doing a -large number of them with git log -p, git provides a mechanism +large number of them with git log -p, Git provides a mechanism to cache the output and use it in future diffs. To enable caching, set the "cachetextconv" variable in your diff driver's config. For example: @@ -646,7 +651,7 @@ config. For example: cachetextconv = true This will cache the result of running "exif" on each blob indefinitely. If you change the textconv config variable for a -diff driver, git will automatically invalidate the cache entries +diff driver, Git will automatically invalidate the cache entries and re-run the textconv filter. If you want to invalidate the cache manually (e.g., because your version of "exif" was updated and now produces better output), you can remove the cache @@ -664,7 +669,7 @@ not bound to find line-oriented changes, nor is it necessary for the output to resemble unified diff. You are free to locate and report changes in the most appropriate way for your data format. A textconv, by comparison, is much more limiting. You provide a -transformation of the data into a line-oriented text format, and git +transformation of the data into a line-oriented text format, and Git uses its regular diff tools to generate the output. There are several advantages to choosing this method: @@ -679,7 +684,7 @@ Ease of use. It is often much simpler to write a binary to text Git diff features. By performing only the transformation step - yourself, you can still utilize many of git's diff features, + yourself, you can still utilize many of Git's diff features, including colorization, word-diff, and combined diffs for merges. @@ -698,16 +703,16 @@ data by examining the beginning of the contents. However, sometimes you may want to override its decision, either because a blob contains binary data later in the file, or because the content, while technically composed of text characters, is opaque to a human reader. For example, -many postscript files contain only ascii characters, but produce noisy +many postscript files contain only ASCII characters, but produce noisy and meaningless diffs. The simplest way to mark a file as binary is to unset the diff attribute in the .gitattributes file: *.ps -diff -This will cause git to generate Binary files differ (or a binary +This will cause Git to generate Binary files differ (or a binary patch, if binary patches are enabled) instead of a regular diff. However, one may also want to specify other diff driver attributes. For example, you might want to use textconv to convert postscript files to -an ascii representation for human viewing, but otherwise treat them as +an ASCII representation for human viewing, but otherwise treat them as binary files. You cannot specify both -diff and diff=ps attributes. The solution is to use the diff.*.binary config option: [diff "ps"] @@ -836,7 +841,7 @@ manual page is a wrong place to talk about it. However… $GIT_DIR/config file (or $HOME/.gitconfig file) like this: [merge "filfre"] name = feel-free merge driver - driver = filfre %O %A %B + driver = filfre %O %A %B %L %P recursive = binary The merge.*.name variable gives the driver a human-readable name. @@ -856,6 +861,8 @@ driver to use when the merge driver is called for an internal merge between common ancestors, when there are more than one. When left unspecified, the driver itself is used for both internal merge and the final merge. +The merge driver can learn the pathname in which the merged result +will be stored via placeholder %P.
<emphasis>conflict-marker-size</emphasis> @@ -884,7 +891,7 @@ Set - Notice all types of potential whitespace errors known to git. + Notice all types of potential whitespace errors known to Git. The tab width is taken from the value of the core.whitespace configuration variable. @@ -935,7 +942,7 @@ archive files.
<emphasis>export-subst</emphasis> -If the attribute export-subst is set for a file then git will expand +If the attribute export-subst is set for a file then Git will expand several placeholders when adding this file to an archive. The expansion depends on the availability of a commit ID, i.e., if has been given a tree instead of a commit or a @@ -987,9 +994,12 @@ state. DEFINING MACRO ATTRIBUTES -Custom macro attributes can be defined only in the .gitattributes -file at the toplevel (i.e. not in any subdirectory). The built-in -macro attribute "binary" is equivalent to: +Custom macro attributes can be defined only in top-level gitattributes +files ($GIT_DIR/info/attributes, the .gitattributes file at the +top level of the working tree, or the global or system-wide +gitattributes files), not in .gitattributes files in working tree +subdirectories. The built-in macro attribute "binary" is equivalent +to: [attr]binary -diff -merge -text @@ -1011,7 +1021,7 @@ abc -foo -bar By examining t/.gitattributes (which is in the same - directory as the path in question), git finds that the first + directory as the path in question), Git finds that the first line matches. merge attribute is set. It also finds that the second line matches, and attributes foo and bar are unset. diff --git a/doc/source/en/TortoiseGit/git_doc/gitcli.xml b/doc/source/en/TortoiseGit/git_doc/gitcli.xml index 8a6ee10c2..88b1f9936 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitcli.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitcli.xml @@ -8,7 +8,7 @@ NAME -gitcli - git command line interface and conventions +gitcli - Git command-line interface and conventions SYNOPSIS @@ -16,7 +16,7 @@ DESCRIPTION -This manual describes the convention used throughout git CLI. +This manual describes the convention used throughout Git CLI. Many commands take revisions (most often "commits", but sometimes "tree-ish", depending on the context and command) and paths as their arguments. Here are the rules: @@ -35,14 +35,14 @@ When an argument can be misunderstood as either a revision or a path, they can be disambiguated by placing -- between them. E.g. git diff -- HEAD is, "I have a file called HEAD in my work tree. Please show changes between the version I staged in the index - and what I have in the work tree for that file". not "show difference + and what I have in the work tree for that file", not "show difference between the HEAD commit and the work tree as a whole". You can say git diff HEAD -- to ask for the latter. -Without disambiguating --, git makes a reasonable guess, but errors +Without disambiguating --, Git makes a reasonable guess, but errors out and asking you to disambiguate when ambiguous. E.g. if you have a file called HEAD in your work tree, git diff HEAD is ambiguous, and you have to say either git diff HEAD -- or git diff -- HEAD to @@ -68,13 +68,20 @@ working tree. After running git add hello.c; rm hello.c, y see hello.c in your working tree with the former, but with the latter you will. + + +Just as the filesystem . (period) refers to the current directory, + using a . as a repository name in Git (a dot-repository) is a relative + path and means your current repository. + + Here are the rules regarding the "flags" that you should follow when you are -scripting git: +scripting Git: -it's preferred to use the non dashed form of git commands, which means that +it's preferred to use the non-dashed form of Git commands, which means that you should prefer git foo to git-foo. @@ -86,11 +93,11 @@ splitting short options to separate words (prefer git foo -a -b -when a command line option takes an argument, use the sticked form. In +when a command-line option takes an argument, use the stuck form. In other words, write git foo -oArg instead of git foo -o Arg for short options, and git foo --long-opt=Arg instead of git foo --long-opt Arg for long options. An option that takes optional option-argument must be - written in the sticked form. + written in the stuck form. @@ -103,12 +110,12 @@ when you give a revision parameter to a command, make sure the parameter is -many commands allow a long option "--option" to be abbreviated +many commands allow a long option --option to be abbreviated only to their unique prefix (e.g. if there is no other option - whose name begins with "opt", you may be able to spell "--opt" to - invoke the "--option" flag), but you should fully spell them out + whose name begins with opt, you may be able to spell --opt to + invoke the --option flag), but you should fully spell them out when writing your scripts; later versions of Git may introduce a - new option whose name shares the same prefix, e.g. "--optimize", + new option whose name shares the same prefix, e.g. --optimize, to make a short prefix that used to be unique no longer unique. @@ -116,13 +123,13 @@ many commands allow a long option "--option" to be abbreviated ENHANCED OPTION PARSER -From the git 1.5.4 series and further, many git commands (not all of them at the +From the Git 1.5.4 series and further, many Git commands (not all of them at the time of the writing though) come with an enhanced option parser. Here is a list of the facilities provided by this option parser.
Magic Options Commands which have the enhanced option parser activated all understand a -couple of magic command line options: +couple of magic command-line options: @@ -133,14 +140,15 @@ couple of magic command line options: gives a pretty printed usage of the command. $ git describe -h -usage: git describe [options] <committish>* +usage: git describe [options] <commit-ish>* + or: git describe [options] --dirty --contains find the tag that comes after the commit --debug debug search strategy on stderr - --all use any ref in .git/refs - --tags use any tag in .git/refs/tags - --abbrev [<n>] use <n> digits to display SHA-1s - --candidates <n> consider <n> most recent tags (default: 10) + --all use any ref + --tags use any tag, even unannotated + --long always use long format + --abbrev[=<n>] use <n> digits to display SHA-1s @@ -149,7 +157,7 @@ usage: git describe [options] <committish>* - Some git commands take options that are only used for plumbing or that + Some Git commands take options that are only used for plumbing or that are deprecated, and such options are hidden from the default usage. This option gives the full list of options. @@ -177,7 +185,7 @@ prefix of a long option as if it is fully spelled out, but use this with a caution. For example, git commit --amen behaves as if you typed git commit --amend, but that is true only until a later version of Git introduces another option that shares the same prefix, -e.g `git commit --amenity" option. +e.g. git commit --amenity option.
Separating argument from the option @@ -188,7 +196,7 @@ $ git foo --long-opt Arg $ git foo -oArg $ git foo -o Arg However, this is NOT allowed for switches with an optional value, where the -sticked form must be used: +stuck form must be used: $ git describe --abbrev HEAD # correct $ git describe --abbrev=10 HEAD # correct $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT diff --git a/doc/source/en/TortoiseGit/git_doc/gitcore-tutorial.xml b/doc/source/en/TortoiseGit/git_doc/gitcore-tutorial.xml index 41ee8ab07..a3d3d867a 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitcore-tutorial.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitcore-tutorial.xml @@ -8,7 +8,7 @@ NAME -gitcore-tutorial - A git core tutorial for developers +gitcore-tutorial - A Git core tutorial for developers SYNOPSIS @@ -16,14 +16,14 @@ DESCRIPTION -This tutorial explains how to use the "core" git commands to set up and -work with a git repository. -If you just need to use git as a revision control system you may prefer -to start with "A Tutorial Introduction to GIT" () or -link:user-manual.html[the GIT User Manual]. +This tutorial explains how to use the "core" Git commands to set up and +work with a Git repository. +If you just need to use Git as a revision control system you may prefer +to start with "A Tutorial Introduction to Git" () or +link:user-manual.html[the Git User Manual]. However, an understanding of these low-level tools can be helpful if -you want to understand git's internals. -The core git is often called "plumbing", with the prettier user +you want to understand Git's internals. +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. @@ -38,22 +38,22 @@ commands do is still valid. skip on your first reading. -Creating a git repository -Creating a new git repository couldn't be easier: all git repositories start +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. +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: +subdirectory, and initialize the Git infrastructure with git init: $ mkdir git-tutorial $ cd git-tutorial $ git init -to which git will reply +to which Git will reply Initialized empty Git repository in .git/ -which is just git's way of saying that you haven't been doing anything +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 @@ -96,11 +96,11 @@ 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 +branch. A number of the Git tools will assume that .git/HEAD is valid, though. -An object is identified by its 160-bit SHA1 hash, aka object name, +An object is identified by its 160-bit SHA-1 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 +representation of that SHA-1 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 @@ -108,15 +108,15 @@ references in these refs subdirectories when you actually s populating your tree. An advanced user may want to take a look at after finishing this tutorial. -You have now created your first git repository. Of course, since it's +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 +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 +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 @@ -135,7 +135,7 @@ commit that index file as an object. -The first step is trivial: when you want to tell git about any changes +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 @@ -144,9 +144,9 @@ adding a new entry with the --add flag (or removing an entr --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. +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 +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: @@ -158,7 +158,7 @@ database. If you did exactly the steps above, you should now be able to do $ 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 (i.e., just a +object is. Git will tell you that you have a "blob" object (i.e., 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 @@ -174,21 +174,21 @@ hexadecimal digits in most places. 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 +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 +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 +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 @@ -221,9 +221,9 @@ index 557db03..263414f 100644 +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 +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. @@ -232,7 +232,7 @@ There are no options or other input: git write-tree will ta 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: +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 @@ -316,9 +316,9 @@ files to compare (the "meta-data") always com 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 +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 +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. @@ -329,7 +329,7 @@ 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 +(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 @@ -352,7 +352,7 @@ 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 +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 @@ -410,32 +410,13 @@ 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 -and you will see exactly what has changed in the repository over its -short history. -When using the above two commands, the initial commit will be shown. -If this is a problem because it is huge, you can hide it by setting -the log.showroot configuration variable to false. Having this, you -can still show it for each command just adding the --root option, -which is a flag for git diff-tree accepted by both commands. -With that, you should now be having some inkling of what git does, and -can explore on your own. -Most likely, you are not directly using the core -git Plumbing commands, but using Porcelain such as git add, git-rm -and git-commit. +changes. You can emulate git log, git log -p, etc. with a trivial +script that pipes the output of git rev-list to git diff-tree --stdin, +which was exactly how early versions of git log were implemented. Tagging a version -In git, there are two kinds of tags, a "light" one, and an "annotated tag". +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 @@ -448,7 +429,7 @@ particular state. You can, for example, do 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 +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 @@ -466,15 +447,15 @@ name for the state at that point. Copying repositories -git repositories are normally totally self-sufficient and relocatable. +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 +"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. -You can tell git to split the git internal information from +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 +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: @@ -490,13 +471,13 @@ history outside the project you created. -if you want to move or duplicate a git repository, you can do so. There +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 +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 @@ -505,7 +486,7 @@ So after you do a cp -a to create a new copy, you'll want t Note that the second point is true even across machines. You can -duplicate a remote git repository with any regular copy mechanism, be it +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' @@ -522,28 +503,28 @@ 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 +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 used to be 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. +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 +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 +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 +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 +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 @@ -554,7 +535,7 @@ older version of a checked out tree you may also need to add the -fgit 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 +$ git clone git://git.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. @@ -563,12 +544,12 @@ repository, and checked it out. Creating a new branch -Branches in git are really nothing more than pointers into the git +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 +point in the project history, and just writing the SHA-1 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, @@ -619,7 +600,7 @@ $ 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 +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 @@ -650,7 +631,7 @@ to resolve and what the merge is all about: 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 +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: Auto-merging hello @@ -675,7 +656,7 @@ message about your adventures in git merge-land. 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 +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. @@ -740,7 +721,7 @@ looks like, or run show-branch, which tells you this. 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 +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" @@ -753,26 +734,6 @@ 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 @@ -785,7 +746,7 @@ 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. +most efficient way to exchange Git objects between repositories. @@ -803,7 +764,7 @@ the remote machine via ssh. -git Native +Git Native @@ -833,8 +794,8 @@ tree object; it repeats this process until it gets all the necessary objects. Because of this behavior, 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 +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. @@ -945,7 +906,7 @@ file (the first tree goes to stage 1, the second to 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 +collapsed into stage 0, taking the SHA-1 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 @@ -1010,7 +971,7 @@ changes you made in your primary working tree are in good shape, update the public repository from it. This is often called pushing. This public repository could further be mirrored, and that is -how git repositories at kernel.org are managed. +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 @@ -1024,13 +985,13 @@ done only once. 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 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 +Then, make that directory into a Git repository by running git init, but this time, since its name is not the usual .git, we do things slightly differently: $ GIT_DIR=my-git.git git init @@ -1055,7 +1016,7 @@ there, run this command: 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 +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/ @@ -1063,9 +1024,9 @@ propagation to other publicly visible machines: Packing your repository Earlier, we saw that one file under .git/objects/??/ directory -is stored for each git object you create. This representation +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 +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 @@ -1107,20 +1068,20 @@ project from scratch), and then run git repack every once i 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. +unpacked in the destination. 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 +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 -link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation]. +http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation]. It should be stressed that this hierarchy is purely informal. -There is nothing fundamental in git that enforces the "chain of +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: @@ -1286,7 +1247,7 @@ Use git format-patch origin to prepare patches for e-mail 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 +have to worry. Git supports "shared public repository" style of cooperation you are probably more familiar with as well. See for the details. @@ -1294,7 +1255,7 @@ cooperation you are probably more familiar with as well. 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. +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 @@ -1371,7 +1332,7 @@ to follow, not easier. , , , -link:everyday.html[Everyday git], +, link:user-manual.html[The Git User's Manual] diff --git a/doc/source/en/TortoiseGit/git_doc/gitcredentials.xml b/doc/source/en/TortoiseGit/git_doc/gitcredentials.xml index 077826af2..e7506072f 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitcredentials.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitcredentials.xml @@ -8,7 +8,7 @@ NAME -gitcredentials - providing usernames and passwords to git +gitcredentials - providing usernames and passwords to Git SYNOPSIS @@ -20,12 +20,12 @@ git config credential.helper "$helper $options" Git will sometimes need credentials from the user in order to perform operations; for example, it may need to ask for a username and password in order to access a remote repository over HTTP. This manual describes -the mechanisms git uses to request these credentials, as well as some +the mechanisms Git uses to request these credentials, as well as some features to avoid inputting these credentials repeatedly. REQUESTING CREDENTIALS -Without any credential helpers defined, git will try the following +Without any credential helpers defined, Git will try the following strategies to ask the user for usernames and passwords: @@ -38,7 +38,7 @@ If the GIT_ASKPASS environment variable is set, the program -Otherwise, if the core.askpass configuration variable is set, its +Otherwise, if the core.askPass configuration variable is set, its value is used as above. @@ -76,7 +76,7 @@ Credential helpers to cache or store passwords, or to interact with for a password. It is generally configured by adding this to your config: [credential "https://example.com"] username = me -Credential helpers, on the other hand, are external programs from which git can +Credential helpers, on the other hand, are external programs from which Git can request both usernames and passwords; they typically interface with secure storage provided by the OS or other programs. To use a helper, you must first select one to use. Git currently @@ -108,7 +108,7 @@ store You may also have third-party helpers installed; search for credential-* in the output of git help -a, and consult the documentation of individual helpers. Once you have selected a helper, -you can tell git to use it by putting its name into the +you can tell Git to use it by putting its name into the credential.helper variable. @@ -126,22 +126,26 @@ Read its description. -Tell git to use it. +Tell Git to use it. $ git config --global credential.helper foo If there are multiple instances of the credential.helper configuration variable, each helper will be tried in turn, and may provide a username, -password, or nothing. Once git has acquired both a username and a +password, or nothing. Once Git has acquired both a username and a password, no more helpers will be tried. +If credential.helper is configured to the empty string, this resets +the helper list to empty (so you may override a helper set by a +lower-priority config file by configuring the empty-string helper, +followed by whatever set of helpers you would like). CREDENTIAL CONTEXTS Git considers each credential to have a context defined by a URL. This context is used to look up context-specific configuration, and is passed to any helpers, which may use it as an index into secure storage. -For instance, imagine we are accessing https://example.com/foo.git. When git +For instance, imagine we are accessing https://example.com/foo.git. When Git looks into a config file to see if a section matches this context, it will consider the two a match if the context is a more-specific subset of the pattern in the config file. For example, if you have this in your config file: @@ -152,10 +156,10 @@ the "pattern" URL does not care about the path component at all. However, this context would not match: [credential "https://kernel.org"] username = foo -because the hostnames differ. Nor would it match foo.example.com; git +because the hostnames differ. Nor would it match foo.example.com; Git compares hostnames exactly, without considering whether two hosts are part of the same domain. Likewise, a config entry for http://example.com would not -match: git compares the protocols exactly. +match: Git compares the protocols exactly. CONFIGURATION OPTIONS @@ -196,7 +200,7 @@ useHttpPath - By default, git does not consider the "path" component of an http URL + By default, Git does not consider the "path" component of an http URL to be worth matching via external helpers. This means that a credential stored for https://example.com/foo.git will also be used for https://example.com/bar.git. If you do want to distinguish these @@ -209,7 +213,7 @@ useHttpPath CUSTOM HELPERS You can write your own custom helpers to interface with any system in -which you keep credentials. See the documentation for git's +which you keep credentials. See the documentation for Git's link:technical/api-credentials.html[credentials API] for details. diff --git a/doc/source/en/TortoiseGit/git_doc/gitcvs-migration.xml b/doc/source/en/TortoiseGit/git_doc/gitcvs-migration.xml index bb5abbfd1..7311730a3 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitcvs-migration.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitcvs-migration.xml @@ -8,7 +8,7 @@ NAME -gitcvs-migration - git for CVS users +gitcvs-migration - Git for CVS users SYNOPSIS @@ -23,7 +23,7 @@ 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; this document explains how to do that. -Some basic familiarity with git is required. Having gone through +Some basic familiarity with Git is required. Having gone through and should be sufficient. @@ -63,7 +63,7 @@ other than master. Setting Up a Shared Repository -We assume you have already created a git repository for your project, +We assume you have already created a Git repository for your project, possibly created from scratch or from a tarball (see ), or imported from an already existing CVS repository (see the next section). @@ -78,7 +78,7 @@ $ git --bare fetch /home/alice/myproject master:master 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 . +users to do Git pushes and pulls; see . Put all the committers in the same group, and make the repository writable by that group: $ chgrp -R $group /pub/my-repo.git @@ -88,18 +88,18 @@ they create are writable and searchable by other group members. 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 +http://www.cobite.com/cvsps/">http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make sure it is in your path. Then cd to a checked out CVS working directory of the project you are interested in and run : $ git cvsimport -C <destination> <module> -This puts a git archive of the named CVS module in the directory +This puts a Git archive of the named CVS module in the directory <destination>, which will be created if necessary. 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 +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 @@ -118,20 +118,20 @@ incremental imports. points. You can use these, for example, to send all commits to the shared repository to a mailing list. See . You can enforce finer grained permissions using update hooks. See -link:howto/update-hook-example.txt[Controlling access to branches using +link:howto/update-hook-example.html[Controlling access to branches using update hooks]. -Providing CVS Access to a git Repository -It is also possible to provide true CVS access to a git repository, so +Providing CVS Access to a Git Repository +It is also possible to provide true CVS access to a Git repository, so that developers can still use CVS; see for details. Alternative Development Models CVS users are accustomed to giving a group of developers commit access to -a common repository. As we've seen, this is also possible with git. -However, the distributed nature of git allows other development models, +a common repository. As we've seen, this is also possible 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 @@ -151,7 +151,7 @@ repositories without the need for a central maintainer. , , , -link:everyday.html[Everyday Git], +, link:user-manual.html[The Git User's Manual] diff --git a/doc/source/en/TortoiseGit/git_doc/gitdiffcore.xml b/doc/source/en/TortoiseGit/git_doc/gitdiffcore.xml index da2e163dd..90147178f 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitdiffcore.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitdiffcore.xml @@ -121,7 +121,7 @@ it changes it to: 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 +and "0123456…" as their SHA-1 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 @@ -217,21 +217,30 @@ 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 "result" side and whose "origin" side have -different number of specified string. 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 +This transformation limits the set of filepairs to those that change +specified strings between the preimage and the postimage in a certain +way. -S<block of text> and -G<regular expression> options are used to +specify different ways these strings are sought. +"-S<block of text>" detects filepairs whose preimage and postimage +have different number of occurrences of the specified block of text. +By definition, it will not detect in-file moves. Also, when a +changeset moves a file wholesale without affecting the interesting +string, diffcore-rename kicks in as usual, and -S omits the filepair +(since the number of occurrences of that string didn't change in that +rename-detected filepair). When used with --pickaxe-regex, treat +the <block of text> as an extended POSIX regular expression to match, +instead of a literal string. +"-G<regular expression>" (mnemonic: grep) detects filepairs whose +textual diff has an added or a deleted line that matches the given +regular expression. This means that it will detect in-file (or what +rename-detection considers the same file) moves, which is noise. The +implementation runs diff twice and greps, and this can be quite +expensive. +When -S or -G are used without --pickaxe-all, only filepairs +that match their respective criterion are kept in the output. When +--pickaxe-all is used, if even one filepair matches their respective +criterion in a changeset, the entire changeset is kept. This behavior +is designed to make reviewing changes in the context of the whole changeset easier. @@ -243,7 +252,7 @@ changeset easier. 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 +As an example, a typical orderfile for the core Git probably would look like this: README Makefile diff --git a/doc/source/en/TortoiseGit/git_doc/giteveryday.xml b/doc/source/en/TortoiseGit/git_doc/giteveryday.xml new file mode 100644 index 000000000..7e1f2b099 --- /dev/null +++ b/doc/source/en/TortoiseGit/git_doc/giteveryday.xml @@ -0,0 +1,781 @@ + + + + + giteveryday(7) + +giteveryday(7) + + +NAME +giteveryday - A useful minimum set of commands for Everyday Git + + +SYNOPSIS +Everyday Git With 20 Commands Or So + + +DESCRIPTION +Git users can broadly be grouped into four categories for the purposes of +describing here a small set of useful command for everyday Git. + + + +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 + the Individual Developer (Participant) section as well. + + + + +People who play the Integrator role need to learn some + more commands in addition to the above. + + + + +Repository Administration commands are for system + administrators who are responsible for the care and feeding + of Git repositories. + + + + + +Individual Developer (Standalone)<anchor id="giteveryday(7)_STANDALONE" xreflabel="[STANDALONE]"/> +A standalone individual developer does not exchange patches with +other people, and works alone in a single repository, using the +following commands. + + + + to create a new repository. + + + + + to see what happened. + + + + + and to switch + branches. + + + + + to manage the index file. + + + + + and to see what + you are in the middle of doing. + + + + + to advance the current branch. + + + + + and (with + pathname parameters) to undo changes. + + + + + to merge between local branches. + + + + + to maintain topic branches. + + + + + to mark a known point. + + + +
+Examples + + + +Use a tarball as a starting point for a new repository. + + +$ tar zxf frotz.tar.gz +$ cd frotz +$ git init +$ git add . +$ git commit -m "import of frotz source tree." +$ git tag v2.43 + + + +add everything under the current directory. + + + + +make a lightweight, unannotated tag. + + + + + + + +Create a topic branch and develop. + + +$ git checkout -b alsa-audio +$ edit/compile/test +$ git checkout -- curses/ux_audio_oss.c +$ git add curses/ux_audio_alsa.c +$ edit/compile/test +$ git diff HEAD +$ git commit -a -s +$ edit/compile/test +$ git diff HEAD^ +$ git commit -a --amend +$ git checkout master +$ git merge alsa-audio +$ git log --since='3 days ago' +$ git log v2.43.. curses/ + + + +create a new topic branch. + + + + +revert your botched changes in curses/ux_audio_oss.c. + + + + +you need to tell Git if you added a new file; removal and +modification will be caught if you do git commit -a later. + + + + +to see what changes you are committing. + + + + +commit everything, as you have tested, with your sign-off. + + + + +look at all your changes including the previous commit. + + + + +amend the previous commit, adding all your new changes, +using your original message. + + + + +switch to the master branch. + + + + +merge a topic branch into your master branch. + + + + +review commit logs; other forms to limit output can be +combined and include -10 (to show up to 10 commits), +--until=2005-12-10, etc. + + + + +view only the changes that touch what's in curses/ +directory, since v2.43 tag. + + + + + + +
+ + +Individual Developer (Participant)<anchor id="giteveryday(7)_PARTICIPANT" xreflabel="[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. + + + + from the upstream to prime your local + repository. + + + + + and from "origin" + to keep up-to-date with the upstream. + + + + + to shared repository, if you adopt CVS + style shared repository workflow. + + + + + to prepare e-mail submission, if + you adopt Linux kernel-style public forum workflow. + + + + + to send your e-mail submission without + corruption by your MUA. + + + + + to create a summary of changes + for your upstream to pull. + + + +
+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 +$ git checkout -b mine master +$ edit/compile/test; git commit -a -s +$ git format-patch master +$ git send-email --to="person <email@example.com>" 00*.patch +$ git checkout master +$ git pull +$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 +$ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git +$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL +$ git reset --hard ORIG_HEAD +$ git gc + + + +checkout a new branch mine from master. + + + + +repeat as needed. + + + + +extract patches from your branch, relative to master, + + + + +and email them. + + + + +return to master, ready to see what's new + + + + +git pull fetches from origin by default and merges into the +current branch. + + + + +immediately after pulling, look at the changes done upstream +since last time we checked, only in the +area we are interested in. + + + + +check the branch names in an external repository (if not known). + + + + +fetch from a specific branch ALL from a specific repository +and merge it. + + + + +revert the pull. + + + + +garbage collect leftover objects from reverted pull. + + + + + + + +Push into another repository. + + +satellite$ git clone mothership:frotz frotz +satellite$ cd frotz +satellite$ git config --get-regexp '^(remote|branch)\.' +remote.origin.url mothership:frotz +remote.origin.fetch refs/heads/*:refs/remotes/origin/* +branch.master.remote origin +branch.master.merge refs/heads/master +satellite$ git config remote.origin.push \ + +refs/heads/*:refs/remotes/satellite/* +satellite$ edit/compile/test/commit +satellite$ git push origin + +mothership$ cd frotz +mothership$ git checkout master +mothership$ git merge satellite/master + + + +mothership machine has a frotz repository under your home +directory; clone from it to start a repository on the satellite +machine. + + + + +clone sets these configuration variables by default. +It arranges git pull to fetch and store the branches of mothership +machine to local remotes/origin/* remote-tracking branches. + + + + +arrange git push to push all local branches to +their corresponding branch of the mothership machine. + + + + +push will stash all our work away on remotes/satellite/* +remote-tracking branches on the mothership machine. You could use this +as a back-up method. Likewise, you can pretend that mothership +"fetched" from you (useful when access is one sided). + + + + +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 +$ edit/compile/test; git commit -a +$ git checkout master +$ git cherry-pick v2.6.14..private2.6.14 + + + +create a private branch based on a well known (but somewhat behind) +tag. + + + + +forward port all changes in private2.6.14 branch to master branch +without a formal "merging". Or longhand +git format-patch -k -m --stdout v2.6.14..private2.6.14 | + git am -3 -k + + + + + + +An alternate participant submission mechanism is using the +git request-pull or pull-request mechanisms (e.g as used on +GitHub (www.github.com) to notify your upstream of your +contribution. +
+ + +Integrator<anchor id="giteveryday(7)_INTEGRATOR" xreflabel="[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. +This section can also be used by those who respond to git +request-pull or pull-request on GitHub (www.github.com) to +integrate the work of others into their history. An sub-area +lieutenant for a repository will act both as a participant and +as an integrator. + + + + to apply patches e-mailed in from your + contributors. + + + + + to merge from your trusted lieutenants. + + + + + to prepare and send suggested + alternative to contributors. + + + + + to undo botched commits. + + + + + to publish the bleeding edge. + + + +
+Examples + + + +A typical integrator's Git day. + + +$ git status +$ git branch --no-merged master +$ mailx +& s 2 3 4 5 ./+to-apply +& s 7 8 ./+hold-linus +& q +$ git checkout -b topic/one master +$ git am -3 -i -s ./+to-apply +$ compile/test +$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus +$ git checkout topic/one && git rebase master +$ git checkout pu && git reset --hard next +$ git merge topic/one topic/two && git merge hold/linus +$ git checkout maint +$ git cherry-pick master~4 +$ compile/test +$ git tag -s -m "GIT 0.99.9x" v0.99.9x +$ git fetch ko && for branch in master maint next pu + do + git show-branch ko/$branch $branch + done +$ git push --follow-tags ko + + + +see what you were in the middle of doing, if anything. + + + + +see which branches haven't been merged into master yet. +Likewise for any other integration branches e.g. maint, next +and pu (potential updates). + + + + +read mails, save ones that are applicable, and save others +that are not quite ready (other mail readers are available). + + + + +apply them, interactively, with your sign-offs. + + + + +create topic branch as needed and apply, again with sign-offs. + + + + +rebase internal topic branch that has not been merged to the +master or exposed as a part of a stable branch. + + + + +restart pu every time from the next. + + + + +and bundle topic branches still cooking. + + + + +backport a critical fix. + + + + +create a signed tag. + + + + +make sure master was not accidentally rewound beyond that +already pushed out. ko shorthand points at the Git maintainer's +repository at kernel.org, and looks like this: + +(in .git/config) +[remote "ko"] + url = kernel.org:/pub/scm/git/git.git + fetch = refs/heads/*:refs/remotes/ko/* + push = refs/heads/master + push = refs/heads/next + push = +refs/heads/pu + push = refs/heads/maint + + + +In the output from git show-branch, master should have +everything ko/master has, and next should have +everything ko/next has, etc. + + + + +push out the bleeding edge, together with new tags that point +into the pushed history. + + + + + + +
+ + +Repository Administration<anchor id="giteveryday(7)_ADMINISTRATION" xreflabel="[ADMINISTRATION]"/> +A repository administrator uses the following tools to set up +and maintain access to the repository by developers. + + + + to allow anonymous download from + repository. + + + + + can be used as a restricted login shell + for shared central repository users. + + + + + provides a server side implementation + of Git-over-HTTP ("Smart http") allowing both fetch and push services. + + + + + provides a web front-end to Git repositories, + which can be set-up using the script. + + + +link:howto/update-hook-example.html[update hook howto] has a good +example of managing a shared central repository. +In addition there are a number of other widely deployed hosting, browsing +and reviewing solutions such as: + + + +gitolite, gerrit code review, cgit and others. + + + +
+Examples + + + +We assume the following in /etc/services + + +$ grep 9418 /etc/services +git 9418/tcp # Git Version Control System + + + + +Run git-daemon to serve /pub/scm from inetd. + + +$ grep git /etc/inetd.conf +git stream tcp nowait nobody \ + /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm +The actual configuration line should be on one line. + + + + +Run git-daemon to serve /pub/scm from xinetd. + + +$ cat /etc/xinetd.d/git-daemon +# default: off +# description: The Git server offers access to Git repositories +service git +{ + disable = no + type = UNLISTED + port = 9418 + socket_type = stream + wait = no + user = nobody + server = /usr/bin/git-daemon + server_args = --inetd --export-all --base-path=/pub/scm + log_on_failure += USERID +} +Check your xinetd(8) documentation and setup, this is from a Fedora system. +Others might be different. + + + + +Give push/pull only access to developers using git-over-ssh. + + + +e.g. those using: +$ git push/pull ssh://host.xz/pub/scm/project + +$ grep git /etc/passwd +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 +/usr/bin/git-shell + + + +log-in shell is set to /usr/bin/git-shell, which does not +allow anything but git push and git pull. The users require +ssh access to the machine. + + + + +in many distributions /etc/shells needs to list what is used +as the login shell. + + + + + + + +CVS-style shared repository. + + +$ grep git /etc/group +git:x:9418:alice,bob,cindy,david +$ cd /home/devo.git +$ ls -l + 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 + -r-xr-xr-x 1 david git 3536 Dec 4 22:40 update +$ cat info/allowed-users +refs/heads/master alice\|cindy +refs/heads/doc-update bob +refs/tags/v[0-9]* david + + + +place the developers into the same git group. + + + + +and make the shared repository writable by the group. + + + + +use update-hook example by Carl from Documentation/howto/ +for branch policy control. + + + + +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. + + + + + + +
+ + +GIT +Part of the suite + + diff --git a/doc/source/en/TortoiseGit/git_doc/gitglossary.xml b/doc/source/en/TortoiseGit/git_doc/gitglossary.xml index 9df529941..37243baab 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitglossary.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitglossary.xml @@ -8,7 +8,7 @@ NAME -gitglossary - A GIT Glossary +gitglossary - A Git Glossary SYNOPSIS @@ -25,7 +25,7 @@ Via the alternates mechanism, a repository can inherit part of its object database - from another object database, which is called "alternate". + from another object database, which is called an "alternate". @@ -38,7 +38,7 @@ A bare repository is normally an appropriately named directory with a .git suffix that does not have a locally checked-out copy of any of the files under - revision control. That is, all of the git + revision control. That is, all of the Git administrative and control files that would normally be present in the hidden .git sub-directory are directly present in the repository.git directory instead, @@ -67,7 +67,7 @@ commit on a branch is referred to as the tip of that branch. The tip of the branch is referenced by a branch head, which moves forward as additional development - is done on the branch. A single git + is done on the branch. A single Git repository can track an arbitrary number of branches, but your working tree is associated with just one of them (the "current" or "checked out" @@ -103,9 +103,9 @@ - BitKeeper/cvsps speak for "commit". Since git does not + BitKeeper/cvsps speak for "commit". Since Git does not store changes, but states, it really does not make sense to use the term - "changesets" with git. + "changesets" with Git. @@ -132,7 +132,7 @@ In SCM jargon, "cherry pick" means to choose a subset of changes out of a series of changes (typically commits) and record them - as a new series of changes on top of a different codebase. In GIT, this is + as a new series of changes on top of a different codebase. In Git, this is performed by the "git cherry-pick" command to extract the change introduced by an existing commit and to record it based on the tip of the current branch as a new commit. @@ -158,14 +158,14 @@ As a noun: A single point in the - git history; the entire history of a project is represented as a + Git history; the entire history of a project is represented as a set of interrelated commits. The word "commit" is often - used by git in the same places other revision control systems + used by Git in the same places other revision control systems use the words "revision" or "version". Also used as a short hand for commit object. As a verb: The action of storing a new snapshot of the project's -state in the git history, by creating a new commit representing the current +state in the Git history, by creating a new commit representing the current state of the index and advancing HEAD to point at the new commit. @@ -186,11 +186,30 @@ to point at the new commit. -core git +commit-ish (also committish) - Fundamental data structures and utilities of git. Exposes only limited + A commit object or an + object that can be recursively dereferenced to + a commit object. + The following are all commit-ishes: + a commit object, + a tag object that points to a commit + object, + a tag object that points to a tag object that points to a + commit object, + etc. + + + + + +core Git + + + + Fundamental data structures and utilities of Git. Exposes only limited source code management tools. @@ -228,20 +247,22 @@ to point at the new commit. Normally the HEAD stores the name of a - branch. However, git also allows you to check out - an arbitrary commit that isn't necessarily the tip of any - particular branch. In this case HEAD is said to be "detached". - - - - - -dircache - - - - You are waaaaay behind. See index. + branch, and commands that operate on the + history HEAD represents operate on the history leading to the + tip of the branch the HEAD points at. However, Git also + allows you to check out an arbitrary + commit that isn't necessarily the tip of any + particular branch. The HEAD in such a state is called + "detached". +Note that commands that operate on the history of the current branch +(e.g. git commit to build a new history on top of it) still work +while the HEAD is detached. They update the HEAD to point at the tip +of the updated history without affecting any branch. Commands that +update or inquire information about the current branch (e.g. git +branch --set-upstream-to that sets what remote-tracking branch the +current branch integrates with) obviously do not work, as there is no +(real) current branch to ask about in this state. @@ -268,18 +289,6 @@ to point at the new commit. -ent - - - - Favorite synonym to "tree-ish" by some total geeks. See - http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth - explanation. Avoid this term, not to confuse people. - - - - - evil merge @@ -326,15 +335,15 @@ to point at the new commit. - Linus Torvalds originally designed git to be a user space file system, + Linus Torvalds originally designed Git to be a user space file system, i.e. the infrastructure to hold files and directories. That ensured the - efficiency and speed of git. + efficiency and speed of Git. -git archive +Git archive @@ -344,16 +353,30 @@ to point at the new commit. +gitfile + + + + A plain file .git at the root of a working tree that + points at the directory that is the real repository. + + + + + grafts Grafts enables two otherwise different lines of development to be joined together by recording fake ancestry information for commits. This way - you can make git pretend the set of parents a commit has + you can make Git pretend the set of parents a commit has is different from what was recorded when the commit was created. Configured via the .git/info/grafts file. +Note that the grafts mechanism is outdated and can lead to problems +transferring objects between repositories; see +for a more flexible and robust system to do the same thing. @@ -362,7 +385,7 @@ to point at the new commit. - In git's context, synonym to object name. + In Git's context, synonym for object name. @@ -409,14 +432,14 @@ to point at the new commit. - During the normal execution of several git commands, call-outs are made + During the normal execution of several Git commands, call-outs are made to optional scripts that allow a developer to add functionality or checking. Typically, the hooks allow for a command to be pre-verified and potentially aborted, and allow for a post-notification after the operation is done. The hook scripts are found in the $GIT_DIR/hooks/ directory, and are enabled by simply removing the .sample suffix from the filename. In earlier versions - of git you had to make them executable. + of Git you had to make them executable. @@ -454,7 +477,7 @@ to point at the new commit. The default development branch. Whenever you - create a git repository, a branch named + create a Git repository, a branch named "master" is created, and becomes the active branch. In most cases, this contains the local development, though that is purely by convention and is not required. @@ -494,8 +517,8 @@ This commit is referred to as a "merge commit", or sometimes just a - The unit of storage in git. It is uniquely identified by the - SHA1 of its contents. Consequently, an + The unit of storage in Git. It is uniquely identified by the + SHA-1 of its contents. Consequently, an object can not be changed. @@ -528,10 +551,9 @@ This commit is referred to as a "merge commit", or sometimes just a - The unique identifier of an object. The hash - of the object's contents using the Secure Hash Algorithm - 1 and usually represented by the 40 character hexadecimal encoding of - the hash of the object. + The unique identifier of an object. The + object name is usually represented by a 40 character + hexadecimal string. Also colloquially called SHA-1. @@ -554,8 +576,7 @@ This commit is referred to as a "merge commit", or sometimes just a - To merge more than two branches. Also denotes an - intelligent predator. + To merge more than two branches. @@ -568,7 +589,7 @@ This commit is referred to as a "merge commit", or sometimes just a The default upstream repository. Most projects have at least one upstream project which they track. By default origin is used for that purpose. New upstream updates - will be fetched into remote remote-tracking branches named + will be fetched into remote-tracking branches named origin/name-of-upstream-branch, which you can see using git branch -r. @@ -603,7 +624,7 @@ This commit is referred to as a "merge commit", or sometimes just a - Pattern used to specify paths. + Pattern used to limit paths in Git commands. Pathspecs are used on the command line of "git ls-files", "git ls-tree", "git add", "git grep", "git diff", "git checkout", @@ -632,43 +653,121 @@ the rest of the pathspec is a pattern for the remainder prefix will be matched against that pattern using fnmatch(3); in particular, * and ? can match directory separators. + + For example, Documentation/*.jpg will match all .jpg files in the Documentation subtree, including Documentation/chapter_1/figure_1.jpg. - - A pathspec that begins with a colon : has special meaning. In the short form, the leading colon : is followed by zero or more "magic signature" letters (which optionally is terminated by another colon :), -and the remainder is the pattern to match against the path. The optional -colon that terminates the "magic signature" can be omitted if the pattern -begins with a character that cannot be a "magic signature" and is not a -colon. +and the remainder is the pattern to match against the path. +The "magic signature" consists of ASCII symbols that are neither +alphanumeric, glob, regex special characters nor colon. +The optional colon that terminates the "magic signature" can be +omitted if the pattern begins with a character that does not belong to +"magic signature" symbol set and is not a colon. In the long form, the leading colon : is followed by a open parenthesis (, a comma-separated list of zero or more "magic words", and a close parentheses ), and the remainder is the pattern to match against the path. -The "magic signature" consists of an ASCII symbol that is not -alphanumeric. +A pathspec with only a colon means "there is no pathspec". This form +should not be combined with other pathspec. -top / +top + + + + The magic word top (magic signature: /) makes the pattern + match from the root of the working tree, even when you are + running the command from inside a subdirectory. + + + + + +literal - The magic word top (mnemonic: /) makes the pattern match - from the root of the working tree, even when you are running - the command from inside a subdirectory. + Wildcards in the pattern such as * or ? are treated + as literal characters. + + + + + +icase + + + + Case insensitive match. + + + + + +glob + + + + Git treats the pattern as a shell glob suitable for + consumption by fnmatch(3) with the FNM_PATHNAME flag: + wildcards in the pattern will not match a / in the pathname. + For example, "Documentation/*.html" matches + "Documentation/git.html" but not "Documentation/ppc/ppc.html" + or "tools/perf/Documentation/perf.html". + +Two consecutive asterisks ("**") in patterns matched against +full pathname may have special meaning: + + + +A leading "**" followed by a slash means match in all + directories. For example, "**/foo" matches file or directory + "foo" anywhere, the same as pattern "foo". "**/foo/bar" + matches file or directory "bar" anywhere that is directly + under directory "foo". + + + + +A trailing "/**" matches everything inside. For example, + "abc/**" matches all files inside directory "abc", relative + to the location of the .gitignore file, with infinite depth. + + + + +A slash followed by two consecutive asterisks then a slash + matches zero or more directories. For example, "a/**/b" + matches "a/b", "a/x/b", "a/x/y/b" and so on. + + + + +Other consecutive asterisks are considered invalid. + +Glob magic is incompatible with literal magic. + + + + + + +exclude + + + + After a path matches any non-exclude pathspec, it will be run + through all exclude pathspec (magic signature: !). If it + matches, the path is ignored. -Currently only the slash / is recognized as the "magic signature", -but it is envisioned that we will support more types of magic in later -versions of git. -A pathspec with only a colon means "there is no pathspec". This form -should not be combined with other pathspec. @@ -703,7 +802,7 @@ should not be combined with other pathspec. - Cute name for core git. + Cute name for core Git. @@ -714,14 +813,50 @@ should not be combined with other pathspec. Cute name for programs and program suites depending on - core git, presenting a high level access to - core git. Porcelains expose more of a SCM + core Git, presenting a high level access to + core Git. Porcelains expose more of a SCM interface than the plumbing. +per-worktree ref + + + + Refs that are per-worktree, rather than + global. This is presently only HEAD and any refs + that start with refs/bisect/, but might later include other + unusual refs. + + + + + +pseudoref + + + + Pseudorefs are a class of files under $GIT_DIR which behave + like refs for the purposes of rev-parse, but which are treated + specially by git. Pseudorefs both have names that are all-caps, + and always start with a line consisting of a + SHA-1 followed by whitespace. So, HEAD is not a + pseudoref, because it is sometimes a symbolic ref. They might + optionally contain some additional data. MERGE_HEAD and + CHERRY_PICK_HEAD are examples. Unlike + per-worktree refs, these files cannot + be symbolic refs, and never have reflogs. They also cannot be + updated through the normal ref update machinery. Instead, + they are updated by directly writing to the files. However, + they can be read as if they were refs, so git rev-parse + MERGE_HEAD will work. + + + + + pull @@ -785,11 +920,19 @@ should not be combined with other pathspec. - A 40-byte hex representation of a SHA1 or a name that - denotes a particular object. They may be stored in - a file under $GIT_DIR/refs/ directory, or - in the $GIT_DIR/packed-refs file. + A name that begins with refs/ (e.g. refs/heads/master) + that points to an object name or another + ref (the latter is called a symbolic ref). + For convenience, a ref can sometimes be abbreviated when used + as an argument to a Git command; see + for details. + Refs are stored in the repository. +The ref namespace is hierarchical. +Different subhierarchies are used for different purposes (e.g. the +refs/heads/ hierarchy is used to represent local branches). +There are a few special-purpose refs that do not begin with refs/. +The most notable example is HEAD. @@ -813,15 +956,19 @@ should not be combined with other pathspec. A "refspec" is used by fetch and push to describe the mapping between remote - ref and local ref. They are combined with a colon in - the format <src>:<dst>, preceded by an optional plus sign, +. - For example: git fetch $URL - refs/heads/master:refs/heads/origin means "grab the master - branch head from the $URL and store - it as my origin branch head". And git push - $URL refs/heads/master:refs/heads/to-upstream means "publish my - master branch head as to-upstream branch at $URL". See also - . + ref and local ref. + + + + + +remote repository + + + + A repository which is used to track the same + project but resides somewhere else. To communicate with remotes, + see fetch or push. @@ -831,12 +978,13 @@ should not be combined with other pathspec. - A regular git branch that is used to follow changes from - another repository. A remote-tracking - branch should not contain direct modifications or have local commits - made to it. A remote-tracking branch can usually be - identified as the right-hand-side ref in a Pull: - refspec. + A ref that is used to follow changes from another + repository. It typically looks like + refs/remotes/foo/bar (indicating that it tracks a branch named + bar in a remote named foo), and matches the right-hand-side of + a configured fetch refspec. A remote-tracking + branch should not contain direct modifications or have local + commits made to it. @@ -872,9 +1020,7 @@ should not be combined with other pathspec. - A particular state of files and directories which was stored in the - object database. It is referenced by a - commit object. + Synonym for commit (the noun). @@ -901,11 +1047,24 @@ should not be combined with other pathspec. -SHA1 +SHA-1 - Synonym for object name. + "Secure Hash Algorithm 1"; a cryptographic hash function. + In the context of Git used as a synonym for object name. + + + + + +shallow clone + + + + Mostly a synonym to shallow repository + but the phrase makes it more explicit that it was created by + running git clone --depth=... command. @@ -917,7 +1076,7 @@ should not be combined with other pathspec. A shallow repository has an incomplete history some of whose commits have parents cauterized away (in other - words, git is told to pretend that these commits do not have the + words, Git is told to pretend that these commits do not have the parents, even though they are recorded in the commit object). This is sometimes useful when you are interested only in the recent history of a project even though the real history recorded in the upstream is much larger. A shallow repository @@ -928,11 +1087,36 @@ should not be combined with other pathspec. +submodule + + + + A repository that holds the history of a + separate project inside another repository (the latter of + which is called superproject). + + + + + +superproject + + + + A repository that references repositories + of other projects in its working tree as submodules. + The superproject knows about the names of (but does not hold + copies of) commit objects of the contained submodules. + + + + + symref - Symbolic reference: instead of containing the SHA1 + Symbolic reference: instead of containing the SHA-1 id itself, it is of the format ref: refs/some/thing and when referenced, it recursively dereferences to this reference. HEAD is a prime example of a symref. Symbolic @@ -951,9 +1135,9 @@ should not be combined with other pathspec. object of an arbitrary type (typically a tag points to either a tag or a commit object). In contrast to a head, a tag is not updated by - the commit command. A git tag has nothing to do with a Lisp + the commit command. A Git tag has nothing to do with a Lisp tag (which would be called an object type - in git's context). A tag is most typically used to mark a particular + in Git's context). A tag is most typically used to mark a particular point in the commit ancestry chain. @@ -977,7 +1161,7 @@ should not be combined with other pathspec. - A regular git branch that is used by a developer to + A regular Git branch that is used by a developer to identify a conceptual line of development. Since branches are very easy and inexpensive, it is often desirable to have several small branches that each contain very well defined concepts or small incremental yet @@ -1010,11 +1194,22 @@ should not be combined with other pathspec. -tree-ish +tree-ish (also treeish) - A ref pointing to either a commit object, a tree object, or a tag object pointing to a tag or commit or tree object. + A tree object or an object + that can be recursively dereferenced to a tree object. + Dereferencing a commit object yields the + tree object corresponding to the revision's + top directory. + The following are all tree-ishes: + a commit-ish, + a tree object, + a tag object that points to a tree object, + a tag object that points to a tag object that points to a tree + object, + etc. @@ -1072,7 +1267,7 @@ should not be combined with other pathspec. , , , -link:everyday.html[Everyday git], +, link:user-manual.html[The Git User's Manual] diff --git a/doc/source/en/TortoiseGit/git_doc/githooks.xml b/doc/source/en/TortoiseGit/git_doc/githooks.xml index eceadfdc6..2d094bff3 100644 --- a/doc/source/en/TortoiseGit/git_doc/githooks.xml +++ b/doc/source/en/TortoiseGit/git_doc/githooks.xml @@ -8,7 +8,7 @@ NAME -githooks - Hooks used by git +githooks - Hooks used by Git SYNOPSIS @@ -85,13 +85,13 @@ given); template (if a -t option was g configuration option commit.template is set); merge (if the commit is a merge or a .git/MERGE_MSG file exists); squash (if a .git/SQUASH_MSG file exists); or commit, followed by -a commit SHA1 (if a -c, -C or --amend option was given). +a commit SHA-1 (if a -c, -C or --amend option was given). If the exit status is non-zero, git commit will abort. The purpose of the hook is to edit the message file in place, and it is not suppressed by the --no-verify option. A non-zero exit means a failure of the hook and aborts the commit. It should not be used as replacement for pre-commit hook. -The sample prepare-commit-msg hook that comes with git comments +The sample prepare-commit-msg hook that comes with Git comments out the Conflicts: part of a merge's commit message.
@@ -117,8 +117,11 @@ the outcome of git commit.
pre-rebase -This hook is called by git rebase and can be used to prevent a branch -from getting rebased. +This hook is called by git rebase and can be used to prevent a +branch from getting rebased. The hook may be called with one or +two parameters. The first parameter is the upstream from which +the series was forked. The second parameter is the branch being +rebased, and is not set when rebasing the current branch.
post-checkout @@ -144,9 +147,31 @@ This hook cannot affect the outcome of git merge and is not if the merge failed due to conflicts. This hook can be used in conjunction with a corresponding pre-commit hook to save and restore any form of metadata associated with the working tree -(eg: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl +(e.g.: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl for an example of how to do this.
+
+pre-push +This hook is called by git push and can be used to prevent a push from taking +place. The hook is called with two parameters which provide the name and +location of the destination remote, if a named remote is not being used both +values will be the same. +Information about what is to be pushed is provided on the hook's standard +input with lines of the form: +<local ref> SP <local sha1> SP <remote ref> SP <remote sha1> LF +For instance, if the command git push origin master:foreign were run the +hook would receive a line like the following: +refs/heads/master 67890 refs/heads/foreign 12345 +although the full, 40-character SHA-1s would be supplied. If the foreign ref +does not yet exist the <remote SHA-1> will be 40 0. If a ref is to be +deleted, the <local ref> will be supplied as (delete) and the <local +SHA-1> will be 40 0. If the local commit was specified by something other +than a name which could be expanded (such as HEAD~, or a SHA-1) it will be +supplied as it was originally given. +If this hook exits with a non-zero status, git push will abort without +pushing anything. Information about why the push is rejected may be sent +to the user by writing to standard error. +
pre-receive This hook is invoked by git-receive-pack on the remote repository, @@ -191,7 +216,7 @@ the old object name stored in the ref, -and the new objectname to be stored in the ref. +and the new object name to be stored in the ref. @@ -236,7 +261,7 @@ names. for the user. The default post-receive hook is empty, but there is a sample script post-receive-email provided in the contrib/hooks -directory in git distribution, which implements sending commit +directory in Git distribution, which implements sending commit emails.
@@ -258,12 +283,38 @@ them. When enabled, the default post-update hook runs git update-server-info to keep the information used by dumb transports (e.g., HTTP) up-to-date. If you are publishing -a git repository that is accessible via HTTP, you should +a Git repository that is accessible via HTTP, you should probably enable this hook. Both standard output and standard error output are forwarded to git send-pack on the other end, so you can simply echo messages for the user.
+
+push-to-checkout +This hook is invoked by git-receive-pack on the remote repository, +which happens when a git push is done on a local repository, when +the push tries to update the branch that is currently checked out +and the receive.denyCurrentBranch configuration variable is set to +updateInstead. Such a push by default is refused if the working +tree and the index of the remote repository has any difference from +the currently checked out commit; when both the working tree and the +index match the current commit, they are updated to match the newly +pushed tip of the branch. This hook is to be used to override the +default behaviour. +The hook receives the commit with which the tip of the current +branch is going to be updated. It can exit with a non-zero status +to refuse the push (when it does so, it must not modify the index or +the working tree). Or it can make any necessary changes to the +working tree and to the index to bring them to the desired state +when the tip of the current branch is updated to the new commit, and +exit with a zero status. +For example, the hook can simply run git read-tree -u -m HEAD "$1" +in order to emulate git fetch that is run in the reverse direction +with git push, as the two-tree form of read-tree -u -m is +essentially the same as git checkout that switches branches while +keeping the local changes in the working tree that do not interfere +with the difference between the branches. +
pre-auto-gc This hook is invoked by git gc --auto. It takes no parameter, and @@ -284,7 +335,7 @@ format preceding SP is also omitted. Currently, no commands pass any extra-info. The hook always runs after the automatic note copying (see -"notes.rewrite.<command>" in linkgit:git-config.txt) has happened, and +"notes.rewrite.<command>" in ) has happened, and thus has access to these notes. The following command-specific comments apply: diff --git a/doc/source/en/TortoiseGit/git_doc/gitignore.xml b/doc/source/en/TortoiseGit/git_doc/gitignore.xml index 48f393ed1..1cf23aa49 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitignore.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitignore.xml @@ -12,16 +12,16 @@ SYNOPSIS -$GIT_DIR/info/exclude, .gitignore +$HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore DESCRIPTION A gitignore file specifies intentionally untracked files that -git should ignore. -Files already tracked by git are not affected; see the NOTES +Git should ignore. +Files already tracked by Git are not affected; see the NOTES below for details. Each line in a gitignore file specifies a pattern. -When deciding whether to ignore a path, git normally checks +When deciding whether to ignore a path, Git normally checks gitignore patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of precedence, the last matching pattern decides the outcome): @@ -52,7 +52,7 @@ Patterns read from $GIT_DIR/info/exclude. Patterns read from the file specified by the configuration - variable core.excludesfile. + variable core.excludesFile. @@ -77,19 +77,19 @@ Patterns which are -Patterns which a user wants git to +Patterns which a user wants Git to ignore in all situations (e.g., backup or temporary files generated by the user's editor of choice) generally go into a file specified by - core.excludesfile in the user's ~/.gitconfig. Its default value is + core.excludesFile in the user's ~/.gitconfig. Its default value is $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/ignore is used instead. -The underlying git plumbing tools, such as +The underlying Git plumbing tools, such as git ls-files and git read-tree, read gitignore patterns specified by command-line options, or from -files specified by command-line options. Higher-level git +files specified by command-line options. Higher-level Git tools, such as git status and git add, use patterns from the sources specified above. @@ -111,10 +111,18 @@ A line starting with # serves as a comment. +Trailing spaces are ignored unless they are quoted with backslash + ("\"). + + + + An optional prefix "!" which negates the pattern; any matching file excluded by a previous pattern will become - included again. If a negated pattern matches, this will - override lower precedence patterns sources. + included again. It is not possible to re-include a file if a parent + directory of that file is excluded. Git doesn't list excluded + directories for performance reasons, so any patterns on contained + files have no effect, no matter where they are defined. Put a backslash ("\") in front of the first "!" for patterns that begin with a literal "!", for example, "\!important!.txt". @@ -126,12 +134,12 @@ If the pattern ends with a slash, it is removed for the a match with a directory. In other words, foo/ will match a directory foo and paths underneath it, but will not match a regular file or a symbolic link foo (this is consistent - with the way how pathspec works in general in git). + with the way how pathspec works in general in Git). -If the pattern does not contain a slash /, git treats it as +If the pattern does not contain a slash /, Git treats it as a shell glob pattern and checks for a match against the pathname relative to the location of the .gitignore file (relative to the toplevel of the work tree if not from a @@ -140,7 +148,7 @@ If the pattern does not contain a slash /, git treats it as -Otherwise, git treats the pattern as a shell glob suitable +Otherwise, Git treats the pattern as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. For example, "Documentation/*.html" matches @@ -156,13 +164,43 @@ A leading slash matches the beginning of the pathname. +Two consecutive asterisks ("**") in patterns matched against +full pathname may have special meaning: + + + +A leading "**" followed by a slash means match in all + directories. For example, "**/foo" matches file or directory + "foo" anywhere, the same as pattern "foo". "**/foo/bar" + matches file or directory "bar" anywhere that is directly + under directory "foo". + + + + +A trailing "/**" matches everything inside. For example, + "abc/**" matches all files inside directory "abc", relative + to the location of the .gitignore file, with infinite depth. + + + + +A slash followed by two consecutive asterisks then a slash + matches zero or more directories. For example, "a/**/b" + matches "a/b", "a/x/b", "a/x/y/b" and so on. + + + + +Other consecutive asterisks are considered invalid. + + + NOTES The purpose of gitignore files is to ensure that certain files -not tracked by git remain untracked. -To ignore uncommitted changes in a file that is already tracked, -use git update-index --assume-unchanged. +not tracked by Git remain untracked. To stop tracking a file that is currently tracked, use git rm --cached. @@ -198,13 +236,23 @@ use git update-index --assume-unchanged. $ ls arch/foo/kernel/vm* arch/foo/kernel/vmlinux.lds.S $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore -The second .gitignore prevents git from ignoring +The second .gitignore prevents Git from ignoring arch/foo/kernel/vmlinux.lds.S. +Example to exclude everything except a specific directory foo/bar +(note the /* - without the slash, the wildcard would also exclude +everything within foo/bar): + $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar SEE ALSO -, , - +, +, + GIT diff --git a/doc/source/en/TortoiseGit/git_doc/gitk.xml b/doc/source/en/TortoiseGit/git_doc/gitk.xml index 06cd55887..e530ca2d2 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitk.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitk.xml @@ -8,12 +8,12 @@ NAME -gitk - The git repository browser +gitk - The Git repository browser SYNOPSIS
-gitk [<option>…] [<revs>] [--] [<path>…] +gitk [<options>] [<revision range>] [--] [<path>…]
@@ -21,27 +21,49 @@ Displays changes in a repository or a selected set of commits. This includes visualizing the commit graph, showing information related to each commit, and the files in the trees of each revision. -Historically, gitk was the first repository browser. It's written in tcl/tk -and started off in a separate repository but was later merged into the main -git repository. OPTIONS -To control which revisions to show, the command takes options applicable to -the git rev-list command (see ). -This manual page describes only the most -frequently used options. +To control which revisions to show, gitk supports most options +applicable to the git rev-list command. It also supports a few +options applicable to the git diff-* commands to control how the +changes each commit introduces are shown. Finally, it supports some +gitk-specific options. +gitk generally only understands options with arguments in the +sticked form (see ) due to limitations in the +command-line parser. +
+rev-list options and arguments +This manual page describes only the most frequently used options. See + for a complete list. --n <number> +--all + + + + Show all refs (branches, tags, etc.). + + + + + +--branches[=<pattern>] + + +--tags[=<pattern>] ---max-count=<number> +--remotes[=<pattern>] - Limits the number of commits to show. + Pretend as if all the branches (tags, remote branches, resp.) + are listed on the command line as <commit>. If <pattern> + is given, limit refs to ones matching given shell glob. If + pattern lacks ?, *, or [, /* at the + end is implied. @@ -67,11 +89,11 @@ frequently used options. ---all +--date-order - Show all branches. + Sort commits by date when possible. @@ -90,32 +112,116 @@ frequently used options. ---argscmd=<command> +--left-right - Command to be run each time gitk has to determine the list of - <revs> to show. The command is expected to print on its standard - output a list of additional revs to be shown, one per line. - Use this instead of explicitly specifying <revs> if the set of - commits to show may vary between refreshes. + Mark which side of a symmetric diff a commit is reachable + from. Commits from the left side are prefixed with a < + symbol and those from the right with a > symbol. ---select-commit=<ref> +--full-history - Automatically select the specified commit after loading the graph. - Default behavior is equivalent to specifying --select-commit=HEAD. + When filtering history with <path>…, does not prune some + history. (See "History simplification" in + for a more detailed explanation.) + + + + + +--simplify-merges + + + + Additional option to --full-history to remove some needless + merges from the resulting history, as there are no selected + commits contributing to this merge. (See "History + simplification" in for a more detailed + explanation.) -<revs> +--ancestry-path + + + + When given a range of commits to display + (e.g. commit1..commit2 or commit2 ^commit1), only + display commits that exist directly on the ancestry chain + between the commit1 and commit2, i.e. commits that are + both descendants of commit1, and ancestors of commit2. + (See "History simplification" in for a more + detailed explanation.) + + + + + +-L<start>,<end>:<file> + + +-L:<funcname>:<file> + + + + Trace the evolution of the line range given by "<start>,<end>" + (or the function name regex <funcname>) within the <file>. You may + not give any pathspec limiters. This is currently limited to + a walk starting from a single revision, i.e., you may only + give zero or one positive revision arguments. + You can specify this option more than once. + +Note: gitk (unlike ) currently only understands +this option if you specify it "glued together" with its argument. Do +not put a space after -L. +<start> and <end> can take one of these forms: + + + +number + +If <start> or <end> is a number, it specifies an +absolute line number (lines count from 1). + + + +/regex/ + +This form will use the first line matching the given +POSIX regex. If <start> is a regex, it will search from the end of +the previous -L range, if any, otherwise from the start of file. +If <start> is ^/regex/, it will search from the start of file. +If <end> is a regex, it will search +starting at the line given by <start>. + + + ++offset or -offset + +This is only valid for <end> and will specify a number +of lines before or after the line given by <start>. + + +If :<funcname> is given in place of <start> and <end>, it is a +regular expression that denotes the range from the first funcname line +that matches <funcname>, up to the next funcname line. :<funcname> +searches from the end of the previous -L range, if any, otherwise +from the start of file. ^:<funcname> searches from the start of +file. + + + + +<revision range> @@ -141,6 +247,38 @@ frequently used options. +
+
+gitk-specific options + + + +--argscmd=<command> + + + + Command to be run each time gitk has to determine the revision + range to show. The command is expected to print on its + standard output a list of additional revisions to be shown, + one per line. Use this instead of explicitly specifying a + <revision range> if the set of commits to show may vary + between refreshes. + + + + + +--select-commit=<ref> + + + + Select the specified commit after loading the graph. + Default behavior is equivalent to specifying --select-commit=HEAD. + + + + +
 Examples @@ -183,8 +321,28 @@ gitk --max-count=100 --all -- Makefile Files -Gitk creates the .gitk file in your $HOME directory to store preferences -such as display options, font, and colors. +User configuration and preferences are stored at: + + + +$XDG_CONFIG_HOME/git/gitk if it exists, otherwise + + + + +$HOME/.gitk if it exists + + + +If neither of the above exist then $XDG_CONFIG_HOME/git/gitk is created and +used by default. If $XDG_CONFIG_HOME is not set it defaults to +$HOME/.config in all cases. + + +History +Gitk was the first graphical repository browser. It's written in +tcl/tk and started off in a separate repository but was later merged +into the main Git repository. SEE ALSO @@ -206,7 +364,7 @@ such as display options, font, and colors. A repository browser written in Python using Gtk. It's based on - bzrk(1) and distributed in the contrib area of the git repository. + bzrk(1) and distributed in the contrib area of the Git repository. @@ -216,7 +374,7 @@ such as display options, font, and colors. - A minimal repository browser and git tool output highlighter written + A minimal repository browser and Git tool output highlighter written in C using Ncurses. diff --git a/doc/source/en/TortoiseGit/git_doc/gitmodules.xml b/doc/source/en/TortoiseGit/git_doc/gitmodules.xml index 410704f52..4f9db3845 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitmodules.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitmodules.xml @@ -16,7 +16,7 @@ DESCRIPTION -The .gitmodules file, located in the top-level directory of a git +The .gitmodules file, located in the top-level directory of a Git working tree, is a text file with a syntax matching the requirements of . The file contains one subsection per submodule, and the subsection value @@ -31,7 +31,7 @@ submodule.<name>.path - Defines the path, relative to the top-level directory of the git + Defines the path, relative to the top-level directory of the Git working tree, where the submodule is expected to be checked out. The path name must not end with a /. All submodule paths must be unique within the .gitmodules file. @@ -51,24 +51,37 @@ submodule.<name>.url + +In addition, there are a number of optional keys: + submodule.<name>.update - Defines what to do when the submodule is updated by the superproject. - If checkout (the default), the new commit specified in the - superproject will be checked out in the submodule on a detached HEAD. - If rebase, the current branch of the submodule will be rebased onto - the commit specified in the superproject. If merge, the commit - specified in the superproject will be merged into the current branch - in the submodule. - If none, the submodule with name $name will not be updated - by default. + Defines the default update procedure for the named submodule, + i.e. how the submodule is updated by "git submodule update" + command in the superproject. This is only used by git + submodule init to initialize the configuration variable of + the same name. Allowed values here are checkout, rebase, + merge or none. See description of update command in + for their meaning. Note that the + !command form is intentionally ignored here for security + reasons. + + + + + +submodule.<name>.branch + + + + A remote branch name for tracking updates in the upstream submodule. + If the option is not specified, it defaults to master. See the + --remote documentation in for details. -This config option is overridden if 'git submodule update' is given -the '--merge', '--rebase' or '--checkout' options. @@ -94,7 +107,9 @@ submodule.<name>.ignore Defines under what circumstances "git status" and the diff family show a submodule as modified. When set to "all", it will never be considered - modified, "dirty" will ignore all changes to the submodules work tree and + modified (but will nonetheless show up in the output of status and + commit when it has been staged), "dirty" will ignore all changes + to the submodules work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account. "untracked" will additionally let submodules with modified tracked files in their work tree show up. @@ -104,7 +119,8 @@ submodule.<name>.ignore the superproject, the setting there will override the one found in .gitmodules. Both settings can be overridden on the command line by using the - "--ignore-submodule" option. + "--ignore-submodule" option. The git submodule commands are not + affected by this setting. diff --git a/doc/source/en/TortoiseGit/git_doc/gitnamespaces.xml b/doc/source/en/TortoiseGit/git_doc/gitnamespaces.xml index eb3a06a06..255d7d5c6 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitnamespaces.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitnamespaces.xml @@ -31,7 +31,7 @@ provides similar support for avoiding duplicates, but alternates do not prevent duplication between new objects added to the repositories without ongoing maintenance, while namespaces do. To specify a namespace, set the GIT_NAMESPACE environment variable to -the namespace. For each ref namespace, git stores the corresponding +the namespace. For each ref namespace, Git stores the corresponding refs in a directory under refs/namespaces/. For example, GIT_NAMESPACE=foo will store refs under refs/namespaces/foo/. You can also specify namespaces via the --namespace option to diff --git a/doc/source/en/TortoiseGit/git_doc/git-remote-helpers.xml b/doc/source/en/TortoiseGit/git_doc/gitremote-helpers.xml similarity index 78% rename from doc/source/en/TortoiseGit/git_doc/git-remote-helpers.xml rename to doc/source/en/TortoiseGit/git_doc/gitremote-helpers.xml index 529f0a7c8..f23a0108f 100644 --- a/doc/source/en/TortoiseGit/git_doc/git-remote-helpers.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitremote-helpers.xml @@ -1,34 +1,34 @@ - - git-remote-helpers(1) + + gitremote-helpers(1) -git-remote-helpers(1) +gitremote-helpers(1) - + NAME -git-remote-helpers - Helper programs to interact with remote repositories +gitremote-helpers - Helper programs to interact with remote repositories - + SYNOPSIS
git remote-<transport> <repository> [<URL>]
- + DESCRIPTION Remote helper programs are normally not used directly by end users, -but they are invoked by git when it needs to interact with remote -repositories git does not support natively. A given helper will -implement a subset of the capabilities documented here. When git +but they are invoked by Git when it needs to interact with remote +repositories Git does not support natively. A given helper will +implement a subset of the capabilities documented here. When Git needs to interact with a repository using a remote helper, it spawns the helper as an independent process, sends commands to the helper's standard input, and expects results from the helper's standard output. Because a remote helper runs as an independent process from -git, there is no need to re-link git to add a new helper, nor any -need to link the helper with the implementation of git. -Every helper must support the "capabilities" command, which git +Git, there is no need to re-link Git to add a new helper, nor any +need to link the helper with the implementation of Git. +Every helper must support the "capabilities" command, which Git uses to determine what other commands the helper will accept. Those other commands can be used to discover and update remote refs, transport objects between the object database and the remote repository, @@ -38,34 +38,34 @@ transport protocols, such as git-remote-http, git git-remote-ftp and git-remote-ftps. They implement the capabilities fetch, option, and push. - + INVOCATION Remote helper programs are invoked with one or (optionally) two -arguments. The first argument specifies a remote repository as in git; +arguments. The first argument specifies a remote repository as in Git; it is either the name of a configured remote or a URL. The second argument specifies a URL; it is usually of the form <transport>://<address>, but any arbitrary string is possible. The GIT_DIR environment variable is set up for the remote helper and can be used to determine where to store additional data or from -which directory to invoke auxiliary git commands. -When git encounters a URL of the form <transport>://<address>, where +which directory to invoke auxiliary Git commands. +When Git encounters a URL of the form <transport>://<address>, where <transport> is a protocol that it cannot handle natively, it automatically invokes git remote-<transport> with the full URL as the second argument. If such a URL is encountered directly on the command line, the first argument is the same as the second, and if it is encountered in a configured remote, the first argument is the name of that remote. -A URL of the form <transport>::<address> explicitly instructs git to +A URL of the form <transport>::<address> explicitly instructs Git to invoke git remote-<transport> with <address> as the second argument. If such a URL is encountered directly on the command line, the first argument is <address>, and if it is encountered in a configured remote, the first argument is the name of that remote. Additionally, when a configured remote has remote.<name>.vcs set to -<transport>, git explicitly invokes git remote-<transport> with +<transport>, Git explicitly invokes git remote-<transport> with <name> as the first argument. If set, the second argument is remote.<name>.url; otherwise, the second argument is omitted. - + INPUT FORMAT Git sends the remote helper a list of commands on standard input, one per line. The first command is always the capabilities command, in @@ -77,15 +77,15 @@ in the remainder of the command stream. (indicated in the documentation of the relevant commands), this blank line is followed by a payload in some other protocol (e.g., the pack protocol), while in others it indicates the end of input. -
+
Capabilities Each remote helper is expected to support only a subset of commands. -The operations a helper supports are declared to git in the response +The operations a helper supports are declared to Git in the response to the capabilities command (see COMMANDS, below). In the following, we list all defined capabilities and for each we list which commands a helper with that capability must provide. -
+
Capabilities for Pushing @@ -127,13 +127,27 @@ must provide. -If a helper advertises connect, git will use it if possible and +If a helper advertises connect, Git will use it if possible and fall back to another capability if the helper requests so when connecting (see the connect command under COMMANDS). -When choosing between push and export, git prefers push. +When choosing between push and export, Git prefers push. Other frontends may have some other order of preference. + + + +no-private-update + + + + When using the refspec capability, git normally updates the + private ref on successful push. This update is disabled when + the remote-helper declares the capability no-private-update. + + + +
-
+
Capabilities for Fetching @@ -144,7 +158,7 @@ Other frontends may have some other order of preference. Can try to connect to git upload-pack (for fetching), git receive-pack, etc for communication using the - git's native packfile protocol. This + Git's native packfile protocol. This requires a bidirectional, full-duplex connection. Supported commands: connect. @@ -174,14 +188,25 @@ Other frontends may have some other order of preference. Supported commands: list, import. + + +check-connectivity + + + + Can guarantee that when a clone is requested, the received + pack is self contained and is connected. + + + -If a helper advertises connect, git will use it if possible and +If a helper advertises connect, Git will use it if possible and fall back to another capability if the helper requests so when connecting (see the connect command under COMMANDS). -When choosing between fetch and import, git prefers fetch. +When choosing between fetch and import, Git prefers fetch. Other frontends may have some other order of preference.
-
+
Miscellaneous capabilities @@ -203,11 +228,11 @@ Other frontends may have some other order of preference. - This modifies the import capability, allowing the produced - fast-import stream to modify refs in a private namespace - instead of writing to refs/heads or refs/remotes directly. + For remote helpers that implement import or export, this capability + allows the refs to be constrained to a private namespace, instead of + writing to refs/heads or refs/remotes directly. It is recommended that all importers providing the import - capability use this. + capability use this. It's mandatory for export. A helper advertising the capability refspec refs/heads/*:refs/svn/origin/branches/* @@ -219,6 +244,11 @@ applicable refspec takes precedence. The left-hand of refspecs advertised with this capability must cover all refs reported by the list command. If no refspec capability is advertised, there is an implied refspec *:*. +When writing remote-helpers for decentralized version control +systems, it is advised to keep a local copy of the repository to +interact with, and to let the private namespace refs point to this +local repository, while the refs/remotes namespace is used to track +the remote repository. @@ -232,10 +262,10 @@ there is an implied refspec *:*. to retrieve information about blobs and trees that already exist in fast-import's memory. This requires a channel from fast-import to the remote-helper. - If it is advertised in addition to "import", git establishes a pipe from + If it is advertised in addition to "import", Git establishes a pipe from fast-import to the remote-helper's stdin. - It follows that git and fast-import are both connected to the - remote-helper's stdin. Because git can send multiple commands to + It follows that Git and fast-import are both connected to the + remote-helper's stdin. Because Git can send multiple commands to the remote-helper it is required that helpers that use bidi-import buffer all import commands of a batch before sending data to fast-import. This is to prevent mixing commands and fast-import responses on the @@ -249,7 +279,7 @@ there is an implied refspec *:*. - This modifies the export capability, instructing git to dump the + This modifies the export capability, instructing Git to dump the internal marks table to <file> when complete. For details, read up on --export-marks=<file> in . @@ -261,17 +291,29 @@ there is an implied refspec *:*. - This modifies the export capability, instructing git to load the + This modifies the export capability, instructing Git to load the marks specified in <file> before processing any input. For details, read up on --import-marks=<file> in . + + +signed-tags + + + + This modifies the export capability, instructing Git to pass + --signed-tags=verbatim to . In the + absence of this capability, Git will use --signed-tags=warn-strip. + + +
- + COMMANDS Commands are given by the caller on the helper's standard input, one per line. @@ -283,7 +325,7 @@ there is an implied refspec *:*. Lists the capabilities of the helper, one per line, ending with a blank line. Each capability may be preceded with *, - which marks them mandatory for git versions using the remote + which marks them mandatory for Git versions using the remote helper to understand. Any unknown mandatory capability is a fatal error. @@ -357,6 +399,8 @@ there is an implied refspec *:*. Optionally may output a lock <file> line indicating a file under GIT_DIR/objects/pack which is keeping a pack until refs can be suitably updated. +If option check-connectivity is requested, the helper must output +connectivity-ok if the clone is self-contained and connected. Supported if the helper has the "fetch" capability. @@ -467,7 +511,7 @@ completing a valid response for the current command. Additional commands may be supported, as may be determined from capabilities reported by the helper. - + REF LIST ATTRIBUTES The list command produces a list of refs in which each ref may be followed by a list of attributes. The following ref list @@ -486,10 +530,10 @@ attributes are defined. - + OPTIONS The following options are defined and (under suitable circumstances) -set by git if the remote helper has the option capability. +set by Git if the remote helper has the option capability. @@ -561,14 +605,69 @@ set by git if the remote helper has the option capability.< + + +option check-connectivity {true|false} + + + + Request the helper to check connectivity of a clone. + + + + + +option force {true|false} + + + + Request the helper to perform a force update. Defaults to + false. + + + + + +option cloning {'true|false} + + + + Notify the helper this is a clone request (i.e. the current + repository is guaranteed empty). + + + + + +option update-shallow {'true|false} + + + + Allow to extend .git/shallow if the new refs require it. + + + + + +option pushcert {'true|false} + + + + GPG sign pushes. + + + - + SEE ALSO + + + - + GIT Part of the suite diff --git a/doc/source/en/TortoiseGit/git_doc/gitrepository-layout.xml b/doc/source/en/TortoiseGit/git_doc/gitrepository-layout.xml index 961573b41..7ee80de05 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitrepository-layout.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitrepository-layout.xml @@ -16,12 +16,30 @@ DESCRIPTION -You may find these things in your git repository (.git -directory for a repository associated with your working tree, or -<project>.git directory for a public bare repository. It is -also possible to have a working tree where .git is a plain -ASCII file containing gitdir: <path>, i.e. the path to the -real git repository). +A Git repository comes in two different flavours: + + + +a .git directory at the root of the working tree; + + + + +a <project>.git directory that is a bare repository + (i.e. without its own working tree), that is typically used for + exchanging histories with others by pushing into it and fetching + from it. + + + +Note: Also you can have a plain text file .git at the root of +your working tree, containing gitdir: <path> to point at the real +directory that has the repository. This mechanism is often used for +a working tree of a submodule checkout, to allow you in the +containing superproject to git checkout a branch that does not +have the submodule. The checkout has to remove the entire +submodule working tree, without losing the submodule repository. +These things may exist in a Git repository. @@ -51,6 +69,8 @@ use with dumb transports but otherwise is OK as long as objects/info/alternates points at the object stores it borrows from. +This directory is ignored if $GIT_COMMON_DIR is set and +"$GIT_COMMON_DIR/objects" will be used instead. @@ -147,7 +167,8 @@ refs References are stored in subdirectories of this directory. The git prune command knows to preserve objects reachable from refs found in this directory and - its subdirectories. + its subdirectories. This directory is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/refs" will be used instead. @@ -189,7 +210,7 @@ refs/replace/<obj-sha1> - records the SHA1 of the object that replaces <obj-sha1>. + records the SHA-1 of the object that replaces <obj-sha1>. This is similar to info/grafts and is internally used and maintained by . Such refs can be exchanged between repositories while grafts are not. @@ -204,7 +225,8 @@ packed-refs records the same information as refs/heads/, refs/tags/, and friends record in a more efficient way. See - . + . This file is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/packed-refs" will be used instead. @@ -217,7 +239,7 @@ HEAD A symref (see glossary) to the refs/heads/ namespace describing the currently active branch. It does not mean much if the repository is not associated with any working tree - (i.e. a bare repository), but a valid git repository + (i.e. a bare repository), but a valid Git repository must have the HEAD file; some porcelains may use it to guess the designated "default" branch of the repository (usually master). It is legal if the named branch @@ -233,6 +255,18 @@ for details. +config + + + + Repository specific configuration file. This file is ignored + if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be + used instead. + + + + + branches @@ -243,7 +277,9 @@ branches name can be given to these commands in place of repository argument. See the REMOTES section in for details. This mechanism is legacy - and not likely to be found in modern repositories. + and not likely to be found in modern repositories. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/branches" will be used instead. @@ -253,13 +289,14 @@ hooks - Hooks are customization scripts used by various git + Hooks are customization scripts used by various Git commands. A handful of sample hooks are installed when git init is run, but all of them are disabled by default. To enable, the .sample suffix has to be removed from the filename by renaming. Read for more details about - each hook. + each hook. This directory is ignored if $GIT_COMMON_DIR is set + and "$GIT_COMMON_DIR/hooks" will be used instead. @@ -276,12 +313,24 @@ index +sharedindex.<SHA-1> + + + + The shared index part, to be referenced by $GIT_DIR/index and + other temporary index files. Only valid in split index mode. + + + + + info Additional information about the repository is recorded - in this directory. + in this directory. This directory is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/index" will be used instead. @@ -315,6 +364,9 @@ info/grafts listing their 40-byte hexadecimal object names separated by a space and terminated by a newline. +Note that the grafts mechanism is outdated and can lead to problems +transferring objects between repositories; see +for a more flexible and robust system to do the same thing. @@ -326,13 +378,24 @@ info/exclude This file, by convention among Porcelains, stores the exclude pattern list. .gitignore is the per-directory ignore file. git status, git add, git rm and - git clean look at it but the core git commands do not look + git clean look at it but the core Git commands do not look at it. See also: . +info/sparse-checkout + + + + This file stores sparse checkout patterns. + See also: . + + + + + remotes @@ -341,7 +404,9 @@ remotes when interacting with remote repositories via git fetch, git pull and git push commands. See the REMOTES section in for details. This mechanism is legacy - and not likely to be found in modern repositories. + and not likely to be found in modern repositories. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/remotes" will be used instead. @@ -351,9 +416,10 @@ logs - Records of changes made to refs are stored in this - directory. See - for more information. + Records of changes made to refs are stored in this directory. + See for more information. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/logs" will be used instead. @@ -385,7 +451,87 @@ shallow This is similar to info/grafts but is internally used and maintained by shallow clone mechanism. See --depth - option to and . + option to and . This + file is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/shallow" will be used instead. + + + + + +commondir + + + + If this file exists, $GIT_COMMON_DIR (see ) will + be set to the path specified in this file if it is not + explicitly set. If the specified path is relative, it is + relative to $GIT_DIR. The repository with commondir is + incomplete without the repository pointed by "commondir". + + + + + +modules + + + + Contains the git-repositories of the submodules. + + + + + +worktrees + + + + Contains administrative data for linked + working trees. Each subdirectory contains the working tree-related + part of a linked working tree. This directory is ignored if + $GIT_COMMON_DIR is set, in which case + "$GIT_COMMON_DIR/worktrees" will be used instead. + + + + + +worktrees/<id>/gitdir + + + + A text file containing the absolute path back to the .git file + that points to here. This is used to check if the linked + repository has been manually removed and there is no need to + keep this directory any more. The mtime of this file should be + updated every time the linked repository is accessed. + + + + + +worktrees/<id>/locked + + + + If this file exists, the linked working tree may be on a + portable device and not available. The presence of this file + prevents worktrees/<id> from being pruned either automatically + or manually by git worktree prune. The file may contain a string + explaining why the repository is locked. + + + + + +worktrees/<id>/link + + + + If this file exists, it is a hard link to the linked .git + file. It is used to detect if the linked repository is + manually removed. diff --git a/doc/source/en/TortoiseGit/git_doc/gitrevisions.xml b/doc/source/en/TortoiseGit/git_doc/gitrevisions.xml index 86edd257d..aa80a441d 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitrevisions.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitrevisions.xml @@ -8,7 +8,7 @@ NAME -gitrevisions - specifying revisions and ranges for git +gitrevisions - specifying revisions and ranges for Git SYNOPSIS @@ -28,7 +28,7 @@ revision parameters which denote other objects than commits, e.g. blobs SPECIFYING REVISIONS A revision parameter <rev> typically, but not necessarily, names a -commit object. It uses what is called an extended SHA1 +commit object. It uses what is called an extended SHA-1 syntax. Here are various ways to spell object names. The ones listed near the end of this list name trees and blobs contained in a commit. @@ -39,7 +39,7 @@ blobs contained in a commit. - The full SHA1 object name (40-byte hexadecimal string), or + The full SHA-1 object name (40-byte hexadecimal string), or a leading substring that is unique within the repository. E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the same commit object if there is no other object in @@ -68,7 +68,7 @@ blobs contained in a commit. A symbolic ref name. E.g. master typically means the commit object referenced by refs/heads/master. If you happen to have both heads/master and tags/master, you can - explicitly say heads/master to tell git which one you mean. + explicitly say heads/master to tell Git which one you mean. When ambiguous, a <refname> is disambiguated by taking the first match in the following rules: @@ -117,7 +117,7 @@ when you run git merge. when you run git cherry-pick. Note that any of the refs/* cases above may come either from the $GIT_DIR/refs directory or from the $GIT_DIR/packed-refs file. -While the ref name encoding is unspecified, UTF-8 is prefered as +While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. @@ -125,6 +125,16 @@ some output processing may assume ref names in UTF-8. +@ + + + + @ alone is a shortcut for HEAD. + + + + + <refname>@{<date>}, e.g. master@{yesterday}, HEAD@{5 minutes ago} @@ -176,21 +186,50 @@ some output processing may assume ref names in UTF-8. - The construct @{-<n>} means the <n>th branch checked out + The construct @{-<n>} means the <n>th branch/commit checked out before the current one. -<refname>@{upstream}, e.g. master@{upstream}, @{u} +<branchname>@{upstream}, e.g. master@{upstream}, @{u} + + + + The suffix @{upstream} to a branchname (short form <branchname>@{u}) + refers to the branch that the branch specified by branchname is set to build on + top of (configured with branch.<name>.remote and + branch.<name>.merge). A missing branchname defaults to the + current one. + + + + + +<branchname>@{push}, e.g. master@{push}, @{push} - The suffix @{upstream} to a ref (short form <refname>@{u}) refers to - the branch the ref is set to build on top of. A missing ref defaults - to the current branch. + The suffix @{push} reports the branch "where we would push to" if + git push were run while branchname was checked out (or the current + HEAD if no branchname is specified). Since our push destination is + in a remote repository, of course, we report the local tracking branch + that corresponds to that branch (i.e., something in refs/remotes/). +Here's an example to make it more clear: +$ git config push.default current +$ git config remote.pushdefault myfork +$ git checkout -b mybranch origin/master + +$ git rev-parse --symbolic-full-name @{upstream} +refs/remotes/origin/master + +$ git rev-parse --symbolic-full-name @{push} +refs/remotes/myfork/mybranch +Note in the example that we set up a triangular workflow, where we pull +from one location and push to another. In a non-triangular workflow, +@{push} is the same as @{upstream}, and there is no need for it. @@ -230,12 +269,22 @@ some output processing may assume ref names in UTF-8. A suffix ^ followed by an object type name enclosed in - brace pair means the object - could be a tag, and dereference the tag recursively until an - object of that type is found or the object cannot be - dereferenced anymore (in which case, barf). <rev>^0 + brace pair means dereference the object at <rev> recursively until + an object of type <type> is found or the object cannot be + dereferenced anymore (in which case, barf). + For example, if <rev> is a commit-ish, <rev>^{commit} + describes the corresponding commit object. + Similarly, if <rev> is a tree-ish, <rev>^{tree} + describes the corresponding tree object. + <rev>^0 is a short-hand for <rev>^{commit}. +rev^{object} can be used to make sure rev names an +object that exists, without requiring rev to be a tag, and +without dereferencing rev; because a tag is already an object, +it does not have to be dereferenced even once to get to an object. +rev^{tag} can be used to ensure that rev identifies an +existing tag object. @@ -274,11 +323,12 @@ some output processing may assume ref names in UTF-8. A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is - reachable from any ref. If the commit message starts with a - ! you have to repeat that; the special sequence :/!, - followed by something else than !, is reserved for now. - The regular expression can match any part of the commit message. To - match messages starting with a string, one can use e.g. :/^foo. + reachable from any ref. The regular expression can match any part of the + commit message. To match messages starting with a string, one can use + e.g. :/^foo. The special sequence :/! is reserved for modifiers to what + is matched. :/!-foo performs a negative match, while :/!!foo matches a + literal ! character, followed by foo. Any other sequence beginning with + :/! is reserved for now. @@ -403,7 +453,8 @@ all of its parents. Include commits that are reachable from <rev2> but exclude - those that are reachable from <rev1>. + those that are reachable from <rev1>. When either <rev1> or + <rev2> is omitted, it defaults to HEAD. @@ -414,7 +465,8 @@ all of its parents. Include commits that are reachable from either <rev1> or - <rev2> but exclude those that are reachable from both. + <rev2> but exclude those that are reachable from both. When + either <rev1> or <rev2> is omitted, it defaults to HEAD. diff --git a/doc/source/en/TortoiseGit/git_doc/gittutorial-2.xml b/doc/source/en/TortoiseGit/git_doc/gittutorial-2.xml index ae16f0572..45fc18204 100644 --- a/doc/source/en/TortoiseGit/git_doc/gittutorial-2.xml +++ b/doc/source/en/TortoiseGit/git_doc/gittutorial-2.xml @@ -8,7 +8,7 @@ NAME -gittutorial-2 - A tutorial introduction to git: part two +gittutorial-2 - A tutorial introduction to Git: part two SYNOPSIS @@ -20,12 +20,12 @@ DESCRIPTION You should work through before reading this tutorial. The goal of this tutorial is to introduce two fundamental pieces of -git's architecture--the object database and the index file--and to +Git's architecture--the object database and the index file--and to provide the reader with everything necessary to understand the rest -of the git documentation. +of the Git documentation. -The git object database +The Git object database Let's start a new project and create a small amount of history: $ mkdir test-project $ cd test-project @@ -41,22 +41,22 @@ $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" [master c4d59f3] add emphasis 1 file changed, 1 insertion(+), 1 deletion(-) -What are the 7 digits of hex that git responded to the commit with? +What are the 7 digits of hex that Git responded to the commit with? We saw in part one of the tutorial that commits have names like this. -It turns out that every object in the git history is stored under -a 40-digit hex name. That name is the SHA1 hash of the object's -contents; among other things, this ensures that git will never store -the same data twice (since identical data is given an identical SHA1 -name), and that the contents of a git object will never change (since +It turns out that every object in the Git history is stored under +a 40-digit hex name. That name is the SHA-1 hash of the object's +contents; among other things, this ensures that Git will never store +the same data twice (since identical data is given an identical SHA-1 +name), and that the contents of a Git object will never change (since that would change the object's name as well). The 7 char hex strings here are simply the abbreviation of such 40 character long strings. Abbreviations can be used everywhere where the 40 character strings can be used, so long as they are unambiguous. It is expected that the content of the commit object you created while -following the example above generates a different SHA1 hash than +following the example above generates a different SHA-1 hash than the one shown above because the commit object records the time when it was created and the name of the person performing the commit. -We can ask git about this particular object with the cat-file +We can ask Git about this particular object with the cat-file command. Don't copy the 40 hex digits from this example but use those from your own version. Note that you can shorten it to only a few characters to save yourself typing all 40 hex digits: @@ -72,20 +72,20 @@ initial commit a file. In addition, a tree can also refer to other tree objects, thus creating a directory hierarchy. You can examine the contents of any tree using ls-tree (remember that a long enough initial portion -of the SHA1 will also work): +of the SHA-1 will also work): $ git ls-tree 92b8b694 100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt -Thus we see that this tree has one file in it. The SHA1 hash is a +Thus we see that this tree has one file in it. The SHA-1 hash is a reference to that file's data: $ git cat-file -t 3b18e512 blob A "blob" is just file data, which we can also examine with cat-file: $ git cat-file blob 3b18e512 hello world -Note that this is the old file data; so the object that git named in +Note that this is the old file data; so the object that Git named in its response to the initial tree was a tree with a snapshot of the directory state that was recorded by the first commit. -All of these objects are stored under their SHA1 names inside the git +All of these objects are stored under their SHA-1 names inside the Git directory: $ find .git/objects/ .git/objects/ @@ -112,7 +112,7 @@ from .git/HEAD: ref: refs/heads/master As you can see, this tells us which branch we're currently on, and it tells us this by naming a file under the .git directory, which itself -contains a SHA1 name referring to a commit object, which we can +contains a SHA-1 name referring to a commit object, which we can examine with cat-file: $ cat .git/refs/heads/master c4d59f390b9cfd4318117afde11d601c1085f241 @@ -146,7 +146,7 @@ branches. Besides blobs, trees, and commits, the only remaining type of object is a "tag", which we won't discuss here; refer to for details. -So now we know how git uses the object database to represent a +So now we know how Git uses the object database to represent a project's history: @@ -183,7 +183,7 @@ The name of the current branch is stored in .git/HEAD. Note, by the way, that lots of commands take a tree as an argument. But as we can see above, a tree can be referred to in many different -ways--by the SHA1 name for that tree, by the name of a commit that +ways--by the SHA-1 name for that tree, by the name of a commit that refers to the tree, by the name of a branch whose head refers to that tree, etc.--and most such commands can accept any of these names. In command synopses, the word "tree-ish" is sometimes used to @@ -296,17 +296,17 @@ goodbye, world The "status" command is a useful way to get a quick summary of the situation: $ git status -# On branch master -# Changes to be committed: -# (use "git reset HEAD <file>..." to unstage) -# -# new file: closing.txt -# -# Changes not staged for commit: -# (use "git add <file>..." to update what will be committed) -# -# modified: file.txt -# +On branch master +Changes to be committed: + (use "git reset HEAD <file>..." to unstage) + + new file: closing.txt + +Changes not staged for commit: + (use "git add <file>..." to update what will be committed) + (use "git checkout -- <file>..." to discard changes in working directory) + + modified: file.txt Since the current state of closing.txt is cached in the index file, it is listed as "Changes to be committed". Since file.txt has changes in the working directory that aren't reflected in the index, @@ -326,17 +326,17 @@ pages for details. What next? At this point you should know everything necessary to read the man pages for any of the git commands; one good place to start would be -with the commands mentioned in link:everyday.html[Everyday git]. You +with the commands mentioned in . You should be able to find any unknown jargon in . The link:user-manual.html[Git User's Manual] provides a more -comprehensive introduction to git. +comprehensive introduction to Git. explains how to -import a CVS repository into git, and shows how to use git in a +import a CVS repository into Git, and shows how to use Git in a CVS-like way. -For some interesting examples of git use, see the +For some interesting examples of Git use, see the link:howto-index.html[howtos]. -For git developers, goes -into detail on the lower-level git mechanisms involved in, for +For Git developers, goes +into detail on the lower-level Git mechanisms involved in, for example, creating a new commit. @@ -346,7 +346,7 @@ example, creating a new commit. , , , -link:everyday.html[Everyday git], +, link:user-manual.html[The Git User's Manual] diff --git a/doc/source/en/TortoiseGit/git_doc/gittutorial.xml b/doc/source/en/TortoiseGit/git_doc/gittutorial.xml index 48c608e84..b1bfc34f0 100644 --- a/doc/source/en/TortoiseGit/git_doc/gittutorial.xml +++ b/doc/source/en/TortoiseGit/git_doc/gittutorial.xml @@ -8,7 +8,7 @@ NAME -gittutorial - A tutorial introduction to git (for version 1.5.1 or newer) +gittutorial - A tutorial introduction to Git SYNOPSIS @@ -18,9 +18,9 @@ DESCRIPTION -This tutorial explains how to import a new project into git, make +This tutorial explains how to import a new project into Git, make changes to it, and share changes with other developers. -If you are instead primarily interested in using git to fetch a project, +If you are instead primarily interested in using Git to fetch a project, for example, to test the latest version, you may prefer to start with the first two chapters of link:user-manual.html[The Git User's Manual]. First, note that you can get documentation for a command such as @@ -30,7 +30,7 @@ the first two chapters of link:user-manual.html[The Git User's Manual].$ git help log With the latter, you can use the manual viewer of your choice; see for more information. -It is a good idea to introduce yourself to git with your name and +It is a good idea to introduce yourself to Git with your name and public email address before doing any operation. The easiest way to do so is: $ git config --global user.name "Your Name Comes Here" @@ -39,7 +39,7 @@ $ git config --global user.email you@yourdomain.example.com Importing a new project Assume you have a tarball project.tar.gz with your initial work. You -can place it under git revision control as follows. +can place it under Git revision control as follows. $ tar xzf project.tar.gz $ cd project $ git init @@ -47,15 +47,15 @@ $ git init Initialized empty Git repository in .git/ You've now initialized the working directory--you may notice a new directory created, named ".git". -Next, tell git to take a snapshot of the contents of all files under the +Next, tell Git to take a snapshot of the contents of all files under the current directory (note the .), with git add: $ git add . -This snapshot is now stored in a temporary staging area which git calls +This snapshot is now stored in a temporary staging area which Git calls the "index". You can permanently store the contents of the index in the repository with git commit: $ git commit This will prompt you for a commit message. You've now stored the first -version of your project in git. +version of your project in Git. Making changes @@ -68,14 +68,14 @@ using git diff with the --cached option: you've made but not yet added to the index.) You can also get a brief summary of the situation with git status: $ git status -# On branch master -# Changes to be committed: -# (use "git reset HEAD <file>..." to unstage) -# -# modified: file1 -# modified: file2 -# modified: file3 -# +On branch master +Changes to be committed: +Your branch is up-to-date with 'origin/master'. + (use "git reset HEAD <file>..." to unstage) + + modified: file1 + modified: file2 + modified: file3 If you need to make any further adjustments, do so now, and then add any newly modified content to the index. Finally, commit your changes with: $ git commit @@ -90,7 +90,7 @@ begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used -throughout git. For example, turns a +throughout Git. For example, turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body. @@ -115,7 +115,7 @@ each step Managing branches -A single git repository can maintain multiple branches of +A single Git repository can maintain multiple branches of development. To create a new branch named "experimental", use $ git branch experimental If you now run @@ -161,8 +161,8 @@ delete the branch with out. -Using git for collaboration -Suppose that Alice has started a new project with a git repository in +Using Git for collaboration +Suppose that Alice has started a new project with a Git repository in /home/alice/project, and that Bob, who has a home directory on the same machine, wants to contribute. Bob begins with: @@ -187,7 +187,7 @@ from a remote branch, then merges them into the current branch. initiating this "pull". If Bob's work conflicts with what Alice did since their histories forked, Alice will use her working tree and the index to resolve conflicts, and existing local changes will interfere with the -conflict resolution process (git will still perform the fetch but will +conflict resolution process (Git will still perform the fetch but will refuse to merge --- Alice will have to get rid of her local changes in some way and pull again when this happens). Alice can peek at what Bob did without merging first, using the "fetch" @@ -245,7 +245,7 @@ regardless of what else is given on the command line. Later, Bob can update his repo with Alice's latest changes using bob$ git pull Note that he doesn't need to give the path to Alice's repository; -when Bob cloned Alice's repository, git stored the location of her +when Bob cloned Alice's repository, Git stored the location of her repository in the repository configuration, and that location is used for pulls: bob$ git config --get remote.origin.url @@ -260,7 +260,7 @@ name "origin/master": If Bob later decides to work from a different host, he can still perform clones and pulls using the ssh protocol: bob$ git clone alice.org:/home/alice/project myrepo -Alternatively, git has a native protocol, or can use rsync or http; +Alternatively, Git has a native protocol, or can use http; see for details. Git can also be used in a CVS-like mode, with a central repository that various users push changes to; see and @@ -301,7 +301,7 @@ $ git show HEAD^2 # show the second parent of HEAD share this name with other people (for example, to identify a release version), you should create a "tag" object, and perhaps sign it; see for details. -Any git command that needs to know a commit can take any of these +Any Git command that needs to know a commit can take any of these names. For example: $ git diff v2.5 HEAD # compare the current HEAD to v2.5 $ git branch stable v2.5 # start a new branch named "stable" based @@ -323,8 +323,8 @@ project, so If you leave out the commit name, git grep will search any of the files it manages in your current directory. So $ git grep "hello" -is a quick way to search just the files that are tracked by git. -Many git commands also take sets of commits, which can be specified +is a quick way to search just the files that are tracked by Git. +Many Git commands also take sets of commits, which can be specified in a number of ways. Here are some examples with git log: $ git log v2.5..v2.6 # commits between v2.5 and v2.6 $ git log v2.5.. # commits since v2.5 @@ -346,7 +346,7 @@ list. When the history has lines of development that diverged and then merged back together, the order in which git log presents those commits is meaningless. Most projects with multiple contributors (such as the Linux kernel, -or git itself) have frequent merges, and gitk does a better job of +or Git itself) have frequent merges, and gitk does a better job of visualizing their history. For example, $ gitk --since="2 weeks ago" drivers/ allows you to browse any commits from the last 2 weeks of commits @@ -364,7 +364,7 @@ of the file: Next Steps This tutorial should be enough to perform basic distributed revision control for your projects. However, to fully understand the depth -and power of git you need to understand two simple ideas on which it +and power of Git you need to understand two simple ideas on which it is based: @@ -384,7 +384,7 @@ The index file is a cache of the state of a directory tree, Part two of this tutorial explains the object database, the index file, and a few other odds and ends that you'll -need to make the most of git. You can find it at . +need to make the most of Git. You can find it at . If you don't want to continue with that right away, a few other digressions that may be interesting at this point are: @@ -414,7 +414,7 @@ digressions that may be interesting at this point are: -link:everyday.html[Everyday GIT with 20 Commands Or So] +: Everyday Git with 20 Commands Or So. @@ -432,7 +432,7 @@ link:everyday.html[Everyday GIT with 20 Commands Or So] , , , -link:everyday.html[Everyday git], +, link:user-manual.html[The Git User's Manual] diff --git a/doc/source/en/TortoiseGit/git_doc/gitweb.conf.xml b/doc/source/en/TortoiseGit/git_doc/gitweb.conf.xml index df0ed3c65..2de3eff54 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitweb.conf.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitweb.conf.xml @@ -8,7 +8,7 @@ NAME -gitweb.conf - Gitweb (git web interface) configuration file +gitweb.conf - Gitweb (Git web interface) configuration file SYNOPSIS @@ -81,7 +81,7 @@ stops declaring it. You can include other configuration file using read_config_file() subroutine. For example, one might want to put gitweb configuration related to access control for viewing repositories via Gitolite (one -of git repository management tools) in a separate file, e.g. in +of Git repository management tools) in a separate file, e.g. in /etc/gitweb-gitolite.conf. To include it, put read_config_file("/etc/gitweb-gitolite.conf"); somewhere in gitweb configuration file used, e.g. in per-installation @@ -104,7 +104,7 @@ and installing gitweb.
Location of repositories The configuration variables described below control how gitweb finds -git repositories, and how repositories are displayed and accessed. +Git repositories, and how repositories are displayed and accessed. See also "Repositories" and later subsections in manpage. @@ -152,7 +152,7 @@ $project_maxdepth If $projects_list variable is unset, gitweb will recursively - scan filesystem for git repositories. The $project_maxdepth + scan filesystem for Git repositories. The $project_maxdepth is used to limit traversing depth, relative to $projectroot (starting point); it means that directories which are further from $projectroot than $project_maxdepth will be skipped. @@ -197,7 +197,7 @@ $export_auth_hook though the above might be done by using $export_ok instead our $export_ok = "git-daemon-export-ok"; If not set (default), it means that this feature is disabled. -See also more involved example in "Controlling access to git repositories" +See also more involved example in "Controlling access to Git repositories" subsection on manpage. @@ -233,11 +233,11 @@ $GIT Core git executable to use. By default set to $GIT_BINDIR/git, which - in turn is by default set to $(bindir)/git. If you use git installed + in turn is by default set to $(bindir)/git. If you use Git installed from a binary package, you should usually set this to "/usr/bin/git". This can just be "git" if your web server has a sensible PATH; from security point of view it is better to use absolute path to git binary. - If you have multiple git versions installed it can be used to choose + If you have multiple Git versions installed it can be used to choose which one to use. Must be (correctly) set for gitweb to be able to work. @@ -251,7 +251,7 @@ $mimetypes_file File to use for (filename extension based) guessing of MIME types before trying /etc/mime.types. NOTE that this path, if relative, is taken - as relative to the current git repository, not to CGI script. If unset, + as relative to the current Git repository, not to CGI script. If unset, only /etc/mime.types is used (if present on filesystem). If no mimetypes file is found, mimetype guessing based on extension of file is disabled. Unset by default. @@ -392,13 +392,37 @@ $home_link_str used as the first component of gitweb's "breadcrumb trail": <home link> / <project> / <action>. Can be set at build time using the GITWEB_HOME_LINK_STR variable. By default it is set to "projects", - as this link leads to the list of projects. Other popular choice it to - set it to the name of site. + as this link leads to the list of projects. Another popular choice is to + set it to the name of site. Note that it is treated as raw HTML so it + should not be set from untrusted sources. +@extra_breadcrumbs + + + + Additional links to be added to the start of the breadcrumb trail before + the home link, to pages that are logically "above" the gitweb projects + list, such as the organization and department which host the gitweb + server. Each element of the list is a reference to an array, in which + element 0 is the link text (equivalent to $home_link_str) and element + 1 is the target URL (equivalent to $home_link). + +For example, the following setting produces a breadcrumb trail like +"home / dev / projects / …" where "projects" is the home link. + + + + our @extra_breadcrumbs = ( + [ 'home' => 'https://www.example.org/' ], + [ 'dev' => 'https://dev.example.org/' ], + ); + + + $logo_url @@ -408,8 +432,8 @@ $logo_label URI and label (title) for the Git logo link (or your site logo, if you chose to use different logo image). By default, these both - refer to git homepage, http://git-scm.com[]; in the past, they pointed - to git documentation at http://www.kernel.org[]. + refer to Git homepage, http://git-scm.com[]; in the past, they pointed + to Git documentation at http://www.kernel.org[]. @@ -578,7 +602,7 @@ $fallback_encoding detection. Note that rename and especially copy detection can be quite -CPU-intensive. Note also that non git tools can have problems with +CPU-intensive. Note also that non Git tools can have problems with patches generated with options mentioned above, especially when they involve file copies ('-C') or criss-cross renames ('-B'). @@ -600,7 +624,7 @@ affects how "summary" pages look like, or load limiting). - List of git base URLs. These URLs are used to generate URLs + List of Git base URLs. These URLs are used to generate URLs describing from where to fetch a project, which are shown on project summary page. The full fetch URL is "$git_base_url/$project", for each element of this list. You can set up multiple base URLs @@ -612,7 +636,7 @@ file, or as values of multi-value gitweb.url configuration project config. Per-repository configuration takes precedence over value composed from @git_base_url_list elements and project name. You can setup one single value (single entry/item in this list) at build -time by setting the GITWEB_BASE_URL built-time configuration variable. +time by setting the GITWEB_BASE_URL build-time configuration variable. By default it is set to (), i.e. an empty list. This means that gitweb would not try to create project URL (to fetch) from project name. @@ -623,7 +647,7 @@ $projects_list_group_categories - Whether to enables the grouping of projects by category on the project + Whether to enable the grouping of projects by category on the project list page. The category of a project is determined by the $GIT_DIR/category file or the gitweb.category variable in each repository's configuration. Disabled by default (set to 0). @@ -828,12 +852,12 @@ override If this field has a true value then the given feature is - overriddable, which means that it can be configured + overridable, which means that it can be configured (or enabled/disabled) on a per-repository basis. Usually given "<feature>" is configurable via the gitweb.<feature> -config variable in the per-repository git configuration file. -Note that no feature is overriddable by default. +config variable in the per-repository Git configuration file. +Note that no feature is overridable by default. @@ -937,7 +961,7 @@ show-sizes I/O. Enabled by default. This feature can be configured on a per-repository basis via -repository's gitweb.showsizes configuration variable (boolean). +repository's gitweb.showSizes configuration variable (boolean). @@ -1069,7 +1093,7 @@ filesystem (i.e. "$projectroot/$project"), %h to the curren ('h gitweb parameter) and %b` to the current hash base ('hb gitweb parameter); %%` expands to '%. For example, at the time this page was written, the http://repo.or.cz[] -git hosting site set it to the following to enable graphical log +Git hosting site set it to the following to enable graphical log (using the third party tool git-browser): $feature{'actions'}{'default'} = [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')]; @@ -1084,10 +1108,10 @@ timed - Enable displaying how much time and how many git commands it took to + Enable displaying how much time and how many Git commands it took to generate and display each page in the page footer (at the bottom of page). For example the footer might contain: "This page took 6.53325 - seconds and 13 git commands to generate." Disabled by default. + seconds and 13 Git commands to generate." Disabled by default. Project specific override is not supported. @@ -1098,27 +1122,59 @@ javascript-timezone - Enable and configure the ability to change a common timezone for dates + Enable and configure the ability to change a common time zone for dates in gitweb output via JavaScript. Dates in gitweb output include authordate and committerdate in "commit", "commitdiff" and "log" views, and taggerdate in "tag" view. Enabled by default. -The value is a list of three values: a default timezone (for if the client -hasn't selected some other timezone and saved it in a cookie), a name of cookie -where to store selected timezone, and a CSS class used to mark up +The value is a list of three values: a default time zone (for if the client +hasn't selected some other time zone and saved it in a cookie), a name of cookie +where to store selected time zone, and a CSS class used to mark up dates for manipulation. If you want to turn this feature off, set "default" to empty list: []. -Typical gitweb config files will only change starting (default) timezone, +Typical gitweb config files will only change starting (default) time zone, and leave other elements at their default values: $feature{'javascript-timezone'}{'default'}[0] = "utc"; The example configuration presented here is guaranteed to be backwards and forward compatible. -Timezone values can be "local" (for local timezone that browser uses), "utc" +Time zone values can be "local" (for local time zone that browser uses), "utc" (what gitweb uses when JavaScript or this feature is disabled), or numerical -timezones in the form of "+/-HHMM", such as "+0200". +time zones in the form of "+/-HHMM", such as "+0200". Project specific override is not supported. + + +extra-branch-refs + + + + List of additional directories under "refs" which are going to + be used as branch refs. For example if you have a gerrit setup + where all branches under refs/heads/ are official, + push-after-review ones and branches under refs/sandbox/, + refs/wip and refs/other are user ones where permissions are + much wider, then you might want to set this variable as + follows: + +$feature{'extra-branch-refs'}{'default'} = + ['sandbox', 'wip', 'other']; +This feature can be configured on per-repository basis after setting +$feature{extra-branch-refs}{override} to true, via repository's +gitweb.extraBranchRefs configuration variable, which contains a +space separated list of refs. An example: +[gitweb] + extraBranchRefs = sandbox wip other +The gitweb.extraBranchRefs is actually a multi-valued configuration +variable, so following example is also correct and the result is the +same as of the snippet above: +[gitweb] + extraBranchRefs = sandbox + extraBranchRefs = wip other +It is an error to specify a ref that does not pass "git check-ref-format" +scrutiny. Duplicated values are filtered. + +
@@ -1134,13 +1190,20 @@ $feature{'pickaxe'}{'override'} = 1; $feature{'snapshot'}{'default'} = ['zip', 'tgz']; $feature{'snapshot'}{'override'} = 1; If you allow overriding for the snapshot feature, you can specify which -snapshot formats are globally disabled. You can also add any command line +snapshot formats are globally disabled. You can also add any command-line options you want (such as setting the compression level). For instance, you can disable Zip compressed snapshots and set gzip(1) to run at level 6 by adding the following lines to your gitweb configuration file: $known_snapshot_formats{'zip'}{'disabled'} = 1; $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; + +BUGS +Debugging would be easier if the fallback configuration file +(/etc/gitweb.conf) and environment variable to override its location +(GITWEB_CONFIG_SYSTEM) had names reflecting their "fallback" role. +The current names are kept to avoid breaking working setups. + ENVIRONMENT The location of per-instance and system-wide configuration files can be diff --git a/doc/source/en/TortoiseGit/git_doc/gitweb.xml b/doc/source/en/TortoiseGit/git_doc/gitweb.xml index d9e5e25da..6c943a0cb 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitweb.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitweb.xml @@ -12,13 +12,13 @@ SYNOPSIS -To get started with gitweb, run from a git repository. +To get started with gitweb, run from a Git repository. This would configure and start your web server, and run web browser pointing to gitweb. DESCRIPTION -Gitweb provides a web interface to git repositories. Its features include: +Gitweb provides a web interface to Git repositories. Its features include: @@ -83,9 +83,9 @@ projects' root" subsection). our $projectroot = '/path/to/parent/directory'; The default value for $projectroot is /pub/git. You can change it during building gitweb via GITWEB_PROJECTROOT build configuration variable. -By default all git repositories under $projectroot are visible and available +By default all Git repositories under $projectroot are visible and available to gitweb. The list of projects is generated by default by scanning the -$projectroot directory for git repositories (for object databases to be +$projectroot directory for Git repositories (for object databases to be more exact; gitweb is not interested in a working area, and is best suited to showing "bare" repositories). The name of the repository in gitweb is the path to its $GIT_DIR (its object @@ -121,7 +121,7 @@ separator (rules for Perl's "split(" ", $line)"). Fields use modified URI encoding, defined in RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding" (see -URL_encoding), the difference +http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference being that SP (" ") can be encoded as "+" (and therefore "+" has to be also percent-encoded). @@ -165,7 +165,7 @@ Currently recognized fields are: foo.git Joe+R+Hacker+<joe@example.com> foo/bar.git O+W+Ner+<owner@example.org> By default this file controls only which projects are visible on projects -list page (note that entries that do not point to correctly recognized git +list page (note that entries that do not point to correctly recognized Git repositories won't be displayed by gitweb). Even if a project is not visible on projects list page, you can view it nevertheless by hand-crafting a gitweb URL. By setting $strict_export configuration variable (see @@ -196,8 +196,8 @@ as projects list file, which means that you can set $projects_list
-Controlling access to git repositories -By default all git repositories under $projectroot are visible and +Controlling access to Git repositories +By default all Git repositories under $projectroot are visible and available to gitweb. You can however configure how gitweb controls access to repositories. @@ -251,7 +251,7 @@ authorized to read the files:
Per-repository gitweb configuration You can configure individual repositories shown in gitweb by creating file -in the GIT_DIR of git repository, or by setting some repo configuration +in the GIT_DIR of Git repository, or by setting some repo configuration variable (in GIT_DIR/config, see ). You can use the following files in repository: @@ -692,7 +692,7 @@ repositories, you can configure Apache like this: </VirtualHost> The above configuration expects your public repositories to live under /pub/git and will serve them as http://git.domain.org/dir-under-pub-git, -both as cloneable GIT URL and as browseable gitweb interface. If you then +both as clonable Git URL and as browseable gitweb interface. If you then start your with --base-path=/pub/git --export-all then you can even use the git:// URL with exactly the same path. Setting the environment variable GITWEB_CONFIG will tell gitweb to use the @@ -760,7 +760,7 @@ line in gitweb configuration file (/etc/gitweb.conf in abov $per_request_config must be false, or the above must be put in code referenced by $per_request_config; These configurations enable two things. First, each unix user (<user>) of -the server will be able to browse through gitweb git repositories found in +the server will be able to browse through gitweb Git repositories found in ~/public_git/ with the following url: http://git.example.org/~<user>/ If you do not want this feature on your server just remove the second @@ -831,7 +831,7 @@ named without a .git extension (e.g. The additional AliasMatch makes it so that http://git.example.com/project.git -will give raw access to the project's git dir (so that the project can be +will give raw access to the project's Git dir (so that the project can be cloned), while http://git.example.com/project will provide human-friendly gitweb access. diff --git a/doc/source/en/TortoiseGit/git_doc/gitworkflows.xml b/doc/source/en/TortoiseGit/git_doc/gitworkflows.xml index 5a286491a..ad244a9e4 100644 --- a/doc/source/en/TortoiseGit/git_doc/gitworkflows.xml +++ b/doc/source/en/TortoiseGit/git_doc/gitworkflows.xml @@ -8,7 +8,7 @@ NAME -gitworkflows - An overview of recommended workflows with git +gitworkflows - An overview of recommended workflows with Git SYNOPSIS @@ -224,9 +224,9 @@ will therefore not be included in your feature release. tag to the tip of master indicating the release version: Release tagging -git tag -s -m "GIT X.Y.Z" vX.Y.Z master +git tag -s -m "Git X.Y.Z" vX.Y.Z master -You need to push the new tag to a public git server (see +You need to push the new tag to a public Git server (see "DISTRIBUTED WORKFLOWS" below). This makes the tag available to others tracking your project. The push could also trigger a post-update hook to perform release-related items such as building diff --git a/doc/source/en/TortoiseGit/git_doc/user-manual.xml b/doc/source/en/TortoiseGit/git_doc/user-manual.xml index 4d4b17a26..9d0d235af 100644 --- a/doc/source/en/TortoiseGit/git_doc/user-manual.xml +++ b/doc/source/en/TortoiseGit/git_doc/user-manual.xml @@ -2,63 +2,63 @@ - Git User's Manual (for version 1.5.3 or newer) + Git User Manual Git is a fast distributed revision control system. This manual is designed to be readable by someone with basic UNIX -command-line skills, but no previous knowledge of git. - and explain how +command-line skills, but no previous knowledge of Git. + and explain how to fetch and study a project using git--read these chapters to learn how to build and test a particular version of a software project, search for regressions, and so on. People needing to do actual development will also want to read - and . + and . Further chapters cover more specialized topics. Comprehensive reference documentation is available through the man pages, or command. For example, for the command -"git clone <repo>", you can either use: +git clone <repo>, you can either use: $ man git-clone or: $ git help clone With the latter, you can use the manual viewer of your choice; see for more information. -See also for a brief overview of git commands, +See also for a brief overview of Git commands, without any explanation. -Finally, see for ways that you can help make this manual more +Finally, see for ways that you can help make this manual more complete. -
+
Repositories and Branches -
-How to get a git repository -It will be useful to have a git repository to experiment with as you +
+How to get a Git repository +It will be useful to have a Git repository to experiment with as you read this manual. The best way to get one is by using the command to download a copy of an existing repository. If you don't already have a project in mind, here are some interesting examples: - # git itself (approx. 10MB download): + # Git itself (approx. 40MB download): $ git clone git://git.kernel.org/pub/scm/git/git.git - # the Linux kernel (approx. 150MB download): -$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git + # the Linux kernel (approx. 640MB download): +$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git The initial clone may be time-consuming for a large project, but you will only need to clone once. -The clone command creates a new directory named after the project ("git" -or "linux-2.6" in the examples above). After you cd into this +The clone command creates a new directory named after the project +(git or linux in the examples above). After you cd into this directory, you will see that it contains a copy of the project files, -called the working tree, together with a special -top-level directory named ".git", which contains all the information +called the working tree, together with a special +top-level directory named .git, which contains all the information about the history of the project.
-
+
How to check out a different version of a project Git is best thought of as a tool for storing the history of a collection of files. It stores the history as a compressed collection of -interrelated snapshots of the project's contents. In git each such -version is called a commit. +interrelated snapshots of the project's contents. In Git each such +version is called a commit. Those snapshots aren't necessarily all arranged in a single line from oldest to newest; instead, work may simultaneously proceed along -parallel lines of development, called branches, which may +parallel lines of development, called branches, which may merge and diverge. -A single git repository can track development on multiple branches. It -does this by keeping a list of heads which reference the +A single Git repository can track development on multiple branches. It +does this by keeping a list of heads which reference the latest commit on each branch; the command shows you the list of branch heads: $ git branch @@ -66,7 +66,7 @@ you the list of branch heads: A freshly cloned repository contains a single branch head, by default named "master", with the working directory initialized to the state of the project referred to by that branch head. -Most projects also use tags. Tags, like heads, are +Most projects also use tags. Tags, like heads, are references into the project's history, and can be listed using the command: $ git tag -l @@ -99,7 +99,7 @@ particular point in history, then resetting that branch may leave you with no way to find the history it used to point to; so use this command carefully.
-
+
Understanding History: Commits Every change in the history of a project is represented by a commit. The command shows the most recent commit on the @@ -129,7 +129,7 @@ index 65898fa..b002dc6 100644 As you can see, a commit shows who made the latest change, what they did, and why. Every commit has a 40-hexdigit id, sometimes called the "object name" or the -"SHA-1 id", shown on the first line of the "git show" output. You can usually +"SHA-1 id", shown on the first line of the git show output. You can usually refer to a commit by a shorter name, such as a tag or a branch name, but this longer name can also be useful. Most importantly, it is a globally unique name for this commit: so if you tell somebody else the object name (for @@ -138,32 +138,32 @@ commit in their repository that it does in yours (assuming their repository has that commit at all). Since the object name is computed as a hash over the contents of the commit, you are guaranteed that the commit can never change without its name also changing. -In fact, in we shall see that everything stored in git +In fact, in we shall see that everything stored in Git history, including file data and directory contents, is stored in an object with a name that is a hash of its contents. -
+
Understanding history: commits, parents, and reachability Every commit (except the very first commit in a project) also has a parent commit which shows what happened before this commit. Following the chain of parents will eventually take you back to the beginning of the project. -However, the commits do not form a simple list; git allows lines of +However, the commits do not form a simple list; Git allows lines of development to diverge and then reconverge, and the point where two lines of development reconverge is called a "merge". The commit representing a merge can therefore have more than one parent, with each parent representing the most recent commit on one of the lines of development leading to that point. The best way to see how this works is using the -command; running gitk now on a git repository and looking for merge -commits will help understand how the git organizes history. +command; running gitk now on a Git repository and looking for merge +commits will help understand how Git organizes history. In the following, we say that commit X is "reachable" from commit Y if commit X is an ancestor of commit Y. Equivalently, you could say that Y is a descendant of X, or that there is a chain of parents leading from commit Y to commit X.
-
+
Understanding history: History diagrams -We will sometimes represent git history using diagrams like the one +We will sometimes represent Git history using diagrams like the one below. Commits are shown as "o", and the links between them with lines drawn with - / and \. Time goes left to right: o--o--o <-- Branch A @@ -174,7 +174,7 @@ lines drawn with - / and \. Time goes left to right: If we need to talk about a particular commit, the character "o" may be replaced with another letter or number.
-
+
Understanding history: What is a branch? When we need to be precise, we will use the word "branch" to mean a line of development, and "branch head" (or just "head") to mean a reference @@ -186,130 +186,133 @@ the line of three commits leading up to that point as all being part of "branch" both for branches and for branch heads.
-
+
Manipulating branches Creating, deleting, and modifying branches is quick and easy; here's a summary of the commands: -git branch +git branch - list all branches + list all branches. -git branch <branch> +git branch <branch> - create a new branch named <branch>, referencing the same - point in history as the current branch + create a new branch named <branch>, referencing the same + point in history as the current branch. -git branch <branch> <start-point> +git branch <branch> <start-point> - create a new branch named <branch>, referencing - <start-point>, which may be specified any way you like, - including using a branch name or a tag name + create a new branch named <branch>, referencing + <start-point>, which may be specified any way you like, + including using a branch name or a tag name. -git branch -d <branch> +git branch -d <branch> - delete the branch <branch>; if the branch you are deleting - points to a commit which is not reachable from the current - branch, this command will fail with a warning. + delete the branch <branch>; if the branch is not fully + merged in its upstream branch or contained in the current branch, + this command will fail with a warning. -git branch -D <branch> +git branch -D <branch> - even if the branch points to a commit not reachable - from the current branch, you may know that that commit - is still reachable from some other branch or tag. In that - case it is safe to use this command to force git to delete - the branch. + delete the branch <branch> irrespective of its merged status. -git checkout <branch> +git checkout <branch> - make the current branch <branch>, updating the working - directory to reflect the version referenced by <branch> + make the current branch <branch>, updating the working + directory to reflect the version referenced by <branch>. -git checkout -b <new> <start-point> +git checkout -b <new> <start-point> - create a new branch <new> referencing <start-point>, and + create a new branch <new> referencing <start-point>, and check it out. The special symbol "HEAD" can always be used to refer to the current -branch. In fact, git uses a file named "HEAD" in the .git directory to -remember which branch is current: +branch. In fact, Git uses a file named HEAD in the .git directory +to remember which branch is current: $ cat .git/HEAD ref: refs/heads/master
-
+
Examining an old version without creating a new branch The git checkout command normally expects a branch head, but will also accept an arbitrary commit; for example, you can check out the commit referenced by a tag: $ git checkout v2.6.17 -Note: moving to "v2.6.17" which isn't a local branch -If you want to create a new branch from this checkout, you may do so -(now or later) by using -b with the checkout command again. Example: - git checkout -b <new_branch_name> +Note: checking out 'v2.6.17'. + +You are in 'detached HEAD' state. You can look around, make experimental +changes and commit them, and you can discard any commits you make in this +state without impacting any branches by performing another checkout. + +If you want to create a new branch to retain commits you create, you may +do so (now or later) by using -b with the checkout command again. Example: + + git checkout -b new_branch_name + HEAD is now at 427abfa... Linux v2.6.17 The HEAD then refers to the SHA-1 of the commit instead of to a branch, and git branch shows that you are no longer on a branch: $ cat .git/HEAD 427abfa28afedffadfca9dd8b067eb6d36bac53f $ git branch -* (no branch) +* (detached from v2.6.17) master In this case we say that the HEAD is "detached". This is an easy way to check out a particular version without having to make up a name for the new branch. You can still create a new branch (or tag) for this version later if you decide to.
-
+
Examining branches from a remote repository The "master" branch that was created at the time you cloned is a copy of the HEAD in the repository that you cloned from. That repository may also have had other branches, though, and your local repository keeps branches which track each of those remote branches, called remote-tracking branches, which you -can view using the "-r" option to : +can view using the -r option to : $ git branch -r origin/HEAD origin/html @@ -323,94 +326,99 @@ can view using the "-r" option to : for short. The branches of this repository are called "remote branches" from our point of view. The remote-tracking branches listed above were created based on the remote branches at clone time and will -be updated by "git fetch" (hence "git pull") and "git push". See - for details. +be updated by git fetch (hence git pull) and git push. See + for details. You might want to build on one of these remote-tracking branches on a branch of your own, just as you would for a tag: $ git checkout -b my-todo-copy origin/todo -You can also check out "origin/todo" directly to examine it or -write a one-off patch. See detached head. -Note that the name "origin" is just the name that git uses by default +You can also check out origin/todo directly to examine it or +write a one-off patch. See detached head. +Note that the name "origin" is just the name that Git uses by default to refer to the repository that you cloned from.
-
+
Naming branches, tags, and other references Branches, remote-tracking branches, and tags are all references to commits. All references are named with a slash-separated path name -starting with "refs"; the names we've been using so far are actually +starting with refs; the names we've been using so far are actually shorthand: -The branch "test" is short for "refs/heads/test". +The branch test is short for refs/heads/test. -The tag "v2.6.18" is short for "refs/tags/v2.6.18". +The tag v2.6.18 is short for refs/tags/v2.6.18. -"origin/master" is short for "refs/remotes/origin/master". +origin/master is short for refs/remotes/origin/master. The full name is occasionally useful if, for example, there ever exists a tag and a branch with the same name. -(Newly created refs are actually stored in the .git/refs directory, +(Newly created refs are actually stored in the .git/refs directory, under the path given by their name. However, for efficiency reasons they may also be packed together in a single file; see ). As another useful shortcut, the "HEAD" of a repository can be referred to just using the name of that repository. So, for example, "origin" is usually a shortcut for the HEAD branch in the repository "origin". -For the complete list of paths which git checks for references, and +For the complete list of paths which Git checks for references, and the order it uses to decide which to choose when there are multiple references with the same shorthand name, see the "SPECIFYING REVISIONS" section of .
-
+
Updating a repository with git fetch -Eventually the developer cloned from will do additional work in her -repository, creating new commits and advancing the branches to point -at the new commits. -The command "git fetch", with no arguments, will update all of the -remote-tracking branches to the latest version found in her +After you clone a repository and commit a few changes of your own, you +may wish to check the original repository for updates. +The git-fetch command, with no arguments, will update all of the +remote-tracking branches to the latest version found in the original repository. It will not touch any of your own branches--not even the "master" branch that was created for you on clone.
-
+
Fetching branches from other repositories You can also track branches from repositories other than the one you cloned from, using : -$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git -$ git fetch linux-nfs -* refs/remotes/linux-nfs/master: storing branch 'master' ... - commit: bf81b46 +$ git remote add staging git://git.kernel.org/.../gregkh/staging.git +$ git fetch staging +... +From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging + * [new branch] master -> staging/master + * [new branch] staging-linus -> staging/staging-linus + * [new branch] staging-next -> staging/staging-next New remote-tracking branches will be stored under the shorthand name -that you gave "git remote add", in this case linux-nfs: +that you gave git remote add, in this case staging: $ git branch -r -linux-nfs/master -origin/master -If you run "git fetch <remote>" later, the remote-tracking branches for the -named <remote> will be updated. -If you examine the file .git/config, you will see that git has added + origin/HEAD -> origin/master + origin/master + staging/master + staging/staging-linus + staging/staging-next +If you run git fetch <remote> later, the remote-tracking branches +for the named <remote> will be updated. +If you examine the file .git/config, you will see that Git has added a new stanza: $ cat .git/config ... -[remote "linux-nfs"] - url = git://linux-nfs.org/pub/nfs-2.6.git - fetch = +refs/heads/*:refs/remotes/linux-nfs/* +[remote "staging"] + url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git + fetch = +refs/heads/*:refs/remotes/staging/* ... -This is what causes git to track the remote's branches; you may modify -or delete these configuration options by editing .git/config with a +This is what causes Git to track the remote's branches; you may modify +or delete these configuration options by editing .git/config with a text editor. (See the "CONFIGURATION FILE" section of for details.)
-
-Exploring git history +
+Exploring Git history Git is best thought of as a tool for storing the history of a collection of files. It does this by storing compressed snapshots of the contents of a file hierarchy, together with "commits" which show @@ -419,7 +427,7 @@ the relationships between these snapshots. history of a project. We start with one specialized tool that is useful for finding the commit that introduced a bug into a project. -
+
How to use bisect to find a regression Suppose version 2.6.18 of your project worked, but the version at "master" crashes. Sometimes the best way to find the cause of such a @@ -431,7 +439,7 @@ $ git bisect good v2.6.18 $ git bisect bad master Bisecting: 3537 revisions left to test after this [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6] -If you run "git branch" at this point, you'll see that git has +If you run git branch at this point, you'll see that Git has temporarily moved you in "(no branch)". HEAD is now detached from any branch and points directly to a commit (with commit id 65934…) that is reachable from "master" but not from v2.6.18. Compile and test it, @@ -439,7 +447,7 @@ and see whether it crashes. Assume it does crash. Then: $ git bisect bad Bisecting: 1769 revisions left to test after this [7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings -checks out an older version. Continue like this, telling git at each +checks out an older version. Continue like this, telling Git at each stage whether the version it gives you is good or bad, and notice that the number of revisions left to test is cut approximately in half each time. @@ -459,20 +467,20 @@ run says "bisect". Choose a safe-looking commit nearby, note its commit id, and check it out with: $ git reset --hard fb47ddb2db... -then test, run "bisect good" or "bisect bad" as appropriate, and +then test, run bisect good or bisect bad as appropriate, and continue. -Instead of "git bisect visualize" and then "git reset --hard -fb47ddb2db…", you might just want to tell git that you want to skip +Instead of git bisect visualize and then git reset --hard +fb47ddb2db..., you might just want to tell Git that you want to skip the current commit: $ git bisect skip -In this case, though, git may not eventually be able to tell the first +In this case, though, Git may not eventually be able to tell the first bad one between some first skipped commits and a later bad commit. There are also ways to automate the bisecting process if you have a test script that can tell a good from a bad commit. See - for more information about this and other "git -bisect" features. + for more information about this and other git +bisect features.
-
+
Naming commits We have seen several ways of naming commits already: @@ -491,7 +499,7 @@ branch name: refers to the commit at the head of the given tag name: refers to the commit pointed to by the given tag (we've seen branches and tags are special cases of - references). + references). @@ -509,7 +517,7 @@ $ git show HEAD^ # the parent of the HEAD commit $ git show HEAD^^ # the grandparent $ git show HEAD~4 # the great-great-grandparent Recall that merge commits may have more than one parent; by default, -^ and ~ follow the first parent listed in the commit, but you can +^ and ~ follow the first parent listed in the commit, but you can also choose: $ git show HEAD^1 # show the first parent of HEAD $ git show HEAD^2 # show the second parent of HEAD @@ -532,18 +540,18 @@ name for that commit: $ git rev-parse origin e05db0fd4f31dde7005f075a84f96b360d05984b
-
+
Creating tags We can also create a tag to refer to a particular commit; after running $ git tag stable-1 1b2e1d63ff -You can use stable-1 to refer to the commit 1b2e1d63ff. +You can use stable-1 to refer to the commit 1b2e1d63ff. This creates a "lightweight" tag. If you would also like to include a comment with the tag, and possibly sign it cryptographically, then you should create a tag object instead; see the man page for details.
-
+
Browsing revisions The command can show lists of commits. On its own, it shows all commits reachable from the parent commit; but you @@ -559,18 +567,18 @@ $ git log fs/ # ... which modify any file under fs/ $ git log -S'foo()' # commits which add or remove any file data # matching the string 'foo()' And of course you can combine all of these; the following finds -commits since v2.5 which touch the Makefile or any file under fs: +commits since v2.5 which touch the Makefile or any file under fs: $ git log v2.5.. Makefile fs/ You can also ask git log to show patches: $ git log -p -See the "--pretty" option in the man page for more +See the --pretty option in the man page for more display options. Note that git log starts with the most recent commit and works -backwards through the parents; however, since git history can contain +backwards through the parents; however, since Git history can contain multiple independent lines of development, the particular order that commits are listed in may be somewhat arbitrary.
-
+
Generating diffs You can generate diffs between any two versions using : @@ -585,7 +593,7 @@ use : will generate a file with a patch for each commit reachable from test but not from master.
-
+
Viewing old file versions You can always view an old version of a file by just checking out the correct revision first. But sometimes it is more convenient to be @@ -593,21 +601,21 @@ able to view an old version of a single file without checking anything out; this command does that: $ git show v2.5:fs/locks.c Before the colon may be anything that names a commit, and after it -may be any path to a file tracked by git. +may be any path to a file tracked by Git.
-
+
Examples -
+
Counting the number of commits on a branch -Suppose you want to know how many commits you've made on "mybranch" -since it diverged from "origin": +Suppose you want to know how many commits you've made on mybranch +since it diverged from origin: $ git log --pretty=oneline origin..mybranch | wc -l Alternatively, you may often see this sort of thing done with the lower-level command , which just lists the SHA-1's of all the given commits: $ git rev-list origin..mybranch | wc -l
-
+
Check whether two branches point at the same history Suppose you want to check whether two branches point at the same point in history. @@ -620,13 +628,13 @@ routes. You could compare the object names: e05db0fd4f31dde7005f075a84f96b360d05984b $ git rev-list master e05db0fd4f31dde7005f075a84f96b360d05984b -Or you could recall that the … operator selects all commits -contained reachable from either one reference or the other but not -both: so +Or you could recall that the ... operator selects all commits +reachable from either one reference or the other but not +both; so $ git log origin...master will return no commits when the two branches are equal.
-
+
Find first tagged version including a given fix Suppose you know that the commit e05db0fd fixed a certain problem. You'd like to find the earliest tagged release that contains that @@ -636,7 +644,7 @@ after commit e05db0fd, then there could be multiple "earliest" tagged releases. You could just visually inspect the commits since e05db0fd: $ gitk e05db0fd.. -Or you can use , which will give the commit a +or you can use , which will give the commit a name based on any tag it finds pointing to one of the commit's descendants: $ git name-rev --tags e05db0fd @@ -661,8 +669,8 @@ actually is an ancestor of v1.5.0-rc1. because it outputs only commits that are not reachable from v1.5.0-rc1. As yet another alternative, the command lists the commits reachable from its arguments with a display on the left-hand -side that indicates which arguments that commit is reachable from. So, -you can run something like +side that indicates which arguments that commit is reachable from. +So, if you run something like $ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2 ! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if available @@ -670,16 +678,16 @@ available ! [v1.5.0-rc1] GIT v1.5.0-rc1 ! [v1.5.0-rc2] GIT v1.5.0-rc2 ... -then search for a line that looks like +then a line like + ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if available -Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and -from v1.5.0-rc2, but not from v1.5.0-rc0. +shows that e05db0fd is reachable from itself, from v1.5.0-rc1, +and from v1.5.0-rc2, and not from v1.5.0-rc0.
-
+
Showing commits unique to a given branch Suppose you would like to see all the commits reachable from the branch -head named "master" but not from any other head in your repository. +head named master but not from any other head in your repository. We can list all the heads in this repository with : $ git show-ref --heads @@ -688,7 +696,7 @@ db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master 24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2 1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes -We can get just the branch-head names, and remove "master", with +We can get just the branch-head names, and remove master, with the help of the standard utilities cut and grep: $ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master' refs/heads/core-tutorial @@ -705,13 +713,18 @@ commits reachable from some head but not from any tag in the repository:(See for explanations of commit-selecting syntax such as --not.)
-
+
Creating a changelog and tarball for a software release The command can create a tar or zip archive from any version of a project; for example: +$ git archive -o latest.tar.gz --prefix=project/ HEAD +will use HEAD to produce a gzipped tar archive in which each filename +is preceded by project/. The output file format is inferred from +the output file extension if possible, see for +details. +Versions of Git older than 1.7.7 don't know about the tar.gz format, +you'll need to use gzip explicitly: $ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz -will use HEAD to produce a tar archive in which each filename is -preceded by "project/". If you're releasing a new version of a software project, you may want to simultaneously make a changelog to include in the release announcement. @@ -732,7 +745,7 @@ echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"and then he just cut-and-pastes the output commands after verifying that they look OK.
-
+
Finding commits referencing a file with given content Somebody hands you a copy of a file, and asks which commits modified a file such that it contained the given content either before or after the @@ -745,20 +758,24 @@ student. The ,
-
-Developing with git -
-Telling git your name -Before creating any commits, you should introduce yourself to git. The -easiest way to do so is to make sure the following lines appear in a -file named .gitconfig in your home directory: +
+Developing with Git +
+Telling Git your name +Before creating any commits, you should introduce yourself to Git. +The easiest way to do so is to use : +$ git config --global user.name 'Your Name Comes Here' +$ git config --global user.email 'you@yourdomain.example.com' +Which will add the following to a file named .gitconfig in your +home directory: [user] name = Your Name Comes Here email = you@yourdomain.example.com -(See the "CONFIGURATION FILE" section of for -details on the configuration file.) +See the "CONFIGURATION FILE" section of for +details on the configuration file. The file is plain text, so you can +also edit it with your favorite editor.
-
+
Creating a new repository Creating a new repository from scratch is very easy: $ mkdir project @@ -771,7 +788,7 @@ $ git init $ git add . # include everything below ./ in the first commit: $ git commit
-
+
How to make a commit Creating a new commit takes three steps: @@ -783,30 +800,28 @@ Making some changes to the working directory using your -Telling git about your changes. +Telling Git about your changes. -Creating the commit using the content you told git about +Creating the commit using the content you told Git about in step 2. In practice, you can interleave and repeat steps 1 and 2 as many times as you want: in order to keep track of what you want committed -at step 3, git maintains a snapshot of the tree's contents in a +at step 3, Git maintains a snapshot of the tree's contents in a special staging area called "the index." At the beginning, the content of the index will be identical to -that of the HEAD. The command "git diff --cached", which shows +that of the HEAD. The command git diff --cached, which shows the difference between the HEAD and the index, should therefore produce no output at that point. Modifying the index is easy: -To update the index with the new contents of a modified file, use -$ git add path/to/file -To add the contents of a new file to the index, use +To update the index with the contents of a new or modified file, use $ git add path/to/file -To remove a file from the index and from the working tree, +To remove a file from the index and from the working tree, use $ git rm path/to/file After each step you can verify that $ git diff --cached @@ -814,12 +829,12 @@ produce no output at that point. is what you'd commit if you created the commit now--and that $ git diff shows the difference between the working tree and the index file. -Note that "git add" always adds just the current contents of a file +Note that git add always adds just the current contents of a file to the index; further changes to the same file will be ignored unless you run git add on the file again. When you're ready, just run $ git commit -and git will prompt you for a commit message and then create the new +and Git will prompt you for a commit message and then create the new commit. Check to make sure it looks like what you expected with $ git show As a special shortcut, @@ -841,28 +856,29 @@ the index and the working tree files, and individually select diff hunks for inclusion in the index (by right-clicking on the diff hunk and choosing "Stage Hunk For Commit").
-
+
Creating good commit messages Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used -throughout git. For example, turns a +throughout Git. For example, turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.
-
+
Ignoring files -A project will often generate files that you do not want to track with git. +A project will often generate files that you do not want to track with Git. This typically includes files generated by a build process or temporary -backup files made by your editor. Of course, not tracking files with git +backup files made by your editor. Of course, not tracking files with Git is just a matter of not calling git add on them. But it quickly becomes annoying to have these untracked files lying around; e.g. they make git add . practically useless, and they keep showing up in the output of git status. -You can tell git to ignore certain files by creating a file called .gitignore -in the top level of your working directory, with contents such as: +You can tell Git to ignore certain files by creating a file called +.gitignore in the top level of your working directory, with contents +such as: # Lines starting with '#' are considered comments. # Ignore any file named foo.txt. foo.txt @@ -881,19 +897,19 @@ patterns (such as patterns matching build output files) would also make sense for other users who clone your repository. If you wish the exclude patterns to affect only certain repositories (instead of every repository for a given project), you may instead put -them in a file in your repository named .git/info/exclude, or in any file -specified by the core.excludesfile configuration variable. Some git -commands can also take exclude patterns directly on the command line. -See for the details. +them in a file in your repository named .git/info/exclude, or in any +file specified by the core.excludesFile configuration variable. +Some Git commands can also take exclude patterns directly on the +command line. See for the details.
-
+
How to merge You can rejoin two diverging branches of development using : $ git merge branchname -merges the development in the branch "branchname" into the current +merges the development in the branch branchname into the current branch. -A merge is made by combining the changes made in "branchname" and the +A merge is made by combining the changes made in branchname and the changes made up to the latest commit in your current branch since their histories forked. The work tree is overwritten by the result of the merge when this combining is done cleanly, or overwritten by a @@ -905,7 +921,7 @@ and if you don't, then can take these changes away while you're doing the merge, and reapply them afterwards. If the changes are independent enough, Git will automatically complete the merge and commit the result (or reuse an existing commit in case -of fast-forward, see below). On the other hand, +of fast-forward, see below). On the other hand, if there are conflicts--for example, if the same file is modified in two different ways in the remote branch and the local branch--then you are warned; the output may look something like this: @@ -916,15 +932,15 @@ CONFLICT (content): Merge conflict in file.txt Automatic merge failed; fix conflicts and then commit the result. Conflict markers are left in the problematic files, and after you resolve the conflicts manually, you can update the index -with the contents and run git commit, as you normally would when +with the contents and run Git commit, as you normally would when creating a new file. If you examine the resulting commit using gitk, you will see that it has two parents, one pointing to the top of the current branch, and one to the top of the other branch.
-
+
Resolving a merge -When a merge isn't resolved automatically, git leaves the index and +When a merge isn't resolved automatically, Git leaves the index and the working tree in a special state that gives you all the information you need to help resolve the merge. Files with conflicts are marked specially in the index, so until you @@ -946,11 +962,11 @@ $ git commit some information about the merge. Normally you can just use this default message unchanged, but you may add additional commentary of your own if desired. -The above is all you need to know to resolve a simple merge. But git +The above is all you need to know to resolve a simple merge. But Git also provides more information to help resolve conflicts: -
+
Getting conflict-resolution help during a merge -All of the changes that git was able to merge automatically are +All of the changes that Git was able to merge automatically are already added to the index file, so shows only the conflicts. It uses an unusual syntax: $ git diff @@ -980,7 +996,7 @@ mixed (in other words, when a hunk's merge results come only from stage 2, that part is not conflicting and is not shown. Same for stage 3). The diff above shows the differences between the working-tree version of file.txt and the stage 2 and stage 3 versions. So instead of preceding -each line by a single "+" or "-", it now uses two columns: the first +each line by a single + or -, it now uses two columns: the first column is used for differences between the first parent and the working directory copy, and the second for differences between the second parent and the working directory copy. (See the "COMBINED DIFF FORMAT" section @@ -1021,7 +1037,7 @@ unmerged files using external tools such as Emacs or kdiff3. git diff will (by default) no longer show diffs for that file.
-
+
Undoing a merge If you get stuck and decide to just give up and throw the whole mess away, you can always return to the pre-merge state with @@ -1033,19 +1049,19 @@ throw away a commit you have already committed if that commit may itself have been merged into another branch, as doing so may confuse further merges.
-
+
Fast-forward merges There is one special case not mentioned above, which is treated differently. Normally, a merge results in a merge commit, with two parents, one pointing at each of the two lines of development that were merged. -However, if the current branch is a descendant of the other--so every -commit present in the one is already contained in the other--then git -just performs a "fast-forward"; the head of the current branch is moved -forward to point at the head of the merged-in branch, without any new -commits being created. +However, if the current branch is an ancestor of the other--so every commit +present in the current branch is already contained in the other branch--then Git +just performs a "fast-forward"; the head of the current branch is moved forward +to point at the head of the merged-in branch, without any new commits being +created.
-
+
Fixing mistakes If you've messed up the working tree, but haven't yet committed your mistake, you can return the entire working tree to the last committed @@ -1065,13 +1081,13 @@ You can create a new commit that undoes whatever was done You can go back and modify the old commit. You should never do this if you have already made the history public; - git does not normally expect the "history" of a project to + Git does not normally expect the "history" of a project to change, and cannot correctly perform repeated merges from a branch that has had its history changed. -
+
Fixing a mistake with a new commit Creating a new commit that reverts an earlier change is very easy; just pass the command a reference to the bad @@ -1081,19 +1097,19 @@ commit; for example, to revert the most recent commit: will be given a chance to edit the commit message for the new commit. You can also revert an earlier change, for example, the next-to-last: $ git revert HEAD^ -In this case git will attempt to undo the old change while leaving +In this case Git will attempt to undo the old change while leaving intact any changes made since then. If more recent changes overlap with the changes to be reverted, then you will be asked to fix -conflicts manually, just as in the case of resolving a merge. +conflicts manually, just as in the case of resolving a merge.
-
+
Fixing a mistake by rewriting history If the problematic commit is the most recent commit, and you have not yet made that commit public, then you may just -destroy it using git reset. +destroy it using git reset. Alternatively, you can edit the working directory and update the index to fix your -mistake, just as if you were going to create a new commit, then run +mistake, just as if you were going to create a new commit, then run $ git commit --amend which will replace the old commit by a new commit incorporating your changes, giving you a chance to edit the old commit message first. @@ -1102,9 +1118,9 @@ been merged into another branch; use instead in that case. It is also possible to replace commits further back in the history, but this is an advanced topic to be left for -another chapter. +another chapter.
-
+
Checking out an old version of a file In the process of undoing a previous bad change, you may find it useful to check out an older version of a particular file using @@ -1120,7 +1136,7 @@ modifying the working directory, you can do that with $ git show HEAD^:path/to/file which will display the given version of the file.
-
+
Temporarily setting aside work in progress While you are in the middle of working on something complicated, you find an unrelated but obvious and trivial bug. You would like to fix it @@ -1139,19 +1155,18 @@ $ git commit -a -m "blorpl: typofix" $ git stash pop
-
+
Ensuring good performance -On large repositories, git depends on compression to keep the history -information from taking up too much space on disk or in memory. -This compression is not performed automatically. Therefore you -should occasionally run : -$ git gc -to recompress the archive. This can be very time-consuming, so -you may prefer to run git gc when you are not doing other work. +On large repositories, Git depends on compression to keep the history +information from taking up too much space on disk or in memory. Some +Git commands may automatically run , so you don't +have to worry about running it manually. However, compressing a large +repository may take a while, so you may want to call gc explicitly +to avoid automatic compression kicking in when it is not convenient.
-
+
Ensuring reliability -
+
Checking the repository for corruption The command runs a number of self-consistency checks on the repository, and reports on any problems. This may take some @@ -1168,24 +1183,24 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f ... You will see informational messages on dangling objects. They are objects that still exist in the repository but are no longer referenced by any of -your branches, and can (and will) be removed after a while with "gc". +your branches, and can (and will) be removed after a while with gc. You can run git fsck --no-dangling to suppress these messages, and still view real errors.
-
+
Recovering lost changes
Reflogs -Say you modify a branch with --hard, and then -realize that the branch was the only reference you had to that point in -history. -Fortunately, git also keeps a log, called a "reflog", of all the +Say you modify a branch with git reset --hard, +and then realize that the branch was the only reference you had to +that point in history. +Fortunately, Git also keeps a log, called a "reflog", of all the previous values of each branch. So in this case you can still find the old history using, for example, $ git log master@{1} This lists the commits reachable from the previous version of the -"master" branch head. This syntax can be used with any git command -that accepts a commit, not just with git log. Some other examples: +master branch head. This syntax can be used with any Git command +that accepts a commit, not just with git log. Some other examples: $ git show master@{2} # See where the branch pointed 2, $ git show master@{3} # 3, ... changes ago. $ gitk master@{yesterday} # See where it pointed yesterday, @@ -1200,7 +1215,7 @@ you've checked out. pruned. See and to learn how to control this pruning, and see the "SPECIFYING REVISIONS" section of for details. -Note that the reflog history is very different from normal git history. +Note that the reflog history is very different from normal Git history. While normal history is shared by every repository that works on the same project, the reflog history is not shared: it tells you only about how the branches in your local repository have changed over time. @@ -1212,7 +1227,7 @@ suppose you delete a branch, then realize you need the history it contained. The reflog is also deleted; however, if you have not yet pruned the repository, then you may still be able to find the lost commits in the dangling objects that git fsck reports. See - for the details. + for the details. $ git fsck dangling commit 7281251ddd2a61e38657c827739c57015671a6b3 dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63 @@ -1237,14 +1252,14 @@ dangling objects can arise in other situations.
-
+
Sharing development with others -
+
Getting updates with git pull After you clone a repository and commit a few changes of your own, you may wish to check the original repository for updates and merge them into your own work. -We have already seen how to keep remote-tracking branches up to date with , +We have already seen how to keep remote-tracking branches up to date with , and how to merge two branches. So you can merge in changes from the original repository's master branch with: $ git fetch @@ -1252,8 +1267,8 @@ $ git merge origin/master However, the command provides a way to do this in one step: $ git pull origin master -In fact, if you have "master" checked out, then this branch has been -configured by "git clone" to get changes from the HEAD branch of the +In fact, if you have master checked out, then this branch has been +configured by git clone to get changes from the HEAD branch of the origin repository. So often you can accomplish the above with just a simple $ git pull @@ -1263,30 +1278,30 @@ the current branch. More generally, a branch that is created from a remote-tracking branch will pull by default from that branch. See the descriptions of the -branch.<name>.remote and branch.<name>.merge options in +branch.<name>.remote and branch.<name>.merge options in , and the discussion of the --track option in , to learn how to control these defaults. -In addition to saving you keystrokes, "git pull" also helps you by +In addition to saving you keystrokes, git pull also helps you by producing a default commit message documenting the branch and repository that you pulled from. (But note that no such commit will be created in the case of a -fast-forward; instead, your branch will just be +fast-forward; instead, your branch will just be updated to point to the latest commit from the upstream branch.) -The git pull command can also be given "." as the "remote" repository, +The git pull command can also be given . as the "remote" repository, in which case it just merges in a branch from the current repository; so the commands $ git pull . branch $ git merge branch -are roughly equivalent. The former is actually very commonly used. +are roughly equivalent.
-
+
Submitting patches to a project If you just have a few changes, the simplest way to submit them may just be to send them as patches in email: First, use ; for example: $ git format-patch origin will produce a numbered series of files in the current directory, one -for each patch in the current branch but not in origin/HEAD. +for each patch in the current branch but not in origin/HEAD. git format-patch can include an initial "cover letter". You can insert commentary on individual patches after the three dash line which format-patch places after the commit message but before the patch @@ -1296,35 +1311,35 @@ manner. You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the script to automate the process. -Consult the mailing list for your project first to determine how they -prefer such patches be handled. +Consult the mailing list for your project first to determine +their requirements for submitting patches.
-
+
Importing patches to a project Git also provides a tool called (am stands for "apply mailbox"), for importing such an emailed series of patches. Just save all of the patch-containing messages, in order, into a -single mailbox file, say "patches.mbox", then run +single mailbox file, say patches.mbox, then run $ git am -3 patches.mbox Git will apply each patch in order; if any conflicts are found, it will stop, and you can fix the conflicts as described in -"Resolving a merge". (The "-3" option tells -git to perform a merge; if you would prefer it just to abort and +"Resolving a merge". (The -3 option tells +Git to perform a merge; if you would prefer it just to abort and leave your tree and index untouched, you may omit that option.) Once the index is updated with the results of the conflict resolution, instead of creating a new commit, just run -$ git am --resolved -and git will create the commit for you and continue applying the +$ git am --continue +and Git will create the commit for you and continue applying the remaining patches from the mailbox. The final result will be a series of commits, one for each patch in the original mailbox, with authorship and commit log message each taken from the message containing each patch.
-
-Public git repositories +
+Public Git repositories Another way to submit changes to a project is to tell the maintainer of that project to pull the changes from your repository using -. In the section "Getting updates with git pull" we described this as a way to get +. In the section "Getting updates with git pull" we described this as a way to get updates from the "main" repository, but it works just as well in the other direction. If you and the maintainer both have accounts on the same machine, then @@ -1357,41 +1372,41 @@ your personal repo ------------------> your public repo | they push V their public repo <------------------- their repo We explain how to do this in the following sections. -
+
Setting up a public repository -Assume your personal repository is in the directory ~/proj. We +Assume your personal repository is in the directory ~/proj. We first create a new clone of the repository and tell git daemon that it is meant to be public: $ git clone --bare ~/proj proj.git $ touch proj.git/git-daemon-export-ok The resulting directory proj.git contains a "bare" git repository--it is -just the contents of the ".git" directory, without any files checked out +just the contents of the .git directory, without any files checked out around it. -Next, copy proj.git to the server where you plan to host the +Next, copy proj.git to the server where you plan to host the public repository. You can use scp, rsync, or whatever is most convenient.
-
-Exporting a git repository via the git protocol +
+Exporting a Git repository via the Git protocol This is the preferred method. If someone else administers the server, they should tell you what -directory to put the repository in, and what git:// URL it will appear -at. You can then skip to the section -"Pushing changes to a public repository", below. +directory to put the repository in, and what git:// URL it will +appear at. You can then skip to the section +"Pushing changes to a public repository", below. Otherwise, all you need to do is start ; it will listen on port 9418. By default, it will allow access to any directory -that looks like a git directory and contains the magic file +that looks like a Git directory and contains the magic file git-daemon-export-ok. Passing some directory paths as git daemon arguments will further restrict the exports to those paths. You can also run git daemon as an inetd service; see the man page for details. (See especially the examples section.)
-
-Exporting a git repository via http -The git protocol gives better performance and reliability, but on a -host with a web server set up, http exports may be simpler to set up. -All you need to do is place the newly created bare git repository in +
+Exporting a git repository via HTTP +The Git protocol gives better performance and reliability, but on a +host with a web server set up, HTTP exports may be simpler to set up. +All you need to do is place the newly created bare Git repository in a directory that is exported by the web server, and make some adjustments to give web clients some extra information they need: $ mv proj.git /home/you/public_html/proj.git @@ -1400,50 +1415,52 @@ $ git --bare update-server-info $ mv hooks/post-update.sample hooks/post-update (For an explanation of the last two lines, see and .) -Advertise the URL of proj.git. Anybody else should then be able to +Advertise the URL of proj.git. Anybody else should then be able to clone or pull from that URL, for example with a command line like: $ git clone http://yourserver.com/~you/proj.git (See also -link:howto/setup-git-server-over-http.txt[setup-git-server-over-http] +link:howto/setup-git-server-over-http.html[setup-git-server-over-http] for a slightly more sophisticated setup using WebDAV which also -allows pushing over http.) +allows pushing over HTTP.)
-
+
Pushing changes to a public repository Note that the two techniques outlined above (exporting via -http or git) allow other +http or git) allow other maintainers to fetch your latest changes, but they do not allow write access, which you will need to update the public repository with the latest changes created in your private repository. The simplest way to do this is using and ssh; to -update the remote branch named "master" with the latest state of your -branch named "master", run +update the remote branch named master with the latest state of your +branch named master, run $ git push ssh://yourserver.com/~you/proj.git master:master or just $ git push ssh://yourserver.com/~you/proj.git master As with git fetch, git push will complain if this does not result in a -fast-forward; see the following section for details on +fast-forward; see the following section for details on handling this case. -Note that the target of a "push" is normally a -bare repository. You can also push to a -repository that has a checked-out working tree, but the working tree -will not be updated by the push. This may lead to unexpected results if -the branch you push to is the currently checked-out branch! +Note that the target of a push is normally a +bare repository. You can also push to a +repository that has a checked-out working tree, but a push to update the +currently checked-out branch is denied by default to prevent confusion. +See the description of the receive.denyCurrentBranch option +in for details. As with git fetch, you may also set up configuration options to -save typing; so, for example, after -$ cat >>.git/config <<EOF -[remote "public-repo"] - url = ssh://yourserver.com/~you/proj.git -EOF -you should be able to perform the above push with just +save typing; so, for example: +$ git remote add public-repo ssh://yourserver.com/~you/proj.git +adds the following to .git/config: +[remote "public-repo"] + url = yourserver.com:proj.git + fetch = +refs/heads/*:refs/remotes/example/* +which lets you do the same push with just $ git push public-repo master -See the explanations of the remote.<name>.url, branch.<name>.remote, -and remote.<name>.push options in for -details. +See the explanations of the remote.<name>.url, +branch.<name>.remote, and remote.<name>.push options in + for details.
-
+
What to do when a push fails -If a push would not result in a fast-forward of the +If a push would not result in a fast-forward of the remote branch, then it will fail with an error like: error: remote 'refs/heads/master' is not an ancestor of local 'refs/heads/master'. @@ -1459,23 +1476,26 @@ use git reset --hard to remove already-published commits, o use git commit --amend to replace already-published commits - (as in ), or + (as in ), or use git rebase to rebase any already-published commits (as - in ). + in ). You may force git push to perform the update anyway by preceding the branch name with a plus sign: $ git push ssh://yourserver.com/~you/proj.git +master +Note the addition of the + sign. Alternatively, you can use the +-f flag to force the remote update, as in: +$ git push -f ssh://yourserver.com/~you/proj.git master Normally whenever a branch head in a public repository is modified, it is modified to point to a descendant of the commit that it pointed to before. By forcing a push in this situation, you break that convention. -(See .) +(See .) Nevertheless, this is a common practice for people that need a simple way to publish a work-in-progress patch series, and it is an acceptable compromise as long as you warn other developers that this is how you @@ -1484,19 +1504,19 @@ intend to manage the branch. the right to push to the same repository. In that case, the correct solution is to retry the push after first updating your work: either by a pull, or by a fetch followed by a rebase; see the -next section and +next section and for more.
-
+
Setting up a shared repository Another way to collaborate is by using a model similar to that commonly used in CVS, where several developers with special rights all push to and pull from a single shared repository. See for instructions on how to set this up. -However, while there is nothing wrong with git's support for shared +However, while there is nothing wrong with Git's support for shared repositories, this mode of operation is not generally recommended, -simply because the mode of collaboration that git supports--by +simply because the mode of collaboration that Git supports--by exchanging patches and pulling from public repositories--has so many advantages over the central shared repository: @@ -1528,18 +1548,41 @@ The lack of a central group of "committers" means there is
-
+
Allowing web browsing of a repository The gitweb cgi script provides users an easy way to browse your -project's files and history without having to install git; see the file -gitweb/INSTALL in the git source tree for instructions on setting it up. +project's revisions, file contents and logs without having to install +Git. Features like RSS/Atom feeds and blame/annotation details may +optionally be enabled. +The command provides a simple way to start +browsing the repository using gitweb. The default server when using +instaweb is lighttpd. +See the file gitweb/INSTALL in the Git source tree and + for instructions on details setting up a permanent +installation with a CGI or Perl capable server. +
+
+How to get a Git repository with minimal history +A shallow clone, with its truncated +history, is useful when one is interested only in recent history +of a project and getting full history from the upstream is +expensive. +A shallow clone is created by specifying +the --depth switch. The depth can later be +changed with the --depth switch, or full +history restored with --unshallow. +Merging inside a shallow clone will work as long +as a merge base is in the recent history. +Otherwise, it will be like merging unrelated histories and may +have to result in huge conflicts. This limitation may make such +a repository unsuitable to be used in merge based workflows.
-
+
Examples -
+
Maintaining topic branches for a Linux subsystem maintainer -This describes how Tony Luck uses git in his role as maintainer of the +This describes how Tony Luck uses Git in his role as maintainer of the IA64 architecture for the Linux kernel. He uses two public branches: @@ -1563,16 +1606,16 @@ A "release" tree into which tested patches are moved for final sanity containing a logical grouping of patches. To set this up, first create your work tree by cloning Linus's public tree: -$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work +$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work $ cd work Linus's tree will be stored in the remote-tracking branch named origin/master, and can be updated using ; you can track other public trees using to set up a "remote" and to keep them up-to-date; see -. +. Now create the branches in which you are going to work; these start out at the current tip of origin/master branch, and should be set up (using -the --track option to ) to merge changes in from +the --track option to ) to merge changes in from Linus by default. $ git branch --track test origin/master $ git branch --track release origin/master @@ -1581,17 +1624,17 @@ $ git branch --track release origin/master $ git checkout release && git pull Important note! If you have any local changes in these branches, then this merge will create a commit object in the history (with no local -changes git will simply do a "fast-forward" merge). Many people dislike +changes Git will simply do a "fast-forward" merge). Many people dislike the "noise" that this creates in the Linux history, so you should avoid -doing this capriciously in the "release" branch, as these noisy commits +doing this capriciously in the release branch, as these noisy commits will become part of the permanent history when you ask Linus to pull from the release branch. A few configuration variables (see ) can make it easy to push both branches to your public tree. (See -.) +.) $ cat >> .git/config <<EOF [remote "mytree"] - url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git + url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git push = release push = test EOF @@ -1608,22 +1651,22 @@ patches), and create a new branch from a recent stable tag of Linus's branch. Picking a stable base for your branch will: 1) help you: by avoiding inclusion of unrelated and perhaps lightly tested changes -2) help future bug hunters that use "git bisect" to find problems +2) help future bug hunters that use git bisect to find problems $ git checkout -b speed-up-spinlocks v2.6.35 Now you apply the patch(es), run some tests, and commit the change(s). If the patch is a multi-part series, then you should apply each as a separate commit to this branch. $ ... patch ... test ... commit [ ... patch ... test ... commit ]* -When you are happy with the state of this change, you can pull it into the +When you are happy with the state of this change, you can merge it into the "test" branch in preparation to make it public: -$ git checkout test && git pull . speed-up-spinlocks +$ git checkout test && git merge speed-up-spinlocks It is unlikely that you would have any conflicts here … but you might if you spent a while on this step and had also pulled new versions from upstream. -Some time later when enough time has passed and testing done, you can pull the -same branch into the "release" tree ready to go upstream. This is where you +Sometime later when enough time has passed and testing done, you can pull the +same branch into the release tree ready to go upstream. This is where you see the value of keeping each patch (or patch series) in its own branch. It -means that the patches can be moved into the "release" tree in any order. -$ git checkout release && git pull . speed-up-spinlocks +means that the patches can be moved into the release tree in any order. +$ git checkout release && git merge speed-up-spinlocks After a while, you will have a number of branches, and despite the well chosen names you picked for each of them, you may forget what they are for, or what status they are in. To get a reminder of what @@ -1638,23 +1681,23 @@ use: If it has been merged, then there will be no output.) Once a patch completes the great cycle (moving from test to release, then pulled by Linus, and finally coming back into your local -"origin/master" branch), the branch for this change is no longer needed. +origin/master branch), the branch for this change is no longer needed. You detect this when the output from: $ git log origin..branchname is empty. At this point the branch can be deleted: $ git branch -d branchname Some changes are so trivial that it is not necessary to create a separate branch and then merge into each of the test and release branches. For -these changes, just apply directly to the "release" branch, and then -merge that into the "test" branch. -To create diffstat and shortlog summaries of changes to include in a "please -pull" request to Linus you can use: -$ git diff --stat origin..release -and -$ git log -p origin..release | git shortlog +these changes, just apply directly to the release branch, and then +merge that into the test branch. +After pushing your work to mytree, you can use + to prepare a "please pull" request message +to send to Linus: +$ git push mytree +$ git request-pull origin mytree release Here are some of the scripts that simplify all this even further. ==== update script ==== -# Update a branch in my GIT tree. If the branch to be updated +# Update a branch in my Git tree. If the branch to be updated # is origin, then pull from kernel.org. Otherwise merge # origin/master branch into test|release branch @@ -1672,7 +1715,7 @@ origin) fi ;; *) - echo "Usage: $0 origin|test|release" 1>&2 + echo "usage: $0 origin|test|release" 1>&2 exit 1 ;; esac @@ -1683,7 +1726,7 @@ pname=$0 usage() { - echo "Usage: $pname branch test|release" 1>&2 + echo "usage: $pname branch test|release" 1>&2 exit 1 } @@ -1706,7 +1749,7 @@ test|release) ;; esac ==== status script ==== -# report on status of my ia64 GIT tree +# report on status of my ia64 Git tree gb=$(tput setab 2) rb=$(tput setab 1) @@ -1756,14 +1799,14 @@ done
-
+
Rewriting history and maintaining patch series Normally commits are only added to a project, never taken away or replaced. Git is designed with this assumption, and violating it will -cause git's merge machinery (for example) to do the wrong thing. +cause Git's merge machinery (for example) to do the wrong thing. However, there is a situation in which it can be useful to violate this assumption. -
+
Creating the perfect patch series Suppose you are a contributor to a large project, and you want to add a complicated feature, and to present it to the other developers in a way @@ -1804,10 +1847,10 @@ The complete series produces the same end result as your own use them, and then explain some of the problems that can arise because you are rewriting history.
-
+
Keeping a patch series up to date using git rebase -Suppose that you create a branch "mywork" on a remote-tracking branch -"origin", and create some commits on top of it: +Suppose that you create a branch mywork on a remote-tracking branch +origin, and create some commits on top of it: $ git checkout -b mywork origin $ vi file.txt $ git commit @@ -1815,16 +1858,16 @@ $ vi otherfile.txt $ git commit ... You have performed no merges into mywork, so it is just a simple linear -sequence of patches on top of "origin": +sequence of patches on top of origin: o--o--O <-- origin \ a--b--c <-- mywork Some more interesting work has been done in the upstream project, and -"origin" has advanced: +origin has advanced: o--o--O--o--o--o <-- origin \ a--b--c <-- mywork -At this point, you could use "pull" to merge your changes back in; +At this point, you could use pull to merge your changes back in; the result would create a new merge commit, like this: o--o--O--o--o--o <-- origin \ \ @@ -1835,7 +1878,7 @@ commits without any merges, you may instead choose to use $ git checkout mywork $ git rebase origin This will remove each of your commits from mywork, temporarily saving -them as patches (in a directory named ".git/rebase-apply"), update mywork to +them as patches (in a directory named .git/rebase-apply), update mywork to point at the latest version of origin, then apply each of the saved patches to the new mywork. The result will look like: o--o--O--o--o--o <-- origin @@ -1846,67 +1889,90 @@ and allow you to fix the conflicts; after fixing conflicts, use git ad to update the index with those contents, and then, instead of running git commit, just run $ git rebase --continue -and git will continue applying the rest of the patches. +and Git will continue applying the rest of the patches. At any point you may use the --abort option to abort this process and return mywork to the state it had before you started the rebase: $ git rebase --abort +If you need to reorder or edit a number of commits in a branch, it may +be easier to use git rebase -i, which allows you to reorder and +squash commits, as well as marking them for individual editing during +the rebase. See for details, and + for alternatives.
-
+
Rewriting a single commit -We saw in that you can replace the +We saw in that you can replace the most recent commit using $ git commit --amend which will replace the old commit by a new commit incorporating your -changes, giving you a chance to edit the old commit message first. -You can also use a combination of this and to -replace a commit further back in your history and recreate the -intervening changes on top of it. First, tag the problematic commit -with -$ git tag bad mywork~5 -(Either gitk or git log may be useful for finding the commit.) -Then check out that commit, edit it, and rebase the rest of the series -on top of it (note that we could check out the commit on a temporary -branch, but instead we're using a detached head): -$ git checkout bad -$ # make changes here and update the index -$ git commit --amend -$ git rebase --onto HEAD bad mywork -When you're done, you'll be left with mywork checked out, with the top -patches on mywork reapplied on top of your modified commit. You can -then clean up with -$ git tag -d bad -Note that the immutable nature of git history means that you haven't really -"modified" existing commits; instead, you have replaced the old commits with -new commits having new object names. +changes, giving you a chance to edit the old commit message first. +This is useful for fixing typos in your last commit, or for adjusting +the patch contents of a poorly staged commit. +If you need to amend commits from deeper in your history, you can +use interactive rebase's edit instruction.
-
+
Reordering or selecting from a patch series -Given one existing commit, the command -allows you to apply the change introduced by that commit and create a -new commit that records it. So, for example, if "mywork" points to a -series of patches on top of "origin", you might do something like: -$ git checkout -b mywork-new origin -$ gitk origin..mywork & -and browse through the list of patches in the mywork branch using gitk, -applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using git commit --amend. -The command may also help as it allows you to -individually select diff hunks for inclusion in the index (by -right-clicking on the diff hunk and choosing "Stage Hunk for Commit"). -Another technique is to use git format-patch to create a series of -patches, then reset the state to before the patches: +Sometimes you want to edit a commit deeper in your history. One +approach is to use git format-patch to create a series of patches +and then reset the state to before the patches: $ git format-patch origin $ git reset --hard origin -Then modify, reorder, or eliminate patches as preferred before applying -them again with . +Then modify, reorder, or eliminate patches as needed before applying +them again with : +$ git am *.patch
-
+
+Using interactive rebases +You can also edit a patch series with an interactive rebase. This is +the same as reordering a patch series using format-patch, so use whichever interface you like best. +Rebase your current HEAD on the last commit you want to retain as-is. +For example, if you want to reorder the last 5 commits, use: +$ git rebase -i HEAD~5 +This will open your editor with a list of steps to be taken to perform +your rebase. +pick deadbee The oneline of this commit +pick fa1afe1 The oneline of the next commit +... + +# Rebase c0ffeee..deadbee onto c0ffeee +# +# Commands: +# p, pick = use commit +# r, reword = use commit, but edit the commit message +# e, edit = use commit, but stop for amending +# s, squash = use commit, but meld into previous commit +# f, fixup = like "squash", but discard this commit's log message +# x, exec = run command (the rest of the line) using shell +# +# These lines can be re-ordered; they are executed from top to bottom. +# +# If you remove a line here THAT COMMIT WILL BE LOST. +# +# However, if you remove everything, the rebase will be aborted. +# +# Note that empty commits are commented out +As explained in the comments, you can reorder commits, squash them +together, edit commit messages, etc. by editing the list. Once you +are satisfied, save the list and close your editor, and the rebase +will begin. +The rebase will stop where pick has been replaced with edit or +when a step in the list fails to mechanically resolve conflicts and +needs your help. When you are done editing and/or resolving conflicts +you can continue with git rebase --continue. If you decide that +things are getting too hairy, you can always bail out with git rebase +--abort. Even after the rebase is complete, you can still recover +the original branch by using the reflog. +For a more detailed discussion of the procedure and additional tips, +see the "INTERACTIVE MODE" section of . +
+
Other tools There are numerous other tools, such as StGit, which exist for the purpose of maintaining a patch series. These are outside of the scope of this manual.
-
+
Problems with rewriting history The primary problem with rewriting the history of a branch has to do with merging. Suppose somebody fetches your branch and merges it into @@ -1929,7 +1995,7 @@ look like: the old head; it treats this situation exactly the same as it would if two developers had independently done the work on the old and new heads in parallel. At this point, if someone attempts to merge the new head -in to their branch, git will attempt to merge together the two (old and +in to their branch, Git will attempt to merge together the two (old and new) lines of development, instead of trying to replace the old by the new. The results are likely to be unexpected. You may still choose to publish branches whose history is rewritten, @@ -1939,7 +2005,7 @@ branches into their own work. For true distributed development that supports proper merging, published branches should never be rewritten.
-
+
Why bisecting merge commits can be harder than bisecting linear history The command correctly handles history that includes merge commits. However, when the commit that it finds is a @@ -1983,39 +2049,39 @@ linear history: ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D* Bisecting between Z and D* would hit a single culprit commit Y*, and understanding why Y* was broken would probably be easier. -Partly for this reason, many experienced git users, even when +Partly for this reason, many experienced Git users, even when working on an otherwise merge-heavy project, keep the history linear by rebasing against the latest upstream version before publishing.
-
+
Advanced branch management -
+
Fetching individual branches Instead of using , you can also choose just to update one branch at a time, and to store it locally under an arbitrary name: $ git fetch origin todo:my-todo-work -The first argument, "origin", just tells git to fetch from the -repository you originally cloned from. The second argument tells git -to fetch the branch named "todo" from the remote repository, and to -store it locally under the name refs/heads/my-todo-work. +The first argument, origin, just tells Git to fetch from the +repository you originally cloned from. The second argument tells Git +to fetch the branch named todo from the remote repository, and to +store it locally under the name refs/heads/my-todo-work. You can also fetch branches from other repositories; so $ git fetch git://example.com/proj.git master:example-master -will create a new branch named "example-master" and store in it the -branch named "master" from the repository at the given URL. If you +will create a new branch named example-master and store in it the +branch named master from the repository at the given URL. If you already have a branch named example-master, it will attempt to -fast-forward to the commit given by example.com's +fast-forward to the commit given by example.com's master branch. In more detail:
-
+
git fetch and fast-forwards -In the previous example, when updating an existing branch, "git fetch" +In the previous example, when updating an existing branch, git fetch checks to make sure that the most recent commit on the remote branch is a descendant of the most recent commit on your copy of the branch before updating your copy of the branch to point at the new -commit. Git calls this process a fast-forward. +commit. Git calls this process a fast-forward. A fast-forward looks something like this: o--o--o--o <-- old head of the branch \ @@ -2027,29 +2093,29 @@ resulting in a situation like: o--o--o--o--a--b <-- old head of the branch \ o--o--o <-- new head of the branch -In this case, "git fetch" will fail, and print out a warning. -In that case, you can still force git to update to the new head, as +In this case, git fetch will fail, and print out a warning. +In that case, you can still force Git to update to the new head, as described in the following section. However, note that in the -situation above this may mean losing the commits labeled "a" and "b", +situation above this may mean losing the commits labeled a and b, unless you've already created a reference of your own pointing to them.
-
+
Forcing git fetch to do non-fast-forward updates If git fetch fails because the new head of a branch is not a descendant of the old head, you may force the update with: $ git fetch git://example.com/proj.git +master:refs/remotes/example/master -Note the addition of the "+" sign. Alternatively, you can use the "-f" +Note the addition of the + sign. Alternatively, you can use the -f flag to force updates of all the fetched branches, as in: $ git fetch -f origin Be aware that commits that the old version of example/master pointed at may be lost, as we saw in the previous section.
-
+
Configuring remote-tracking branches -We saw above that "origin" is just a shortcut to refer to the +We saw above that origin is just a shortcut to refer to the repository that you originally cloned from. This information is -stored in git configuration variables, which you can see using +stored in Git configuration variables, which you can see using : $ git config -l core.repositoryformatversion=0 @@ -2060,38 +2126,33 @@ remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* branch.master.remote=origin branch.master.merge=refs/heads/master If there are other repositories that you also use frequently, you can -create similar configuration options to save typing; for example, -after -$ git config remote.example.url git://example.com/proj.git -then the following two commands will do the same thing: -$ git fetch git://example.com/proj.git master:refs/remotes/example/master -$ git fetch example master:refs/remotes/example/master -Even better, if you add one more option: -$ git config remote.example.fetch master:refs/remotes/example/master -then the following commands will all do the same thing: -$ git fetch git://example.com/proj.git master:refs/remotes/example/master -$ git fetch example master:refs/remotes/example/master +create similar configuration options to save typing; for example, +$ git remote add example git://example.com/proj.git +adds the following to .git/config: +[remote "example"] + url = git://example.com/proj.git + fetch = +refs/heads/*:refs/remotes/example/* +Also note that the above configuration can be performed by directly +editing the file .git/config instead of using . +After configuring the remote, the following three commands will do the +same thing: +$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/* +$ git fetch example +refs/heads/*:refs/remotes/example/* $ git fetch example -You can also add a "+" to force the update each time: -$ git config remote.example.fetch +master:refs/remotes/example/master -Don't do this unless you're sure you won't mind "git fetch" possibly -throwing away commits on example/master. -Also note that all of the above configuration can be performed by -directly editing the file .git/config instead of using -. See for more details on the configuration -options mentioned above. +options mentioned above and for more details on +the refspec syntax.
-
+
Git concepts Git is built on a small number of simple but powerful ideas. While it is possible to get things done without understanding them, you will find -git much more intuitive if you do. -We start with the most important, the object database and the index. -
+Git much more intuitive if you do. +We start with the most important, the object database and the index. +
The Object Database -We already saw in that all commits are stored +We already saw in that all commits are stored under a 40-digit "object name". In fact, all the information needed to represent the history of a project is stored in objects with such names. In each case the name is calculated by taking the SHA-1 hash of the @@ -2120,27 +2181,27 @@ Git can detect errors when it reads an object, by checking that the -(See for the details of the object formatting and +(See for the details of the object formatting and SHA-1 calculation.) There are four different types of objects: "blob", "tree", "commit", and "tag". -A "blob" object is used to store file data. +A "blob" object is used to store file data. -A "tree" object ties one or more +A "tree" object ties one or more "blob" objects into a directory structure. In addition, a tree object can refer to other tree objects, thus creating a directory hierarchy. -A "commit" object ties such directory hierarchies - together into a directed acyclic graph of revisions--each +A "commit" object ties such directory hierarchies + together into a directed acyclic graph of revisions--each commit contains the object name of exactly one tree designating the directory hierarchy at the time of the commit. In addition, a commit refers to "parent" commit objects that describe the history of how we @@ -2149,7 +2210,7 @@ A "commit" object ties such directory h -A "tag" object symbolically identifies and can be +A "tag" object symbolically identifies and can be used to sign other objects. It contains the object name and type of another object, a symbolic name (of course!) and, optionally, a signature. @@ -2157,10 +2218,10 @@ A "tag" object symbolically identifies and The object types in some more detail: -
+
Commit Object The "commit" object links a physical state of a tree with a description -of how we got there and why. Use the --pretty=raw option to +of how we got there and why. Use the --pretty=raw option to or to examine your favorite commit: $ git show -s --pretty=raw 2be7fcb476 @@ -2215,15 +2276,15 @@ a comment describing this commit. Note that a commit does not itself contain any information about what actually changed; all changes are calculated by comparing the contents of the tree referred to by this commit with the trees associated with -its parents. In particular, git does not attempt to record file renames +its parents. In particular, Git does not attempt to record file renames explicitly, though it can identify cases where the existence of the same file data at changing paths suggests a rename. (See, for example, the --M option to ). +-M option to ). A commit is usually created by , which creates a commit whose parent is normally the current HEAD, and whose tree is taken from the content currently stored in the index.
-
+
Tree Object The ever-versatile command can also be used to examine tree objects, but will give you more @@ -2246,18 +2307,18 @@ another tree, representing the contents of a subdirectory. Since trees and blobs, like all other objects, are named by the SHA-1 hash of their contents, two trees have the same SHA-1 name if and only if their contents (including, recursively, the contents of all subdirectories) -are identical. This allows git to quickly determine the differences +are identical. This allows Git to quickly determine the differences between two related tree objects, since it can ignore any entries with identical object names. (Note: in the presence of submodules, trees may also have commits as -entries. See for documentation.) -Note that the files all have mode 644 or 755: git actually only pays +entries. See for documentation.) +Note that the files all have mode 644 or 755: Git actually only pays attention to the executable bit.
-
+
Blob Object You can use to examine the contents of a blob; take, -for example, the blob in the entry for "COPYING" from the tree above: +for example, the blob in the entry for COPYING from the tree above: $ git show 6ff87c4664 Note that the only valid version of the GPL as far as this project @@ -2276,7 +2337,7 @@ renaming a file does not change the object that file is associated with.
-
+
Trust If you receive the SHA-1 name of a blob from one source, and its contents from another (possibly untrusted) source, you can still trust that those @@ -2298,9 +2359,9 @@ commits tells others that they can trust the whole history. sending out a single email that tells the people the name (SHA-1 hash) of the top commit, and digitally sign that email using something like GPG/PGP. -To assist in this, git also provides the tag object… +To assist in this, Git also provides the tag object…
-
+
Tag Object A tag object contains an object, object type, tag name, the name of the person ("tagger") who created the tag, and a message, which may contain @@ -2322,12 +2383,12 @@ nLE/L9aUXdWeTFPron96DLA= See the command to learn how to create and verify tag objects. (Note that can also be used to create "lightweight tags", which are not tag objects at all, but just simple -references whose names begin with "refs/tags/"). +references whose names begin with refs/tags/).
-
-How git stores objects efficiently: pack files +
+How Git stores objects efficiently: pack files Newly created objects are initially created in a file named after the -object's SHA-1 hash (stored in .git/objects). +object's SHA-1 hash (stored in .git/objects). Unfortunately this system becomes inefficient once a project has a lot of objects. Try this on an old project: $ git count-objects @@ -2335,27 +2396,25 @@ lot of objects. Try this on an old project: The first number is the number of objects which are kept in individual files. The second is the amount of space taken up by those "loose" objects. -You can save space and make git faster by moving these loose objects in +You can save space and make Git faster by moving these loose objects in to a "pack file", which stores a group of objects in an efficient compressed format; the details of how pack files are formatted can be -found in link:technical/pack-format.txt[technical/pack-format.txt]. +found in link:technical/pack-format.html[pack format]. To put the loose objects into a pack, just run git repack: $ git repack -Generating pack... -Done counting 6020 objects. -Deltifying 6020 objects. - 100% (6020/6020) done -Writing 6020 objects. - 100% (6020/6020) done -Total 6020, written 6020 (delta 4070), reused 0 (delta 0) -Pack pack-3e54ad29d5b2e05838c75df582c65257b8d08e1c created. -You can then run +Counting objects: 6020, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (6020/6020), done. +Writing objects: 100% (6020/6020), done. +Total 6020 (delta 4070), reused 0 (delta 0) +This creates a single "pack file" in .git/objects/pack/ +containing all currently unpacked objects. You can then run $ git prune to remove any of the "loose" objects that are now contained in the pack. This will also remove any unreferenced objects (which may be -created when, for example, you use "git reset" to remove a commit). +created when, for example, you use git reset to remove a commit). You can verify that the loose objects are gone by looking at the -.git/objects directory or by running +.git/objects directory or by running $ git count-objects 0 objects, 0 kilobytes Although the object files are gone, any commands that refer to those @@ -2363,17 +2422,17 @@ objects will work exactly as they did before. The command performs packing, pruning, and more for you, so is normally the only high-level command you need.
-
+
Dangling objects The command will sometimes complain about dangling objects. They are not a problem. The most common cause of dangling objects is that you've rebased a branch, or you have pulled from somebody else who rebased a branch--see -. In that case, the old head of the original +. In that case, the old head of the original branch still exists, as does everything it pointed to. The branch pointer itself just doesn't, since you replaced it with another one. There are also other situations that cause dangling objects. For -example, a "dangling blob" may arise because you did a "git add" of a +example, a "dangling blob" may arise because you did a git add of a file, but then, before you actually committed it and made it part of the bigger picture, you changed something else in that file and committed that updated thing--the old state that you added originally ends up @@ -2401,36 +2460,31 @@ you want, you can always create a new reference to it, e.g., them. You can just do $ git show <dangling-blob/tree-sha-goes-here> to show what the contents of the blob were (or, for a tree, basically -what the "ls" for that directory was), and that may give you some idea +what the ls for that directory was), and that may give you some idea of what the operation was that left that dangling object. Usually, dangling blobs and trees aren't very interesting. They're almost always the result of either being a half-way mergebase (the blob will often even have the conflict markers from a merge in it, if you have had conflicting merges that you fixed up by hand), or simply -because you interrupted a "git fetch" with ^C or something like that, +because you interrupted a git fetch with ^C or something like that, leaving some of the new objects in the object database, but just dangling and useless. Anyway, once you are sure that you're not interested in any dangling state, you can just prune all unreachable objects: $ git prune -and they'll be gone. But you should only run "git prune" on a quiescent +and they'll be gone. (You should only run git prune on a quiescent repository--it's kind of like doing a filesystem fsck recovery: you -don't want to do that while the filesystem is mounted. -(The same is true of "git fsck" itself, btw, but since -git fsck never actually changes the repository, it just reports -on what it found, git fsck itself is never dangerous to run. -Running it while somebody is actually changing the repository can cause -confusing and scary messages, but it won't actually do anything bad. In -contrast, running "git prune" while somebody is actively changing the -repository is a BAD idea). +don't want to do that while the filesystem is mounted. +git prune is designed not to cause any harm in such cases of concurrent +accesses to a repository but you might receive confusing or scary messages.)
-
+
Recovering from repository corruption -By design, git treats data trusted to it with caution. However, even in -the absence of bugs in git itself, it is still possible that hardware or +By design, Git treats data trusted to it with caution. However, even in +the absence of bugs in Git itself, it is still possible that hardware or operating system errors could corrupt data. The first defense against such problems is backups. You can back up a -git directory using clone, or just using cp, tar, or any other backup +Git directory using clone, or just using cp, tar, or any other backup mechanism. As a last resort, you can search for the corrupted objects and attempt to replace them by hand. Back up your repository before attempting this @@ -2448,7 +2502,7 @@ missing blob 4b9458b3786228369c63936db65827de3cc06200 Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 points to it. If you could find just one copy of that missing blob object, possibly in some other repository, you could move it into -.git/objects/4b/9458b3… and be done. Suppose you can't. You can +.git/objects/4b/9458b3... and be done. Suppose you can't. You can still examine the tree that pointed to it with , which might output something like: $ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8 @@ -2459,10 +2513,10 @@ which might output something like: 100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile ... So now you know that the missing blob was the data for a file named -"myfile". And chances are you can also identify the directory--let's -say it's in "somedirectory". If you're lucky the missing copy might be +myfile. And chances are you can also identify the directory--let's +say it's in somedirectory. If you're lucky the missing copy might be the same as the copy you have checked out in your working tree at -"somedirectory/myfile"; you can test whether that's right with +somedirectory/myfile; you can test whether that's right with : $ git hash-object -w somedirectory/myfile which will create and store a blob object with the contents of @@ -2496,16 +2550,16 @@ shot at reconstructing the contents of the in-between state 4b9458b. If you can do that, you can now recreate the missing object with $ git hash-object -w <recreated-file> and your repository is good again! -(Btw, you could have ignored the fsck, and started with doing a +(Btw, you could have ignored the fsck, and started with doing a $ git log --raw --all and just looked for the sha of the missing object (4b9458b..) in that -whole thing. It's up to you - git does have a lot of information, it is +whole thing. It's up to you--Git does have a lot of information, it is just missing one particular blob version.
-
+
The index -The index is a binary file (generally kept in .git/index) containing a +The index is a binary file (generally kept in .git/index) containing a sorted list of path names, each with permissions and the SHA-1 of a blob object; can show you the contents of the index: $ git ls-files --stage @@ -2540,7 +2594,7 @@ and the working tree. the last modified time). This data is not displayed above, and is not stored in the created tree object, but it can be used to determine quickly which files in the working directory differ from what was -stored in the index, and thus save git from having to read all of the +stored in the index, and thus save Git from having to read all of the data from such files to look for changes. @@ -2550,7 +2604,7 @@ between different tree objects, allowing each pathname to be associated with sufficient information about the trees involved that you can create a three-way merge between them. -We saw in that during a merge the index can +We saw in that during a merge the index can store multiple versions of a single file (called "stages"). The third column in the output above is the stage number, and will take on values other than 0 for files with merge @@ -2563,7 +2617,7 @@ a tree which you are in the process of working on. information as long as you have the name of the tree that it described.
-
+
Submodules Large projects are often composed of smaller, self-contained modules. For example, an embedded Linux distribution's source tree would include every @@ -2599,7 +2653,7 @@ clone none, some or all of the submodules. with Git 1.5.2 can look up the submodule commits in the repository and manually check them out; earlier versions won't recognize the submodules at all. -To see how submodule support works, create (for example) four example +To see how submodule support works, create four example repositories that can be used later as a submodule: $ mkdir ~/git $ cd ~/git @@ -2629,7 +2683,7 @@ done -It clones the submodule from <repo> to the given <path> under the +It clones the submodule from <repo> to the given <path> under the current directory and by default checks out the master branch. @@ -2677,7 +2731,7 @@ that git submodule update checks out a specific commit, rat of a branch. It's like checking out a tag: the head is detached, so you're not working on a branch. $ git branch -* (no branch) +* (detached from d266b98) master If you want to make a change within a submodule and you have a detached head, then you should create or checkout a branch, make your changes, publish the @@ -2704,7 +2758,7 @@ $ git commit -m "Updated submodule a." $ git push You have to run git submodule update after git pull if you want to update submodules, too. -
+
Pitfalls with submodules Always publish the submodule change before publishing the change to the superproject that references it. If you forget to publish the submodule change, @@ -2722,13 +2776,13 @@ $ git submodule update error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git. Did you forget to 'git add'? Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a' -In older git versions it could be easily forgotten to commit new or modified +In older Git versions it could be easily forgotten to commit new or modified files in a submodule, which silently leads to similar problems as not pushing -the submodule changes. Starting with git 1.7.0 both "git status" and "git diff" +the submodule changes. Starting with Git 1.7.0 both git status and git diff in the superproject show submodules as modified when they contain new or -modified files to protect against accidentally committing such a state. "git -diff" will also add a "-dirty" to the work tree side when generating patch -output or used with the --submodule option: +modified files to protect against accidentally committing such a state. git +diff will also add a -dirty to the work tree side when generating patch +output or used with the --submodule option: $ git diff diff --git a/sub b/sub --- a/sub @@ -2754,16 +2808,18 @@ $ cd a $ cat a.txt module a The changes are still visible in the submodule's reflog. -This is not the case if you did not commit your changes. +If you have uncommitted changes in your submodule working tree, git +submodule update will not overwrite them. Instead, you get the usual +warning about not being able switch from a dirty branch.
-
-Low-level git operations +
+Low-level Git operations Many of the higher-level commands were originally implemented as shell -scripts using a smaller core of low-level git commands. These can still -be useful when doing unusual things with git, or just as a way to +scripts using a smaller core of low-level Git commands. These can still +be useful when doing unusual things with Git, or just as a way to understand its inner workings. -
+
Object access and manipulation The command can show the contents of any object, though the higher-level is usually more useful. @@ -2776,29 +2832,29 @@ accessed by . Two trees can be compared with verified by , though it is normally simpler to use for both.
-
+
The Workflow High-level operations such as , and work by moving data between the working tree, the index, and the object database. Git provides low-level operations which perform each of these steps individually. -Generally, all "git" operations work on the index file. Some operations +Generally, all Git operations work on the index file. Some operations work purely on the index file (showing the current state of the index), but most operations move data between the index file and either the database or the working directory. Thus there are four main combinations: -
+
working directory → index The command updates the index with information from the working directory. You generally update the index information by just specifying the filename you want to update, like so: $ git update-index filename -but to avoid common mistakes with filename globbing etc, the command +but to avoid common mistakes with filename globbing etc., the command will not normally add totally new entries or remove old entries, i.e. it will normally just update existing cache entries. -To tell git that yes, you really do realize that certain files no +To tell Git that yes, you really do realize that certain files no longer exist, or that new files should be added, you should use the --remove and --add flags respectively. NOTE! A --remove flag does not mean that subsequent filenames will @@ -2815,7 +2871,7 @@ an object still matches its old backing store object. The previously introduced is just a wrapper for .
-
+
index → object database You write your current index file to a "tree" object with the program $ git write-tree @@ -2825,7 +2881,7 @@ and it will return the name of the resulting top-level tree. You can use that tree to re-generate the index at any time by going in the other direction:
-
+
object database → index You read a "tree" file from the object database, and use that to populate (and overwrite--don't do this if your index contains any @@ -2836,7 +2892,7 @@ index. Normal operation is just earlier. However, that is only your index file: your working directory contents have not been modified.
-
+
index → working directory You update your working directory from the index by "checking out" files. This is not a very common operation, since normally you'd just @@ -2851,14 +2907,14 @@ with or, if you want to check out all of the index, use -a. NOTE! git checkout-index normally refuses to overwrite old files, so if you have an old version of the tree already checked out, you will -need to use the "-f" flag (before the "-a" flag or the filename) to +need to use the -f flag (before the -a flag or the filename) to force the checkout. Finally, there are a few odds and ends which are not purely moving from one representation to the other:
-
+
Tying it all together -To commit a tree you have instantiated with "git write-tree", you'd +To commit a tree you have instantiated with git write-tree, you'd create a "commit" object that refers to that tree and the history behind it--most notably the "parent" commits that preceded it in history. @@ -2868,7 +2924,7 @@ or more parent commits, in which case we call it a "merge", due to the fact that such a commit brings together ("merges") two or more previous states represented by other commits. In other words, while a "tree" represents a particular directory state -of a working directory, a "commit" represents that state in "time", +of a working directory, a "commit" represents that state in time, and explains how we got there. You create a commit object by giving it the tree that describes the state at the time of the commit, and a list of parents: @@ -2877,12 +2933,11 @@ state at the time of the commit, and a list of parents: redirection from a pipe or file, or by just typing it at the tty). git commit-tree will return the name of the object that represents that commit, and you should save it away for later use. Normally, -you'd commit a new HEAD state, and while git doesn't care where you +you'd commit 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 pointed at by .git/HEAD, so that we can always see what the last committed state was. -Here is an ASCII art by Jon Loeliger that illustrates how -various pieces fit together. +Here is a picture that illustrates how various pieces fit together: commit-tree commit obj +----+ @@ -2916,7 +2971,7 @@ various pieces fit together. +-----------+
-
+
Examining the data You can examine the data represented in the object database and the index with various helper tools. For every object, you can use @@ -2937,23 +2992,22 @@ you can do $ git cat-file commit HEAD to see what the top commit was.
-
+
Merging multiple trees -Git helps you do a three-way merge, which you can expand to n-way by -repeating the merge procedure arbitrary times until you finally -"commit" the state. The normal situation is that you'd only do one -three-way merge (two parents), and commit it, but if you like to, you -can do multiple parents in one go. -To do a three-way merge, you need the two sets of "commit" objects -that you want to merge, use those to find the closest common parent (a -third "commit" object), and then use those commit objects to find the -state of the directory ("tree" object) at these points. -To get the "base" for the merge, you first look up the common parent -of two commits with +Git can help you perform a three-way merge, which can in turn be +used for a many-way merge by repeating the merge procedure several +times. The usual situation is that you only do one three-way merge +(reconciling two lines of history) and commit the result, but if +you like to, you can merge several branches in one go. +To perform a three-way merge, you start with the two commits you +want to merge, find their closest common parent (a third commit), +and compare the trees corresponding to these three commits. +To get the "base" for the merge, look up the common parent of two +commits: $ git merge-base <commit1> <commit2> -which will return you the commit they are both based on. You should -now look up the "tree" objects of those commits, which you can easily -do with (for example) +This prints the name of a commit they are both based on. You should +now look up the tree objects of those commits, which you can easily +do with $ git cat-file commit <commitname> | head -1 since the tree object information is always the first line in a commit object. @@ -2970,7 +3024,7 @@ you have in your current index anyway). index file, and you can just write the result out with git write-tree.
-
+
Merging multiple trees, continued Sadly, many merges aren't trivial. If there are files that have been added, moved or removed, or if both branches have modified the @@ -2987,18 +3041,18 @@ $ git ls-files --unmerged 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c Each line of the git ls-files --unmerged output begins with the blob mode bits, blob SHA-1, stage number, and the -filename. The stage number is git's way to say which tree it +filename. The stage number is Git's way to say which tree it came from: stage 1 corresponds to the $orig tree, stage 2 to the HEAD tree, and stage 3 to the $target tree. Earlier we said that trivial merges are done inside git read-tree -m. For example, if the file did not change -from $orig to HEAD nor $target, or if the file changed +from $orig to HEAD or $target, or if the file changed from $orig to HEAD and $orig to $target the same way, obviously the final outcome is what is in HEAD. What the above example shows is that file hello.c was changed from $orig to HEAD and $orig to $target in a different way. You could resolve this by running your favorite 3-way merge -program, e.g. diff3, merge, or git's own merge-file, on +program, e.g. diff3, merge, or Git's own merge-file, on the blob objects from these three stages yourself, like this: $ git cat-file blob 263414f... >hello.c~1 $ git cat-file blob 06fa6a2... >hello.c~2 @@ -3006,26 +3060,26 @@ $ git cat-file blob cc44c73... >hello.c~3 $ git merge-file hello.c~2 hello.c~1 hello.c~3 This would leave the merge result in hello.c~2 file, along with conflict markers if there are conflicts. After verifying -the merge result makes sense, you can tell git what the final +the merge result makes sense, you can tell Git what the final merge result for this file is by: $ mv -f hello.c~2 hello.c $ git update-index hello.c When a path is in the "unmerged" state, running git update-index for -that path tells git to mark the path resolved. -The above is the description of a git merge at the lowest level, +that path tells Git to mark the path resolved. +The above is the description of a Git merge at the lowest level, to help you understand what conceptually happens under the hood. -In practice, nobody, not even git itself, runs git cat-file three times +In practice, nobody, not even Git itself, runs git cat-file three times for this. There is a git merge-index program that extracts the stages to temporary files and calls a "merge" script on it: $ git merge-index git-merge-one-file hello.c and that is what higher level git merge -s resolve is implemented with.
-
-Hacking git -This chapter covers internal details of the git implementation which -probably only git developers need to understand. -
+
+Hacking Git +This chapter covers internal details of the Git implementation which +probably only Git developers need to understand. +
Object storage format All objects have a statically determined "type" which identifies the format of the object (i.e. how it is used, and how it can refer to other @@ -3037,33 +3091,32 @@ that not only specifies their type, but also provides size information about the data in the object. It's worth noting that the SHA-1 hash that is used to name the object is the hash of the original data plus this header, so sha1sum file does not match the object name -for file. -(Historical note: in the dawn of the age of git the hash -was the SHA-1 of the compressed object.) +for file. As a result, the general consistency of an object can always be tested independently of the contents or the type of the object: all objects can be validated by verifying that (a) their hashes match the content of the file and (b) the object successfully inflates to a stream of bytes that -forms a sequence of <ascii type without space> + <space> + <ascii decimal -size> + <byte\0> + <binary object data>. +forms a sequence of +<ascii type without space> + <space> + <ascii decimal size> + +<byte\0> + <binary object data>. The structured objects can further have their structure and connectivity to other objects verified. This is generally done with the git fsck program, which generates a full dependency graph of all objects, and verifies their internal consistency (in addition to just verifying their superficial consistency through the hash).
-
+
A birds-eye view of Git's source code It is not always easy for new developers to find their way through Git's source code. This section gives you a little guidance to show where to start. A good place to start is with the contents of the initial commit, with: $ git checkout e83c5163 -The initial revision lays the foundation for almost everything git has +The initial revision lays the foundation for almost everything Git has today, but is small enough to read in one sitting. Note that terminology has changed since that revision. For example, the README in that revision uses the word "changeset" to describe what we -now call a commit. +now call a commit. Also, we do not call it "cache" any more, but rather "index"; however, the file is still called cache.h. Remark: Not much reason to change it now, especially since there is no good single name for it anyway, because it is @@ -3084,7 +3137,7 @@ structures in cache.h), and that there are just a couple of (struct object *)commit to achieve the same as &commit->object, i.e. get at the object name and flags). Now is a good point to take a break to let this information sink in. -Next step: get familiar with the object naming. Read . +Next step: get familiar with the object naming. Read . There are quite a few ways to name an object (and not only revisions!). All of these are handled in sha1_name.c. Just have a quick look at the function get_sha1(). A lot of the special handling is done by @@ -3106,9 +3159,9 @@ called by the script. revision.h. It wraps the options in a struct named rev_info, which controls how and what revisions are walked, and more. The original job of git rev-parse is now taken by the function -setup_revisions(), which parses the revisions and the common command line +setup_revisions(), which parses the revisions and the common command-line options for the revision walker. This information is stored in the struct -rev_info for later consumption. You can do your own command line option +rev_info for later consumption. You can do your own command-line option parsing after calling setup_revisions(). After that, you have to call prepare_revision_walk() for initialization, and then you can get the commits one by one with the function get_revision(). @@ -3121,8 +3174,9 @@ command git. The source side of a builtin is -a function called cmd_<bla>, typically defined in builtin-<bla>.c, - and declared in builtin.h, +a function called cmd_<bla>, typically defined in builtin/<bla.c> + (note that older versions of Git used to have it in builtin-<bla>.c + instead), and declared in builtin.h. @@ -3137,7 +3191,7 @@ an entry in BUILTIN_OBJECTS in the Makefile Sometimes, more than one builtin is contained in one source file. For -example, cmd_whatchanged() and cmd_log() both reside in builtin-log.c, +example, cmd_whatchanged() and cmd_log() both reside in builtin/log.c, since they share quite a bit of code. In that case, the commands which are not named like the .c file in which they live have to be listed in BUILT_INS in the Makefile. @@ -3160,12 +3214,12 @@ is plumbing, and was around even in the initial commit (it literally went only through - some 20 revisions as cat-file.c, was renamed to builtin-cat-file.c + some 20 revisions as cat-file.c, was renamed to builtin/cat-file.c when made a builtin, and then saw less than 10 versions). -So, look into builtin-cat-file.c, search for cmd_cat_file() and look what +So, look into builtin/cat-file.c, search for cmd_cat_file() and look what it does. git_config(git_default_config); if (argc != 3) @@ -3203,7 +3257,7 @@ the variable sha1 in the function signature of ge This is how you read a blob (actually, not only a blob, but any type of object). To know how the function read_object_with_reference() actually works, find the source code for it (something like git grep -read_object_with | grep ":[a-z]" in the git repository), and read +read_object_with | grep ":[a-z]" in the Git repository), and read the source. To find out how the result can be used, just read on in cmd_cat_file(): write_or_die(1, buf, size); @@ -3221,36 +3275,36 @@ and paste it into the command line Voila. Another example: Find out what to do in order to make some script a builtin: -$ git log --no-merges --diff-filter=A builtin-*.c +$ git log --no-merges --diff-filter=A builtin/*.c You see, Git is actually the best tool to find out about the source of Git itself!
-
+
Git Glossary -alternate object database +alternate object database - Via the alternates mechanism, a repository - can inherit part of its object database - from another object database, which is called "alternate". + Via the alternates mechanism, a repository + can inherit part of its object database + from another object database, which is called an "alternate". -bare repository +bare repository A bare repository is normally an appropriately - named directory with a .git suffix that does not + named directory with a .git suffix that does not have a locally checked-out copy of any of the files under - revision control. That is, all of the git + revision control. That is, all of the Git administrative and control files that would normally be present in the hidden .git sub-directory are directly present in the repository.git directory instead, @@ -3261,204 +3315,225 @@ itself! -blob object +blob object - Untyped object, e.g. the contents of a file. + Untyped object, e.g. the contents of a file. -branch +branch A "branch" is an active line of development. The most recent - commit on a branch is referred to as the tip of + commit on a branch is referred to as the tip of that branch. The tip of the branch is referenced by a branch - head, which moves forward as additional development - is done on the branch. A single git - repository can track an arbitrary number of - branches, but your working tree is + head, which moves forward as additional development + is done on the branch. A single Git + repository can track an arbitrary number of + branches, but your working tree is associated with just one of them (the "current" or "checked out" - branch), and HEAD points to that branch. + branch), and HEAD points to that branch. -cache +cache - Obsolete for: index. + Obsolete for: index. -chain +chain - A list of objects, where each object in the list contains + A list of objects, where each object in the list contains a reference to its successor (for example, the successor of a - commit could be one of its parents). + commit could be one of its parents). -changeset +changeset - BitKeeper/cvsps speak for "commit". Since git does not + BitKeeper/cvsps speak for "commit". Since Git does not store changes, but states, it really does not make sense to use the term - "changesets" with git. + "changesets" with Git. -checkout +checkout The action of updating all or part of the - working tree with a tree object - or blob from the - object database, and updating the - index and HEAD if the whole working tree has - been pointed at a new branch. + working tree with a tree object + or blob from the + object database, and updating the + index and HEAD if the whole working tree has + been pointed at a new branch. -cherry-picking +cherry-picking - In SCM jargon, "cherry pick" means to choose a subset of + In SCM jargon, "cherry pick" means to choose a subset of changes out of a series of changes (typically commits) and record them - as a new series of changes on top of a different codebase. In GIT, this is + as a new series of changes on top of a different codebase. In Git, this is performed by the "git cherry-pick" command to extract the change introduced - by an existing commit and to record it based on the tip - of the current branch as a new commit. + by an existing commit and to record it based on the tip + of the current branch as a new commit. -clean +clean - A working tree is clean, if it - corresponds to the revision referenced by the current - head. Also see "dirty". + A working tree is clean, if it + corresponds to the revision referenced by the current + head. Also see "dirty". -commit +commit As a noun: A single point in the - git history; the entire history of a project is represented as a + Git history; the entire history of a project is represented as a set of interrelated commits. The word "commit" is often - used by git in the same places other revision control systems + used by Git in the same places other revision control systems use the words "revision" or "version". Also used as a short - hand for commit object. + hand for commit object. As a verb: The action of storing a new snapshot of the project's -state in the git history, by creating a new commit representing the current -state of the index and advancing HEAD +state in the Git history, by creating a new commit representing the current +state of the index and advancing HEAD to point at the new commit. -commit object +commit object - An object which contains the information about a - particular revision, such as parents, committer, - author, date and the tree object which corresponds - to the top directory of the stored + An object which contains the information about a + particular revision, such as parents, committer, + author, date and the tree object which corresponds + to the top directory of the stored revision. -core git +commit-ish (also committish) - Fundamental data structures and utilities of git. Exposes only limited - source code management tools. + A commit object or an + object that can be recursively dereferenced to + a commit object. + The following are all commit-ishes: + a commit object, + a tag object that points to a commit + object, + a tag object that points to a tag object that points to a + commit object, + etc. -DAG +core Git - Directed acyclic graph. The commit objects form a - directed acyclic graph, because they have parents (directed), and the - graph of commit objects is acyclic (there is no chain - which begins and ends with the same object). + Fundamental data structures and utilities of Git. Exposes only limited + source code management tools. -dangling object +DAG - An unreachable object which is not - reachable even from other unreachable objects; a - dangling object has no references to it from any - reference or object in the repository. + Directed acyclic graph. The commit objects form a + directed acyclic graph, because they have parents (directed), and the + graph of commit objects is acyclic (there is no chain + which begins and ends with the same object). -detached HEAD +dangling object - Normally the HEAD stores the name of a - branch. However, git also allows you to check out - an arbitrary commit that isn't necessarily the tip of any - particular branch. In this case HEAD is said to be "detached". + An unreachable object which is not + reachable even from other unreachable objects; a + dangling object has no references to it from any + reference or object in the repository. -dircache +detached HEAD - You are waaaaay behind. See index. - + Normally the HEAD stores the name of a + branch, and commands that operate on the + history HEAD represents operate on the history leading to the + tip of the branch the HEAD points at. However, Git also + allows you to check out an arbitrary + commit that isn't necessarily the tip of any + particular branch. The HEAD in such a state is called + "detached". + +Note that commands that operate on the history of the current branch +(e.g. git commit to build a new history on top of it) still work +while the HEAD is detached. They update the HEAD to point at the tip +of the updated history without affecting any branch. Commands that +update or inquire information about the current branch (e.g. git +branch --set-upstream-to that sets what remote-tracking branch the +current branch integrates with) obviously do not work, as there is no +(real) current branch to ask about in this state. -directory +directory @@ -3468,124 +3543,126 @@ to point at the new commit. -dirty +dirty - A working tree is said to be "dirty" if - it contains modifications which have not been committed to the current - branch. + A working tree is said to be "dirty" if + it contains modifications which have not been committed to the current + branch. -ent +evil merge - Favorite synonym to "tree-ish" by some total geeks. See - http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth - explanation. Avoid this term, not to confuse people. + An evil merge is a merge that introduces changes that + do not appear in any parent. -evil merge +fast-forward - An evil merge is a merge that introduces changes that - do not appear in any parent. + A fast-forward is a special type of merge where you have a + revision and you are "merging" another + branch's changes that happen to be a descendant of what + you have. In such these cases, you do not make a new merge + commit but instead just update to his + revision. This will happen frequently on a + remote-tracking branch of a remote + repository. -fast-forward +fetch - A fast-forward is a special type of merge where you have a - revision and you are "merging" another - branch's changes that happen to be a descendant of what - you have. In such these cases, you do not make a new merge - commit but instead just update to his - revision. This will happen frequently on a - remote-tracking branch of a remote - repository. + Fetching a branch means to get the + branch's head ref from a remote + repository, to find out which objects are + missing from the local object database, + and to get them, too. See also . -fetch +file system - Fetching a branch means to get the - branch's head ref from a remote - repository, to find out which objects are - missing from the local object database, - and to get them, too. See also . + Linus Torvalds originally designed Git to be a user space file system, + i.e. the infrastructure to hold files and directories. That ensured the + efficiency and speed of Git. -file system +Git archive - Linus Torvalds originally designed git to be a user space file system, - i.e. the infrastructure to hold files and directories. That ensured the - efficiency and speed of git. + Synonym for repository (for arch people). -git archive +gitfile - Synonym for repository (for arch people). + A plain file .git at the root of a working tree that + points at the directory that is the real repository. -grafts +grafts Grafts enables two otherwise different lines of development to be joined together by recording fake ancestry information for commits. This way - you can make git pretend the set of parents a commit has + you can make Git pretend the set of parents a commit has is different from what was recorded when the commit was created. Configured via the .git/info/grafts file. +Note that the grafts mechanism is outdated and can lead to problems +transferring objects between repositories; see +for a more flexible and robust system to do the same thing. -hash +hash - In git's context, synonym to object name. + In Git's context, synonym for object name. -head +head - A named reference to the commit at the tip of a - branch. Heads are stored in a file in + A named reference to the commit at the tip of a + branch. Heads are stored in a file in $GIT_DIR/refs/heads/ directory, except when using packed refs. (See .) @@ -3593,80 +3670,80 @@ to point at the new commit. -HEAD +HEAD - The current branch. In more detail: Your working tree is normally derived from the state of the tree + The current branch. In more detail: Your working tree is normally derived from the state of the tree referred to by HEAD. HEAD is a reference to one of the - heads in your repository, except when using a - detached HEAD, in which case it directly + heads in your repository, except when using a + detached HEAD, in which case it directly references an arbitrary commit. -head ref +head ref - A synonym for head. + A synonym for head. -hook +hook - During the normal execution of several git commands, call-outs are made + During the normal execution of several Git commands, call-outs are made to optional scripts that allow a developer to add functionality or checking. Typically, the hooks allow for a command to be pre-verified and potentially aborted, and allow for a post-notification after the operation is done. The hook scripts are found in the $GIT_DIR/hooks/ directory, and are enabled by simply removing the .sample suffix from the filename. In earlier versions - of git you had to make them executable. + of Git you had to make them executable. -index +index A collection of files with stat information, whose contents are stored as objects. The index is a stored version of your - working tree. Truth be told, it can also contain a second, and even + working tree. Truth be told, it can also contain a second, and even a third version of a working tree, which are used - when merging. + when merging. -index entry +index entry The information regarding a particular file, stored in the - index. An index entry can be unmerged, if a - merge was started, but not yet finished (i.e. if + index. An index entry can be unmerged, if a + merge was started, but not yet finished (i.e. if the index contains multiple versions of that file). -master +master - The default development branch. Whenever you - create a git repository, a branch named + The default development branch. Whenever you + create a Git repository, a branch named "master" is created, and becomes the active branch. In most cases, this contains the local development, though that is purely by convention and is not required. @@ -3675,112 +3752,110 @@ to point at the new commit. -merge +merge As a verb: To bring the contents of another - branch (possibly from an external - repository) into the current branch. In the + branch (possibly from an external + repository) into the current branch. In the case where the merged-in branch is from a different repository, - this is done by first fetching the remote branch + this is done by first fetching the remote branch and then merging the result into the current branch. This combination of fetch and merge operations is called a - pull. Merging is performed by an automatic process + pull. Merging is performed by an automatic process that identifies changes made since the branches diverged, and then applies all those changes together. In cases where changes conflict, manual intervention may be required to complete the merge. -As a noun: unless it is a fast-forward, a -successful merge results in the creation of a new commit +As a noun: unless it is a fast-forward, a +successful merge results in the creation of a new commit representing the result of the merge, and having as -parents the tips of the merged branches. +parents the tips of the merged branches. This commit is referred to as a "merge commit", or sometimes just a "merge". -object +object - The unit of storage in git. It is uniquely identified by the - SHA1 of its contents. Consequently, an + The unit of storage in Git. It is uniquely identified by the + SHA-1 of its contents. Consequently, an object can not be changed. -object database +object database - Stores a set of "objects", and an individual object is - identified by its object name. The objects usually + Stores a set of "objects", and an individual object is + identified by its object name. The objects usually live in $GIT_DIR/objects/. -object identifier +object identifier - Synonym for object name. + Synonym for object name. -object name +object name - The unique identifier of an object. The hash - of the object's contents using the Secure Hash Algorithm - 1 and usually represented by the 40 character hexadecimal encoding of - the hash of the object. + The unique identifier of an object. The + object name is usually represented by a 40 character + hexadecimal string. Also colloquially called SHA-1. -object type +object type - One of the identifiers "commit", - "tree", "tag" or - "blob" describing the type of an - object. + One of the identifiers "commit", + "tree", "tag" or + "blob" describing the type of an + object. -octopus +octopus - To merge more than two branches. Also denotes an - intelligent predator. + To merge more than two branches. -origin +origin - The default upstream repository. Most projects have + The default upstream repository. Most projects have at least one upstream project which they track. By default origin is used for that purpose. New upstream updates - will be fetched into remote remote-tracking branches named + will be fetched into remote-tracking branches named origin/name-of-upstream-branch, which you can see using git branch -r. @@ -3788,7 +3863,7 @@ This commit is referred to as a "merge commit", or sometimes just a -pack +pack @@ -3799,23 +3874,23 @@ This commit is referred to as a "merge commit", or sometimes just a -pack index +pack index The list of identifiers, and other information, of the objects in a - pack, to assist in efficiently accessing the contents of a + pack, to assist in efficiently accessing the contents of a pack. -pathspec +pathspec - Pattern used to specify paths. + Pattern used to limit paths in Git commands. Pathspecs are used on the command line of "git ls-files", "git ls-tree", "git add", "git grep", "git diff", "git checkout", @@ -3844,52 +3919,130 @@ the rest of the pathspec is a pattern for the remainder prefix will be matched against that pattern using fnmatch(3); in particular, * and ? can match directory separators. + + For example, Documentation/*.jpg will match all .jpg files in the Documentation subtree, including Documentation/chapter_1/figure_1.jpg. - - A pathspec that begins with a colon : has special meaning. In the short form, the leading colon : is followed by zero or more "magic signature" letters (which optionally is terminated by another colon :), -and the remainder is the pattern to match against the path. The optional -colon that terminates the "magic signature" can be omitted if the pattern -begins with a character that cannot be a "magic signature" and is not a -colon. +and the remainder is the pattern to match against the path. +The "magic signature" consists of ASCII symbols that are neither +alphanumeric, glob, regex special characters nor colon. +The optional colon that terminates the "magic signature" can be +omitted if the pattern begins with a character that does not belong to +"magic signature" symbol set and is not a colon. In the long form, the leading colon : is followed by a open parenthesis (, a comma-separated list of zero or more "magic words", and a close parentheses ), and the remainder is the pattern to match against the path. -The "magic signature" consists of an ASCII symbol that is not -alphanumeric. +A pathspec with only a colon means "there is no pathspec". This form +should not be combined with other pathspec. -top / +top + + + + The magic word top (magic signature: /) makes the pattern + match from the root of the working tree, even when you are + running the command from inside a subdirectory. + + + + + +literal - The magic word top (mnemonic: /) makes the pattern match - from the root of the working tree, even when you are running - the command from inside a subdirectory. + Wildcards in the pattern such as * or ? are treated + as literal characters. + + + + + +icase + + + + Case insensitive match. + + + + + +glob + + + + Git treats the pattern as a shell glob suitable for + consumption by fnmatch(3) with the FNM_PATHNAME flag: + wildcards in the pattern will not match a / in the pathname. + For example, "Documentation/*.html" matches + "Documentation/git.html" but not "Documentation/ppc/ppc.html" + or "tools/perf/Documentation/perf.html". + +Two consecutive asterisks ("**") in patterns matched against +full pathname may have special meaning: + + + +A leading "**" followed by a slash means match in all + directories. For example, "**/foo" matches file or directory + "foo" anywhere, the same as pattern "foo". "**/foo/bar" + matches file or directory "bar" anywhere that is directly + under directory "foo". + + + + +A trailing "/**" matches everything inside. For example, + "abc/**" matches all files inside directory "abc", relative + to the location of the .gitignore file, with infinite depth. + + + + +A slash followed by two consecutive asterisks then a slash + matches zero or more directories. For example, "a/**/b" + matches "a/b", "a/x/b", "a/x/y/b" and so on. + + + + +Other consecutive asterisks are considered invalid. + +Glob magic is incompatible with literal magic. + + + + + + +exclude + + + + After a path matches any non-exclude pathspec, it will be run + through all exclude pathspec (magic signature: !). If it + matches, the path is ignored. -Currently only the slash / is recognized as the "magic signature", -but it is envisioned that we will support more types of magic in later -versions of git. -A pathspec with only a colon means "there is no pathspec". This form -should not be combined with other pathspec. -parent +parent - A commit object contains a (possibly empty) list + A commit object contains a (possibly empty) list of the logical predecessor(s) in the line of development, i.e. its parents. @@ -3897,116 +4050,160 @@ should not be combined with other pathspec. -pickaxe +pickaxe - The term pickaxe refers to an option to the diffcore + The term pickaxe refers to an option to the diffcore routines that help select changes that add or delete a given text string. With the --pickaxe-all option, it can be used to view the full - changeset that introduced or removed, say, a + changeset that introduced or removed, say, a particular line of text. See . -plumbing +plumbing - Cute name for core git. + Cute name for core Git. -porcelain +porcelain Cute name for programs and program suites depending on - core git, presenting a high level access to - core git. Porcelains expose more of a SCM - interface than the plumbing. + core Git, presenting a high level access to + core Git. Porcelains expose more of a SCM + interface than the plumbing. -pull +per-worktree ref - Pulling a branch means to fetch it and - merge it. See also . + Refs that are per-worktree, rather than + global. This is presently only HEAD and any refs + that start with refs/bisect/, but might later include other + unusual refs. -push +pseudoref - Pushing a branch means to get the branch's - head ref from a remote repository, + Pseudorefs are a class of files under $GIT_DIR which behave + like refs for the purposes of rev-parse, but which are treated + specially by git. Pseudorefs both have names that are all-caps, + and always start with a line consisting of a + SHA-1 followed by whitespace. So, HEAD is not a + pseudoref, because it is sometimes a symbolic ref. They might + optionally contain some additional data. MERGE_HEAD and + CHERRY_PICK_HEAD are examples. Unlike + per-worktree refs, these files cannot + be symbolic refs, and never have reflogs. They also cannot be + updated through the normal ref update machinery. Instead, + they are updated by directly writing to the files. However, + they can be read as if they were refs, so git rev-parse + MERGE_HEAD will work. + + + + + +pull + + + + Pulling a branch means to fetch it and + merge it. See also . + + + + + +push + + + + Pushing a branch means to get the branch's + head ref from a remote repository, find out if it is a direct ancestor to the branch's local head ref, and in that case, putting all - objects, which are reachable from the local + objects, which are reachable from the local head ref, and which are missing from the remote repository, into the remote - object database, and updating the remote - head ref. If the remote head is not an + object database, and updating the remote + head ref. If the remote head is not an ancestor to the local head, the push fails. -reachable +reachable - All of the ancestors of a given commit are said to be + All of the ancestors of a given commit are said to be "reachable" from that commit. More - generally, one object is reachable from - another if we can reach the one from the other by a chain - that follows tags to whatever they tag, - commits to their parents or trees, and - trees to the trees or blobs + generally, one object is reachable from + another if we can reach the one from the other by a chain + that follows tags to whatever they tag, + commits to their parents or trees, and + trees to the trees or blobs that they contain. -rebase +rebase - To reapply a series of changes from a branch to a - different base, and reset the head of that branch + To reapply a series of changes from a branch to a + different base, and reset the head of that branch to the result. -ref +ref - A 40-byte hex representation of a SHA1 or a name that - denotes a particular object. They may be stored in - a file under $GIT_DIR/refs/ directory, or - in the $GIT_DIR/packed-refs file. + A name that begins with refs/ (e.g. refs/heads/master) + that points to an object name or another + ref (the latter is called a symbolic ref). + For convenience, a ref can sometimes be abbreviated when used + as an argument to a Git command; see + for details. + Refs are stored in the repository. +The ref namespace is hierarchical. +Different subhierarchies are used for different purposes (e.g. the +refs/heads/ hierarchy is used to represent local branches). +There are a few special-purpose refs that do not begin with refs/. +The most notable example is HEAD. -reflog +reflog @@ -4019,91 +4216,94 @@ should not be combined with other pathspec. -refspec +refspec - A "refspec" is used by fetch and - push to describe the mapping between remote - ref and local ref. They are combined with a colon in - the format <src>:<dst>, preceded by an optional plus sign, +. - For example: git fetch $URL - refs/heads/master:refs/heads/origin means "grab the master - branch head from the $URL and store - it as my origin branch head". And git push - $URL refs/heads/master:refs/heads/to-upstream means "publish my - master branch head as to-upstream branch at $URL". See also - . + A "refspec" is used by fetch and + push to describe the mapping between remote + ref and local ref. -remote-tracking branch +remote repository - A regular git branch that is used to follow changes from - another repository. A remote-tracking - branch should not contain direct modifications or have local commits - made to it. A remote-tracking branch can usually be - identified as the right-hand-side ref in a Pull: - refspec. + A repository which is used to track the same + project but resides somewhere else. To communicate with remotes, + see fetch or push. -repository +remote-tracking branch - A collection of refs together with an - object database containing all objects - which are reachable from the refs, possibly - accompanied by meta data from one or more porcelains. A + A ref that is used to follow changes from another + repository. It typically looks like + refs/remotes/foo/bar (indicating that it tracks a branch named + bar in a remote named foo), and matches the right-hand-side of + a configured fetch refspec. A remote-tracking + branch should not contain direct modifications or have local + commits made to it. + + + + + +repository + + + + A collection of refs together with an + object database containing all objects + which are reachable from the refs, possibly + accompanied by meta data from one or more porcelains. A repository can share an object database with other repositories - via alternates mechanism. + via alternates mechanism. -resolve +resolve The action of fixing up manually what a failed automatic - merge left behind. + merge left behind. -revision +revision - A particular state of files and directories which was stored in the - object database. It is referenced by a - commit object. + Synonym for commit (the noun). -rewind +rewind To throw away part of the development, i.e. to assign the - head to an earlier revision. + head to an earlier revision. -SCM +SCM @@ -4113,24 +4313,37 @@ should not be combined with other pathspec. -SHA1 +SHA-1 + + + + "Secure Hash Algorithm 1"; a cryptographic hash function. + In the context of Git used as a synonym for object name. + + + + + +shallow clone - Synonym for object name. + Mostly a synonym to shallow repository + but the phrase makes it more explicit that it was created by + running git clone --depth=... command. -shallow repository +shallow repository - A shallow repository has an incomplete - history some of whose commits have parents cauterized away (in other - words, git is told to pretend that these commits do not have the - parents, even though they are recorded in the commit object). This is sometimes useful when you are interested only in the + A shallow repository has an incomplete + history some of whose commits have parents cauterized away (in other + words, Git is told to pretend that these commits do not have the + parents, even though they are recorded in the commit object). This is sometimes useful when you are interested only in the recent history of a project even though the real history recorded in the upstream is much larger. A shallow repository is created by giving the --depth option to , and @@ -4140,14 +4353,39 @@ should not be combined with other pathspec. -symref +submodule + + + + A repository that holds the history of a + separate project inside another repository (the latter of + which is called superproject). + + + + + +superproject + + + + A repository that references repositories + of other projects in its working tree as submodules. + The superproject knows about the names of (but does not hold + copies of) commit objects of the contained submodules. + + + + + +symref - Symbolic reference: instead of containing the SHA1 + Symbolic reference: instead of containing the SHA-1 id itself, it is of the format ref: refs/some/thing and when referenced, it recursively dereferences to this reference. - HEAD is a prime example of a symref. Symbolic + HEAD is a prime example of a symref. Symbolic references are manipulated with the command. @@ -4155,41 +4393,41 @@ should not be combined with other pathspec. -tag +tag - A ref under refs/tags/ namespace that points to an + A ref under refs/tags/ namespace that points to an object of an arbitrary type (typically a tag points to either a - tag or a commit object). - In contrast to a head, a tag is not updated by - the commit command. A git tag has nothing to do with a Lisp - tag (which would be called an object type - in git's context). A tag is most typically used to mark a particular - point in the commit ancestry chain. + tag or a commit object). + In contrast to a head, a tag is not updated by + the commit command. A Git tag has nothing to do with a Lisp + tag (which would be called an object type + in Git's context). A tag is most typically used to mark a particular + point in the commit ancestry chain. -tag object +tag object - An object containing a ref pointing to + An object containing a ref pointing to another object, which can contain a message just like a - commit object. It can also contain a (PGP) + commit object. It can also contain a (PGP) signature, in which case it is called a "signed tag object". -topic branch +topic branch - A regular git branch that is used by a developer to + A regular Git branch that is used by a developer to identify a conceptual line of development. Since branches are very easy and inexpensive, it is often desirable to have several small branches that each contain very well defined concepts or small incremental yet @@ -4199,66 +4437,77 @@ should not be combined with other pathspec. -tree +tree - Either a working tree, or a tree object together with the dependent blob and tree objects + Either a working tree, or a tree object together with the dependent blob and tree objects (i.e. a stored representation of a working tree). -tree object +tree object - An object containing a list of file names and modes along + An object containing a list of file names and modes along with refs to the associated blob and/or tree objects. A - tree is equivalent to a directory. + tree is equivalent to a directory. -tree-ish +tree-ish (also treeish) - A ref pointing to either a commit object, a tree object, or a tag object pointing to a tag or commit or tree object. + A tree object or an object + that can be recursively dereferenced to a tree object. + Dereferencing a commit object yields the + tree object corresponding to the revision's + top directory. + The following are all tree-ishes: + a commit-ish, + a tree object, + a tag object that points to a tree object, + a tag object that points to a tag object that points to a tree + object, + etc. -unmerged index +unmerged index - An index which contains unmerged - index entries. + An index which contains unmerged + index entries. -unreachable object +unreachable object - An object which is not reachable from a - branch, tag, or any other reference. + An object which is not reachable from a + branch, tag, or any other reference. -upstream branch +upstream branch - The default branch that is merged into the branch in + The default branch that is merged into the branch in question (or the branch in question is rebased onto). It is configured via branch.<name>.remote and branch.<name>.merge. If the upstream branch of A is origin/B sometimes we say "A is tracking origin/B". @@ -4267,23 +4516,23 @@ should not be combined with other pathspec. -working tree +working tree The tree of actual checked out files. The working tree normally - contains the contents of the HEAD commit's tree, + contains the contents of the HEAD commit's tree, plus any local changes that you have made but not yet committed.
- + Git Quick Reference This is a quick summary of the major commands; the previous chapters explain how these work in more detail. -
+
Creating a new repository From a tarball: $ tar xzf project.tar.gz @@ -4296,7 +4545,7 @@ $ git commit $ git clone git://example.com/pub/project.git $ cd project
-
+
Managing branches $ git branch # list all local branches in this repo $ git checkout test # switch working directory to branch "test" @@ -4336,7 +4585,7 @@ $ git remote show example # get details $ git fetch example # update branches from example $ git branch -r # list all remote branches
-
+
Exploring history $ gitk # visualize and browse history $ git log # list all commits @@ -4364,9 +4613,9 @@ $ git bisect good # if this revision is good, or $ git bisect bad # if this revision is bad. # repeat until done.
-
+
Making changes -Make sure git knows who to blame: +Make sure Git knows who to blame: $ cat >>~/.gitconfig <<\EOF [user] name = Your Name Comes Here @@ -4382,20 +4631,20 @@ $ git commit $ git commit d.txt # use latest content only of d.txt $ git commit -a # use latest content of all tracked files
-
+
Merging $ git merge test # merge branch "test" into the current branch $ git pull git://example.com/project.git master # fetch and merge in remote branch $ git pull . test # equivalent to git merge test
-
+
Sharing your changes Importing or exporting patches: $ git format-patch origin..HEAD # format a patch for each commit # in HEAD but not in origin $ git am mbox # import patches from the mailbox "mbox" -Fetch a branch in a different git repository, then merge into the +Fetch a branch in a different Git repository, then merge into the current branch: $ git pull git://example.com/project.git theirbranch Store the fetched branch into a local branch before merging into the @@ -4410,7 +4659,7 @@ branch with your commits: $ git remote add example ssh://example.com/project.git $ git push example test
-
+
Repository maintenance Check for corruption: $ git fsck @@ -4418,7 +4667,7 @@ $ git push example test $ git gc
- + Notes and todo list for this manual This is a work in progress. The basic requirements: @@ -4427,7 +4676,7 @@ $ git push example test It must be readable in order, from beginning to end, by someone intelligent with a basic grasp of the UNIX command line, but without - any special knowledge of git. If necessary, any other prerequisites + any special knowledge of Git. If necessary, any other prerequisites should be specifically mentioned as they arise. @@ -4443,7 +4692,7 @@ Whenever possible, section headings should clearly describe the task Think about how to create a clear chapter dependency graph that will allow people to get to important topics without necessarily reading everything in between. -Scan Documentation/ for other stuff left out; in particular: +Scan Documentation/ for other stuff left out; in particular: @@ -4452,7 +4701,7 @@ howto's -some of technical/? +some of technical/? @@ -4469,21 +4718,16 @@ list of commands in Scan email archives for other stuff left out Scan man pages to see if any assume more background than this manual provides. -Simplify beginning by suggesting disconnected head instead of -temporary branch creation? Add more good examples. Entire sections of just cookbook examples might be a good idea; maybe make an "advanced examples" section a standard end-of-chapter section? Include cross-references to the glossary, where appropriate. -Document shallow clones? See draft 1.5.0 release notes for some -documentation. Add a section on working with other version control systems, including CVS, Subversion, and just imports of series of release tarballs. -More details on gitweb? Write a chapter on using plumbing and writing scripts. Alternates, clone -reference, etc. More on recovery from repository corruption. See: - http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2 - http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 + http://marc.info/?l=git&m=117263864820799&w=2 + http://marc.info/?l=git&m=117147855503798&w=2 diff --git a/doc/source/en/TortoiseGit/tgit_dug/dug_settings_git.xml b/doc/source/en/TortoiseGit/tgit_dug/dug_settings_git.xml index 2a7c02ac9..47e297d61 100644 --- a/doc/source/en/TortoiseGit/tgit_dug/dug_settings_git.xml +++ b/doc/source/en/TortoiseGit/tgit_dug/dug_settings_git.xml @@ -99,7 +99,7 @@ Push Default - Selecting this means to always push to this remote. + Selecting this means to always push to this remote (cf. ) Default is false. -- 2.11.4.GIT