summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/Makefile32
-rw-r--r--Documentation/RelNotes/2.1.1.txt44
-rw-r--r--Documentation/RelNotes/2.1.2.txt20
-rw-r--r--Documentation/RelNotes/2.1.3.txt26
-rw-r--r--Documentation/RelNotes/2.2.0.txt291
-rw-r--r--Documentation/config.txt77
-rw-r--r--Documentation/everyday.txto9
-rw-r--r--Documentation/git-credential-cache--daemon.txt6
-rw-r--r--Documentation/git-difftool.txt14
-rw-r--r--Documentation/git-fast-export.txt61
-rw-r--r--Documentation/git-imap-send.txt14
-rw-r--r--Documentation/git-init.txt85
-rw-r--r--Documentation/git-interpret-trailers.txt314
-rw-r--r--Documentation/git-prune-packed.txt2
-rw-r--r--Documentation/git-push.txt11
-rw-r--r--Documentation/git-quiltimport.txt2
-rw-r--r--Documentation/git-rebase.txt40
-rw-r--r--Documentation/git-receive-pack.txt65
-rw-r--r--Documentation/git-rev-list.txt2
-rw-r--r--Documentation/git-rev-parse.txt1
-rw-r--r--Documentation/git-send-pack.txt13
-rw-r--r--Documentation/git-stage.txt2
-rw-r--r--Documentation/git-status.txt4
-rw-r--r--Documentation/git-svn.txt17
-rw-r--r--Documentation/git-tag.txt2
-rw-r--r--Documentation/git-update-index.txt2
-rw-r--r--Documentation/git.txt14
-rw-r--r--Documentation/gitattributes.txt4
-rw-r--r--Documentation/gitcore-tutorial.txt2
-rw-r--r--Documentation/gitcvs-migration.txt2
-rw-r--r--Documentation/giteveryday.txt (renamed from Documentation/everyday.txt)278
-rw-r--r--Documentation/gitglossary.txt2
-rw-r--r--Documentation/gittutorial-2.txt4
-rw-r--r--Documentation/gittutorial.txt4
-rw-r--r--Documentation/pretty-formats.txt16
-rw-r--r--Documentation/rev-list-options.txt22
-rw-r--r--Documentation/technical/api-allocation-growing.txt3
-rw-r--r--Documentation/technical/api-config.txt155
-rw-r--r--Documentation/technical/api-lockfile.txt254
-rw-r--r--Documentation/technical/api-run-command.txt5
-rw-r--r--Documentation/technical/api-strbuf.txt14
-rw-r--r--Documentation/technical/pack-protocol.txt51
-rw-r--r--Documentation/technical/protocol-capabilities.txt13
43 files changed, 1684 insertions, 315 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile
index cea0e7a..2f6b6aa 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -5,6 +5,7 @@ MAN7_TXT =
TECH_DOCS =
ARTICLES =
SP_ARTICLES =
+OBSOLETE_HTML =
MAN1_TXT += $(filter-out \
$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
@@ -26,6 +27,7 @@ MAN7_TXT += gitcore-tutorial.txt
MAN7_TXT += gitcredentials.txt
MAN7_TXT += gitcvs-migration.txt
MAN7_TXT += gitdiffcore.txt
+MAN7_TXT += giteveryday.txt
MAN7_TXT += gitglossary.txt
MAN7_TXT += gitnamespaces.txt
MAN7_TXT += gitrevisions.txt
@@ -37,11 +39,11 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
-OBSOLETE_HTML = git-remote-helpers.html
+OBSOLETE_HTML += everyday.html
+OBSOLETE_HTML += git-remote-helpers.html
DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
ARTICLES += howto-index
-ARTICLES += everyday
ARTICLES += git-tools
ARTICLES += git-bisect-lk2009
# with their own formatting rules.
@@ -97,6 +99,13 @@ man7dir = $(mandir)/man7
ASCIIDOC = asciidoc
ASCIIDOC_EXTRA =
+ASCIIDOC_HTML = xhtml11
+ASCIIDOC_DOCBOOK = docbook
+ASCIIDOC_CONF = -f asciidoc.conf
+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
+ -agit-version=$(GIT_VERSION)
+TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
+TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
MANPAGE_XSL = manpage-normal.xsl
XMLTO = xmlto
XMLTO_EXTRA =
@@ -304,14 +313,12 @@ clean:
$(MAN_HTML): %.html : %.txt asciidoc.conf
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
- $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
- $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
+ $(TXT_TO_HTML) -d manpage -o $@+ $< && \
mv $@+ $@
$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
- $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
- $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
+ $(TXT_TO_HTML) -o $@+ $< && \
mv $@+ $@
manpage-base-url.xsl: manpage-base-url.xsl.in
@@ -323,13 +330,12 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
%.xml : %.txt asciidoc.conf
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
- $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
- $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
+ $(TXT_TO_XML) -d manpage -o $@+ $< && \
mv $@+ $@
user-manual.xml: user-manual.txt user-manual.conf
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
- $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d article -o $@+ $< && \
+ $(TXT_TO_XML) -d article -o $@+ $< && \
mv $@+ $@
technical/api-index.txt: technical/api-index-skel.txt \
@@ -338,8 +344,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf
- $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
- $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
+ $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
XSLT = docbook.xsl
XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
@@ -386,14 +391,15 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
mv $@+ $@
$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
- $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt
+ $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
WEBDOC_DEST = /pub/software/scm/git/docs
howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
- sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \
+ sed -e '1,/^$$/d' $< | \
+ $(TXT_TO_HTML) - >$@+ && \
mv $@+ $@
install-webdoc : html
diff --git a/Documentation/RelNotes/2.1.1.txt b/Documentation/RelNotes/2.1.1.txt
new file mode 100644
index 0000000..830fc3c
--- /dev/null
+++ b/Documentation/RelNotes/2.1.1.txt
@@ -0,0 +1,44 @@
+Git v2.1.1 Release Notes
+========================
+
+ * Git 2.0 had a regression where "git fetch" into a shallowly
+ cloned repository from a repository with bitmap object index
+ enabled did not work correctly. This has been corrected.
+
+ * Git 2.0 had a regression which broke (rarely used) "git diff-tree
+ -t". This has been corrected.
+
+ * "git log --pretty/format=" with an empty format string did not
+ mean the more obvious "No output whatsoever" but "Use default
+ format", which was counterintuitive. Now it means "nothing shown
+ for the log message part".
+
+ * "git -c section.var command" and "git -c section.var= command"
+ should pass the configuration differently (the former should be a
+ boolean true, the latter should be an empty string), but they
+ didn't work that way. Now it does.
+
+ * Applying a patch not generated by Git in a subdirectory used to
+ check the whitespace breakage using the attributes for incorrect
+ paths. Also whitespace checks were performed even for paths
+ excluded via "git apply --exclude=<path>" mechanism.
+
+ * "git bundle create" with date-range specification were meant to
+ exclude tags outside the range, but it did not work correctly.
+
+ * "git add x" where x that used to be a directory has become a
+ symbolic link to a directory misbehaved.
+
+ * The prompt script checked $GIT_DIR/ref/stash file to see if there
+ is a stash, which was a no-no.
+
+ * "git checkout -m" did not switch to another branch while carrying
+ the local changes forward when a path was deleted from the index.
+
+ * With sufficiently long refnames, fast-import could have overflown
+ an on-stack buffer.
+
+ * After "pack-refs --prune" packed refs at the top-level, it failed
+ to prune them.
+
+ * "git gc --auto" triggered from "git fetch --quiet" was not quiet.
diff --git a/Documentation/RelNotes/2.1.2.txt b/Documentation/RelNotes/2.1.2.txt
new file mode 100644
index 0000000..abc3b89
--- /dev/null
+++ b/Documentation/RelNotes/2.1.2.txt
@@ -0,0 +1,20 @@
+Git v2.1.2 Release Notes
+========================
+
+ * "git push" over HTTP transport had an artificial limit on number of
+ refs that can be pushed imposed by the command line length.
+
+ * When receiving an invalid pack stream that records the same object
+ twice, multiple threads got confused due to a race.
+
+ * An attempt to remove the entire tree in the "git fast-import" input
+ stream caused it to misbehave.
+
+ * Reachability check (used in "git prune" and friends) did not add a
+ detached HEAD as a starting point to traverse objects still in use.
+
+ * "git config --add section.var val" used to lose existing
+ section.var whose value was an empty string.
+
+ * "git fsck" failed to report that it found corrupt objects via its
+ exit status in some cases.
diff --git a/Documentation/RelNotes/2.1.3.txt b/Documentation/RelNotes/2.1.3.txt
new file mode 100644
index 0000000..acc9ebb
--- /dev/null
+++ b/Documentation/RelNotes/2.1.3.txt
@@ -0,0 +1,26 @@
+Git v2.1.3 Release Notes
+========================
+
+ * Some MUAs mangled a line in a message that begins with "From " to
+ ">From " when writing to a mailbox file and feeding such an input to
+ "git am" used to lose such a line.
+
+ * "git daemon" (with NO_IPV6 build configuration) used to incorrectly
+ use the hostname even when gethostbyname() reported that the given
+ hostname is not found.
+
+ * Newer versions of 'meld' breaks the auto-detection we use to see if
+ they are new enough to support the `--output` option.
+
+ * "git pack-objects" forgot to disable the codepath to generate
+ object recheability bitmap when it needs to split the resulting
+ pack.
+
+ * "gitweb" used deprecated CGI::startfrom, which was removed from
+ CGI.pm as of 4.04; use CGI::start_from instead.
+
+ * "git log" documentation had an example section marked up not
+ quite correctly, which passed AsciiDoc but failed with
+ AsciiDoctor.
+
+Also contains some documentation updates.
diff --git a/Documentation/RelNotes/2.2.0.txt b/Documentation/RelNotes/2.2.0.txt
new file mode 100644
index 0000000..826b0e4
--- /dev/null
+++ b/Documentation/RelNotes/2.2.0.txt
@@ -0,0 +1,291 @@
+Git v2.2 Release Notes
+======================
+
+Updates since v2.1
+------------------
+
+Ports
+
+ * Building on older MacOS X systems automatically sets
+ the necessary NO_APPLE_COMMON_CRYPTO build-time option.
+
+ * The support to build with NO_PTHREADS has been resurrected.
+
+ * Compilation options has been updated a bit to support z/OS port
+ better.
+
+
+UI, Workflows & Features
+
+ * "git archive" learned to filter what gets archived with pathspec.
+
+ * "git config --edit --global" starts from a skeletal per-user
+ configuration file contents, instead of a total blank, when the
+ user does not already have any. This immediately reduces the
+ need for a later "Have you forgotten setting core.user?" and we
+ can add more to the template as we gain more experience.
+
+ * "git stash list -p" used to be almost always a no-op because each
+ stash entry is represented as a merge commit. It learned to show
+ the difference between the base commit version and the working tree
+ version, which is in line with what "git show" gives.
+
+ * Sometimes users want to report a bug they experience on their
+ repository, but they are not at liberty to share the contents of
+ the repository. "fast-export" was taught an "--anonymize" option
+ to replace blob contents, names of people and paths and log
+ messages with bland and simple strings to help them.
+
+ * "git difftool" learned an option to stop feeding paths to the
+ diff backend when it exits with a non-zero status.
+
+ * "log --date=iso" uses a slight variant of ISO 8601 format that is
+ made more human readable. A new "--date=iso-strict" option gives
+ datetime output that is more strictly conformant.
+
+ * The logic "git prune" uses is more resilient against various corner
+ cases.
+
+ * A broken reimplementation of Git could write an invalid index that
+ records both stage #0 and higher stage entries for the same path.
+ We now notice and reject such an index, as there is no sensible
+ fallback (we do not know if the broken tool wanted to resolve and
+ forgot to remove higher stage entries, or if it wanted to unresolve
+ and forgot to remove the stage#0 entry).
+
+ * The temporary files "git mergetool" uses are named to avoid too
+ many dots in them (e.g. a temporary file for "hello.c" used to be
+ named e.g. "hello.BASE.4321.c" but now uses underscore instead,
+ e.g. "hello_BASE_4321.c").
+
+ * The temporary files "git mergetools" uses can be placed in a newly
+ creted temporary directory, instead of the current directory, by
+ setting the mergetool.writeToTemp configuration variable.
+
+ * "git mergetool" understands "--tool bc" now, as version 4 of
+ BeyondCompare can be driven the same way as its version 3 and it
+ feels awkward to say "--tool bc3".
+
+ * The "pre-receive" and "post-receive" hooks are no longer required
+ to consume their input fully (not following this requirement used
+ to result in intermittent errors in "git push").
+
+ * The pretty-format specifier "%d", which expanded to " (tagname)"
+ for a tagged commit, gained a cousin "%D" that just gives the
+ "tagname" without frills.
+
+ * "git push" learned "--signed" push, that allows a push (i.e.
+ request to update the refs on the other side to point at a new
+ history, together with the transmission of necessary objects) to be
+ signed, so that it can be verified and audited, using the GPG
+ signature of the person who pushed, that the tips of branches at a
+ public repository really point the commits the pusher wanted to,
+ without having to "trust" the server.
+
+ * "git interpret-trailers" is a new filter to programatically edit
+ the tail end of the commit log messages.
+
+ * "git help everyday" shows the "Everyday Git in 20 commands or so"
+ document, whose contents have been updated to more modern Git
+ practice.
+
+
+Performance, Internal Implementation, etc.
+
+ * The API to manipulate the "refs" has been restructured to make it
+ more transactional, with the eventual goal to allow all-or-none
+ atomic updates and migrating the storage to something other than
+ the traditional filesystem based one (e.g. databases).
+
+ * The lockfile API and its users have been cleaned up.
+
+ * We no longer attempt to keep track of individual dependencies to
+ the header files in the build procedure, relying on automated
+ dependency generation support from modern compilers.
+
+ * In tests, we have been using NOT_{MINGW,CYGWIN} test prerequisites
+ long before negated prerequisites e.g. !MINGW were invented.
+ The former has been converted to the latter to avoid confusion.
+
+ * Looking up remotes configuration in a repository with very many
+ remotes defined has been optimized.
+
+ * There are cases where you lock and open to write a file, close it
+ to show the updated contents to external processes, and then have
+ to update the file again while still holding the lock, but the
+ lockfile API lacked support for such an access pattern.
+
+ * The API to allocate the structure to keep track of commit
+ decoration has been updated to make it less cumbersome to use.
+
+ * An in-core caching layer to let us avoid reading the same
+ configuration files number of times has been added. A few commands
+ have been converted to use this subsystem.
+
+ * Various code paths have been cleaned up and simplified by using
+ "strbuf", "starts_with()", and "skip_prefix()" APIs more.
+
+ * A few codepaths that died when large blobs that would not fit in
+ core are involved in their operation have been taught to punt
+ instead, by e.g. marking too large a blob as not to be diffed.
+
+ * A few more code paths in "commit" and "checkout" have been taught
+ to repopulate the cache-tree in the index, to help speed up later
+ "write-tree" (used in "commit") and "diff-index --cached" (used in
+ "status").
+
+ * A common programming mistake to assign the same short option name
+ to two separate options is detected by parse_options() API to help
+ developers.
+
+ * The code path to write out the packed-refs file has been optimized,
+ which especially matters in a repository with a large number of
+ refs.
+
+ * The check to see if a ref $F can be created by making sure no
+ existing ref has $F/ as its prefix has been optimized, which
+ especially matters in a repository with a large number of existing
+ refs.
+
+ * "git fsck" was taught to check contents of tag objects a bit more.
+
+ * "git hash-object" was taught a "--literally" option to help
+ debugging.
+
+ * When running a required clean filter, we do not have to mmap the
+ original before feeding the filter. Instead, stream the file
+ contents directly to the filter and process its output.
+
+ * The scripts in the test suite can be run with "-x" option to show
+ a shell-trace of each command run in them.
+
+ * The "run-command" API learned to manage the argv and environment
+ array for child process, alleviating the need for the callers to
+ allocate and deallocate them.
+
+ * Some people use AsciiDoctor, instead of AsciiDoc, to format our
+ documentation set; the documentation has been adjusted, as
+ AsciiDoctor is pickier than AsciiDoc in its input mark-up.
+
+
+Also contains various documentation updates and code clean-ups.
+
+
+Fixes since v2.1
+----------------
+
+Unless otherwise noted, all the fixes since v2.1 in the maintenance
+track are contained in this release (see the maintenance releases'
+notes for details).
+
+ * "git log --pretty/format=" with an empty format string did not
+ mean the more obvious "No output whatsoever" but "Use default
+ format", which was counterintuitive.
+
+ * "git -c section.var command" and "git -c section.var= command"
+ should pass the configuration differently (the former should be a
+ boolean true, the latter should be an empty string).
+
+ * Applying a patch not generated by Git in a subdirectory used to
+ check the whitespace breakage using the attributes for incorrect
+ paths. Also whitespace checks were performed even for paths
+ excluded via "git apply --exclude=<path>" mechanism.
+
+ * "git bundle create" with date-range specification were meant to
+ exclude tags outside the range, but it didn't.
+
+ * "git add x" where x that used to be a directory has become a
+ symbolic link to a directory misbehaved.
+
+ * The prompt script checked $GIT_DIR/ref/stash file to see if there
+ is a stash, which was a no-no.
+
+ * Pack-protocol documentation had a minor typo.
+
+ * "git checkout -m" did not switch to another branch while carrying
+ the local changes forward when a path was deleted from the index.
+
+ * "git daemon" (with NO_IPV6 build configuration) used to incorrectly
+ use the hostname even when gethostbyname() reported that the given
+ hostname is not found.
+ (merge 107efbe rs/daemon-fixes later to maint).
+
+ * With sufficiently long refnames, "git fast-import" could have
+ overflown an on-stack buffer.
+
+ * After "pack-refs --prune" packed refs at the top-level, it failed
+ to prune them.
+
+ * Progress output from "git gc --auto" was visible in "git fetch -q".
+
+ * We used to pass -1000 to poll(2), expecting it to also mean "no
+ timeout", which should be spelled as -1.
+
+ * "git rebase" documentation was unclear that it is required to
+ specify on what <upstream> the rebase is to be done when telling it
+ to first check out <branch>.
+ (merge 95c6826 so/rebase-doc later to maint).
+
+ * "git push" over HTTP transport had an artificial limit on number of
+ refs that can be pushed imposed by the command line length.
+ (merge 26be19b jk/send-pack-many-refspecs later to maint).
+
+ * When receiving an invalid pack stream that records the same object
+ twice, multiple threads got confused due to a race.
+ (merge ab791dd jk/index-pack-threading-races later to maint).
+
+ * An attempt to remove the entire tree in the "git fast-import" input
+ stream caused it to misbehave.
+ (merge 2668d69 mb/fast-import-delete-root later to maint).
+
+ * Reachability check (used in "git prune" and friends) did not add a
+ detached HEAD as a starting point to traverse objects still in use.
+ (merge c40fdd0 mk/reachable-protect-detached-head later to maint).
+
+ * "git config --add section.var val" used to lose existing
+ section.var whose value was an empty string.
+ (merge c1063be ta/config-add-to-empty-or-true-fix later to maint).
+
+ * "git fsck" failed to report that it found corrupt objects via its
+ exit status in some cases.
+ (merge 30d1038 jk/fsck-exit-code-fix later to maint).
+
+ * Use of "--verbose" option used to break "git branch --merged".
+ (merge 12994dd jk/maint-branch-verbose-merged later to maint).
+
+ * Some MUAs mangled a line in a message that begins with "From " to
+ ">From " when writing to a mailbox file and feeding such an input
+ to "git am" used to lose such a line.
+ (merge 85de86a jk/mbox-from-line later to maint).
+
+ * "rev-parse --verify --quiet $name" is meant to quietly exit with a
+ non-zero status when $name is not a valid object name, but still
+ gave error messages in some cases.
+
+ * A handful of C source files have been updated to include
+ "git-compat-util.h" as the first thing, to conform better to our
+ coding guidelines.
+ (merge 1c4b660 da/include-compat-util-first-in-c later to maint).
+
+ * t7004 test, which tried to run Git with small stack space, has been
+ updated to give a bit larger stack to avoid false breakage on some
+ platforms.
+ (merge b9a1907 sk/tag-contains-wo-recursion later to maint).
+
+ * A few documentation pages had example sections marked up not quite
+ correctly, which passed AsciiDoc but failed with AsciiDoctor.
+ (merge c30c43c bc/asciidoc-pretty-formats-fix later to maint).
+ (merge f8a48af bc/asciidoc later to maint).
+
+ * "gitweb" used deprecated CGI::startfrom, which was removed from
+ CGI.pm as of 4.04; use CGI::start_from instead.
+ (merge 4750f4b rm/gitweb-start-form later to maint).
+
+ * Newer versions of 'meld' breaks the auto-detection we use to see if
+ they are new enough to support the `--output` option.
+ (merge b12d045 da/mergetool-meld later to maint).
+
+ * "git pack-objects" forgot to disable the codepath to generate
+ object recheability bitmap when it needs to split the resulting
+ pack.
+ (merge 2113471 jk/pack-objects-no-bitmap-when-splitting later to maint).
diff --git a/Documentation/config.txt b/Documentation/config.txt
index c55c22a..7a3294d 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -204,13 +204,26 @@ advice.*::
--
core.fileMode::
- If false, the executable bit differences between the index and
- the working tree are ignored; useful on broken filesystems like FAT.
- See linkgit:git-update-index[1].
+ Tells Git if the executable bit of files in the working tree
+ is to be honored.
+
-The default is true, except linkgit:git-clone[1] or linkgit:git-init[1]
-will probe and set core.fileMode false if appropriate when the
-repository is created.
+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.
+linkgit:git-clone[1] or linkgit:git-init[1] 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 linkgit:git-update-index[1].
++
+The default is true (when core.filemode is not specified in the config file).
core.ignorecase::
If true, this option enables various workarounds to enable
@@ -499,7 +512,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
@@ -871,7 +885,11 @@ color.grep.<slot>::
`linenumber`;;
line number prefix (when using `-n`)
`match`;;
- matching text
+ matching text (same as setting `matchContext` and `matchSelected`)
+`matchContext`;;
+ matching text in context lines
+`matchSelected`;;
+ matching text in selected lines
`selected`;;
non-matching text in selected lines
`separator`;;
@@ -1754,6 +1772,15 @@ mergetool.<tool>.trustExitCode::
if the file has been updated, otherwise the user is prompted to
indicate the success of the merge.
+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::
After performing a merge, the original file with conflict markers
can be saved as a file with a `.orig` extension. If this variable
@@ -1767,6 +1794,12 @@ mergetool.keepTemporaries::
preserved, otherwise they will be removed after the tool has
exited. Defaults to `false`.
+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::
Prompt before each invocation of the merge resolution program.
@@ -1827,10 +1860,11 @@ pack.depth::
maximum depth is given on the command line. Defaults to 50.
pack.windowMemory::
- The window memory size limit used by linkgit:git-pack-objects[1]
- 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 linkgit:git-pack-objects[1] 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.
pack.compression::
An integer -1..9, indicating the compression level for objects
@@ -2043,6 +2077,25 @@ receive.autogc::
receiving data from git-push and updating refs. You can stop
it by setting this variable to false.
+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::
If it is set to true, git-receive-pack will check all received
objects. It will abort in the case of a malformed object or a
diff --git a/Documentation/everyday.txto b/Documentation/everyday.txto
new file mode 100644
index 0000000..c5047d8
--- /dev/null
+++ b/Documentation/everyday.txto
@@ -0,0 +1,9 @@
+Everyday Git With 20 Commands Or So
+===================================
+
+This document has been moved to linkgit:giteveryday[1].
+
+Please let the owners of the referring site know so that they can update the
+link you clicked to get here.
+
+Thanks.
diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
index d15db42..7051c6b 100644
--- a/Documentation/git-credential-cache--daemon.txt
+++ b/Documentation/git-credential-cache--daemon.txt
@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory
SYNOPSIS
--------
[verse]
-git credential-cache--daemon <socket>
+git credential-cache--daemon [--debug] <socket>
DESCRIPTION
-----------
@@ -21,6 +21,10 @@ for `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
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 11887e6..333cf6f 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -91,6 +91,15 @@ instead. `--no-symlinks` is the default on Windows.
the default diff tool will be read from the configured
`diff.guitool` variable instead of `diff.tool`.
+--[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 linkgit:git-diff[1] for the full list of supported options.
CONFIG VARIABLES
@@ -116,6 +125,11 @@ See the `--tool=<tool>` option above for more details.
difftool.prompt::
Prompt before each invocation of the diff tool.
+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.
+
SEE ALSO
--------
linkgit:git-diff[1]::
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 221506b..dbe9a46 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -105,6 +105,11 @@ marks the same across runs.
in the commit (as opposed to just listing the files which are
different from the commit's first parent).
+--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.
@@ -141,6 +146,62 @@ 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
-----------
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 875d283..c7c0d21 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -38,18 +38,17 @@ Variables
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.
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.
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.
imap.user::
The username to use when logging in to the server.
@@ -76,7 +75,8 @@ imap.preformattedHTML::
imap.authMethod::
Specify authenticate method for authentication with IMAP server.
- Current supported method is 'CRAM-MD5' only.
+ Current supported method is 'CRAM-MD5' only. If this is not set
+ then 'git imap-send' uses the basic IMAP plaintext LOGIN command.
Examples
~~~~~~~~
@@ -97,7 +97,7 @@ Using direct mode:
host = imap://imap.example.com
user = bob
pass = p4ssw0rd
-..........................
+.........................
Using direct mode with SSL:
@@ -109,7 +109,7 @@ Using direct mode with SSL:
pass = p4ssw0rd
port = 123
sslverify = false
-..........................
+.........................
EXAMPLE
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index afd721e..369f889 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -43,7 +43,7 @@ OPTIONS
-q::
--quiet::
-Only print error and warning messages, all other output will be suppressed.
+Only print error and warning messages; all other output will be suppressed.
--bare::
@@ -57,12 +57,12 @@ DIRECTORY" section below.)
--separate-git-dir=<git dir>::
-Instead of initializing the repository where it is supposed to be,
-place a filesytem-agnostic Git symbolic link there, pointing to the
-specified 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.
--shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
@@ -72,60 +72,65 @@ 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
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'): 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.
+'group' (or 'true')::
- - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository
- readable by all users.
+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.
- - '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.
+'all' (or 'world' or 'everybody')::
-By default, the configuration flag receive.denyNonFastForwards is enabled
+Same as 'group', but make the repository readable by all users.
+
+'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.
+--
+
+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 linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]).
EXAMPLES
--------
@@ -136,10 +141,12 @@ Start a new Git repository for an existing code base::
$ cd /path/to/my/codebase
$ git init <1>
$ git add . <2>
+$ git commit <3>
----------------
+
-<1> prepare /path/to/my/codebase/.git directory
-<2> add all existing file to the index
+<1> Create a /path/to/my/codebase/.git directory.
+<2> Add all existing files to the index.
+<3> Record the pristine state as the first commit in the history.
GIT
---
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
new file mode 100644
index 0000000..81fac3d
--- /dev/null
+++ b/Documentation/git-interpret-trailers.txt
@@ -0,0 +1,314 @@
+git-interpret-trailers(1)
+=========================
+
+NAME
+----
+git-interpret-trailers - help add stuctured information into commit messages
+
+SYNOPSIS
+--------
+[verse]
+'git interpret-trailers' [--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 ouput, 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
+indide 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
+-------
+--trim-empty::
+ If the <value> part of any trailer contains only whitespace,
+ the whole trailer will be removed from the resulting message.
+ This apply 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>
+------------
+
+* 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
+--------
+linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
index 6738055..9fed59a 100644
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.txt
@@ -1,5 +1,5 @@
git-prune-packed(1)
-=====================
+===================
NAME
----
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index c0d7403..21b3f29 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -10,7 +10,8 @@ SYNOPSIS
--------
[verse]
'git push' [--all | --mirror | --tags] [--follow-tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
- [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream]
+ [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose]
+ [-u | --set-upstream] [--signed]
[--force-with-lease[=<refname>[:<expect>]]]
[--no-verify] [<repository> [<refspec>...]]
@@ -33,7 +34,7 @@ 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 linkgit:git-config[1] for the meaning of `push.default`).
+what to push (See gitlink:git-config[1] for the meaning of `push.default`).
OPTIONS[[OPTIONS]]
@@ -129,6 +130,12 @@ already exists on the remote side.
from the remote but are pointing at commit-ish that are
reachable from the refs being pushed.
+--signed::
+ 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. See linkgit:git-receive-pack[1] for the details
+ on the receiving end.
+
--receive-pack=<git-receive-pack>::
--exec=<git-receive-pack>::
Path to the 'git-receive-pack' program on the remote
diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt
index a356196..d64388c 100644
--- a/Documentation/git-quiltimport.txt
+++ b/Documentation/git-quiltimport.txt
@@ -1,5 +1,5 @@
git-quiltimport(1)
-================
+==================
NAME
----
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 2a93c64..924827d 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -9,7 +9,7 @@ SYNOPSIS
--------
[verse]
'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
@@ -21,15 +21,17 @@ If <branch> is specified, 'git rebase' will perform an automatic
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
-linkgit:git-config[1] 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
+linkgit:git-config[1] 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
@@ -316,11 +318,8 @@ which makes little sense.
-f::
--force-rebase::
- 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
@@ -330,13 +329,18 @@ link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details)
--fork-point::
--no-fork-point::
- Use 'git merge-base --fork-point' to find a better common ancestor
- between `upstream` and `branch` when calculating which commits have
- have been introduced by `branch` (see linkgit:git-merge-base[1]).
+ 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 linkgit:git-merge-base[1]). If 'fork_point'
+ends up being empty, the <upstream> will be used as a fallback.
+
-If no non-option arguments are given on the command line, then the default is
-`--fork-point @{u}` otherwise the `upstream` argument is interpreted literally
-unless the `--fork-point` option is specified.
+If either <upstream> or --root is given on the command line, then the
+default is `--no-fork-point`, otherwise the default is `--fork-point`.
--ignore-whitespace::
--whitespace=<option>::
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index b1f7dc6..9016960 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -53,6 +53,56 @@ 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 linkgit:git-push[1]), 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 linkgit:git-log[1]).
+
+`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
+ linkgit:git-config[1].
+
This hook is called before any refname is updated and before any
fast-forward checks are performed.
@@ -101,9 +151,14 @@ the update. Refs that were created will have sha1-old 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.
@@ -119,6 +174,14 @@ ref listing the commits pushed to the repository:
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
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 7a1585d..fd7f8b5 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -45,7 +45,7 @@ SYNOPSIS
[ \--regexp-ignore-case | -i ]
[ \--extended-regexp | -E ]
[ \--fixed-strings | -F ]
- [ \--date=(local|relative|default|iso|rfc|short) ]
+ [ \--date=(local|relative|default|iso|iso-strict|rfc|short) ]
[ [\--objects | \--objects-edge] [ \--unpacked ] ]
[ \--pretty | \--header ]
[ \--bisect ]
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 0b84769..fa4a8c3 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -114,6 +114,7 @@ can be used.
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.
--sq::
Usually the output is made one line per flag and
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index dc3a568..2a0de42 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -35,6 +35,16 @@ OPTIONS
Instead of explicitly specifying which refs to update,
update all heads that locally exist.
+--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::
Do everything except actually send the updates.
@@ -77,7 +87,8 @@ 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/Documentation/git-stage.txt b/Documentation/git-stage.txt
index ba3fe0d..25bcda9 100644
--- a/Documentation/git-stage.txt
+++ b/Documentation/git-stage.txt
@@ -1,5 +1,5 @@
git-stage(1)
-==============
+============
NAME
----
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index def635f..4d8d530 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -116,7 +116,7 @@ In the short-format, the status of each path is shown as
where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is
shown only when `PATH1` corresponds to a different path in the
-index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
+index/worktree (i.e. the file is renamed). The `XY` is a two-letter
status code.
The fields (including the `->`) are separated from each other by a
@@ -125,7 +125,7 @@ characters, that field will be quoted in the manner of a C string
literal: surrounded by ASCII double quote (34) characters, and with
interior special characters backslash-escaped.
-For paths with merge conflicts, `X` and 'Y' show the modification
+For paths with merge conflicts, `X` and `Y` show the modification
states of each side of the merge. For paths that do not have merge
conflicts, `X` shows the status of the index, and `Y` shows the status
of the work tree. For untracked paths, `XY` are `??`. Other status
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 44c970c..ef8ef1c 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -386,11 +386,13 @@ Any other arguments are passed directly to 'git log'
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
@@ -608,21 +610,6 @@ config key: svn.authorsfile
Make 'git svn' less verbose. Specify a second time to make it
even less verbose.
---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'.
-+
-[verse]
-config key: svn.repack
-config key: svn.repackflags
-
-m::
--merge::
-s<strategy>::
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 3209083..e953ba4 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -42,7 +42,7 @@ 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"
+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
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index dfc09d9..82eca6f 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -202,7 +202,7 @@ 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
diff --git a/Documentation/git.txt b/Documentation/git.txt
index de7b870..9202010 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -22,7 +22,7 @@ unusually rich command set that provides both high-level operations
and full access to internals.
See linkgit:gittutorial[7] to get started, then see
-link:everyday.html[Everyday Git] for a useful minimum set of
+linkgit:giteveryday[7] for a useful minimum set of
commands. The link:user-manual.html[Git User's Manual] has a more
in-depth introduction.
@@ -43,9 +43,12 @@ unreleased) version of Git, that is available from the 'master'
branch of the `git.git` repository.
Documentation for older releases are available here:
-* link:v2.1.0/git.html[documentation for release 2.1]
+* link:v2.1.3/git.html[documentation for release 2.1.3]
* release notes for
+ link:RelNotes/2.1.3.txt[2.1.3],
+ link:RelNotes/2.1.2.txt[2.1.2],
+ link:RelNotes/2.1.1.txt[2.1.1],
link:RelNotes/2.1.0.txt[2.1].
* link:v2.0.4/git.html[documentation for release 2.0.4]
@@ -452,6 +455,11 @@ example the following invocations are equivalent:
given will override values from configuration files.
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.
--exec-path[=<path>]::
Path to wherever your core Git programs are installed.
@@ -1091,7 +1099,7 @@ subscribed to the list to send a message there.
SEE ALSO
--------
linkgit:gittutorial[7], linkgit:gittutorial-2[7],
-link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7],
+linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
linkgit:gitworkflows[7]
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 643c1ba..9b45bda 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -440,8 +440,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`.
String::
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index d2d7c21..8475c07 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -1667,7 +1667,7 @@ linkgit:gittutorial[7],
linkgit:gittutorial-2[7],
linkgit:gitcvs-migration[7],
linkgit:git-help[1],
-link:everyday.html[Everyday git],
+linkgit:giteveryday[7],
link:user-manual.html[The Git User's Manual]
GIT
diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt
index 5f4e890..b06e852 100644
--- a/Documentation/gitcvs-migration.txt
+++ b/Documentation/gitcvs-migration.txt
@@ -194,7 +194,7 @@ linkgit:gittutorial[7],
linkgit:gittutorial-2[7],
linkgit:gitcore-tutorial[7],
linkgit:gitglossary[7],
-link:everyday.html[Everyday Git],
+linkgit:giteveryday[7],
link:user-manual.html[The Git User's Manual]
GIT
diff --git a/Documentation/everyday.txt b/Documentation/giteveryday.txt
index b2548ef..7be6e64 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/giteveryday.txt
@@ -1,22 +1,37 @@
+giteveryday(7)
+===============
+
+NAME
+----
+giteveryday - A useful minimum set of commands for Everyday Git
+
+SYNOPSIS
+--------
+
Everyday Git With 20 Commands Or So
-===================================
-<<Individual Developer (Standalone)>> commands are essential for
-anybody who makes a commit, even for somebody who works alone.
+DESCRIPTION
+-----------
-If you work with other people, you will need commands listed in
-the <<Individual Developer (Participant)>> section as well.
+Git users can broadly be grouped into four categories for the purposes of
+describing here a small set of useful command for everyday Git.
-People who play the <<Integrator>> role need to learn some more
-commands in addition to the above.
+* <<STANDALONE,Individual Developer (Standalone)>> commands are essential
+ for anybody who makes a commit, even for somebody who works alone.
-<<Repository Administration>> commands are for system
-administrators who are responsible for the care and feeding
-of Git repositories.
+* If you work with other people, you will need commands listed in
+ the <<PARTICIPANT,Individual Developer (Participant)>> section as well.
+* People who play the <<INTEGRATOR,Integrator>> role need to learn some
+ more commands in addition to the above.
-Individual Developer (Standalone)[[Individual Developer (Standalone)]]
-----------------------------------------------------------------------
+* <<ADMINISTRATION,Repository Administration>> commands are for system
+ administrators who are responsible for the care and feeding
+ of Git repositories.
+
+
+Individual Developer (Standalone)[[STANDALONE]]
+-----------------------------------------------
A standalone individual developer does not exchange patches with
other people, and works alone in a single repository, using the
@@ -24,8 +39,6 @@ following commands.
* linkgit:git-init[1] to create a new repository.
- * linkgit:git-show-branch[1] to see where you are.
-
* linkgit:git-log[1] to see what happened.
* linkgit:git-checkout[1] and linkgit:git-branch[1] to switch
@@ -45,7 +58,7 @@ following commands.
* linkgit:git-rebase[1] to maintain topic branches.
- * linkgit:git-tag[1] to mark known point.
+ * linkgit:git-tag[1] to mark a known point.
Examples
~~~~~~~~
@@ -75,14 +88,12 @@ $ edit/compile/test
$ git diff HEAD <4>
$ git commit -a -s <5>
$ edit/compile/test
-$ git reset --soft HEAD^ <6>
-$ edit/compile/test
-$ git diff ORIG_HEAD <7>
-$ git commit -a -c ORIG_HEAD <8>
-$ git checkout master <9>
-$ git merge alsa-audio <10>
-$ git log --since='3 days ago' <11>
-$ git log v2.43.. curses/ <12>
+$ git diff HEAD^ <6>
+$ git commit -a --amend <7>
+$ git checkout master <8>
+$ git merge alsa-audio <9>
+$ git log --since='3 days ago' <10>
+$ git log v2.43.. curses/ <11>
------------
+
<1> create a new topic branch.
@@ -90,22 +101,21 @@ $ git log v2.43.. curses/ <12>
<3> you need to tell Git if you added a new file; removal and
modification will be caught if you do `git commit -a` later.
<4> to see what changes you are committing.
-<5> commit everything as you have tested, with your sign-off.
-<6> take the last commit back, keeping what is in the working tree.
-<7> look at the changes since the premature commit we took back.
-<8> redo the commit undone in the previous step, using the message
-you originally wrote.
-<9> switch to the master branch.
-<10> merge a topic branch into your master branch.
-<11> review commit logs; other forms to limit output can be
-combined and include `--max-count=10` (show 10 commits),
+<5> commit everything, as you have tested, with your sign-off.
+<6> look at all your changes including the previous commit.
+<7> amend the previous commit, adding all your new changes,
+using your original message.
+<8> switch to the master branch.
+<9> merge a topic branch into your master branch.
+<10> 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.
-<12> view only the changes that touch what's in `curses/`
+<11> view only the changes that touch what's in `curses/`
directory, since `v2.43` tag.
-Individual Developer (Participant)[[Individual Developer (Participant)]]
-------------------------------------------------------------------------
+Individual Developer (Participant)[[PARTICIPANT]]
+-------------------------------------------------
A developer working as a participant in a group project needs to
learn how to communicate with others, and uses these commands in
@@ -123,6 +133,13 @@ addition to the ones needed by a standalone developer.
* linkgit:git-format-patch[1] to prepare e-mail submission, if
you adopt Linux kernel-style public forum workflow.
+ * linkgit:git-send-email[1] to send your e-mail submission without
+ corruption by your MUA.
+
+ * linkgit:git-request-pull[1] to create a summary of changes
+ for your upstream to pull.
+
+
Examples
~~~~~~~~
@@ -131,28 +148,34 @@ Clone the upstream and work on it. Feed changes to upstream.::
------------
$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
$ cd my2.6
-$ edit/compile/test; git commit -a -s <1>
-$ git format-patch origin <2>
-$ git pull <3>
-$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
-$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
-$ git reset --hard ORIG_HEAD <6>
-$ git gc <7>
-$ git fetch --tags <8>
+$ git checkout -b mine master <1>
+$ edit/compile/test; git commit -a -s <2>
+$ git format-patch master <3>
+$ git send-email --to="person <email@example.com>" 00*.patch <4>
+$ git checkout master <5>
+$ git pull <6>
+$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>
+$ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>
+$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <9>
+$ git reset --hard ORIG_HEAD <10>
+$ git gc <11>
------------
+
-<1> repeat as needed.
-<2> extract patches from your branch for e-mail submission.
-<3> `git pull` fetches from `origin` by default and merges into the
+<1> checkout a new branch `mine` from master.
+<2> repeat as needed.
+<3> extract patches from your branch, relative to master,
+<4> and email them.
+<5> return to `master`, ready to see what's new
+<6> `git pull` fetches from `origin` by default and merges into the
current branch.
-<4> immediately after pulling, look at the changes done upstream
+<7> immediately after pulling, look at the changes done upstream
since last time we checked, only in the
area we are interested in.
-<5> fetch from a specific branch from a specific repository and merge.
-<6> revert the pull.
-<7> garbage collect leftover objects from reverted pull.
-<8> from time to time, obtain official tags from the `origin`
-and store them under `.git/refs/tags/`.
+<8> check the branch names in an external repository (if not known).
+<9> fetch from a specific branch `ALL` from a specific repository
+and merge it.
+<10> revert the pull.
+<11> garbage collect leftover objects from reverted pull.
Push into another repository.::
@@ -166,7 +189,7 @@ 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 <3>
+ +refs/heads/*:refs/remotes/satellite/* <3>
satellite$ edit/compile/test/commit
satellite$ git push origin <4>
@@ -181,11 +204,12 @@ machine.
<2> 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.
-<3> arrange `git push` to push local `master` branch to
-`remotes/satellite/master` branch of the mothership machine.
-<4> 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.
+<3> arrange `git push` to push all local branches to
+their corresponding branch of the mothership machine.
+<4> 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).
<5> on mothership machine, merge the work done on the satellite
machine into the master branch.
@@ -195,17 +219,22 @@ Branch off of a specific tag.::
$ git checkout -b private2.6.14 v2.6.14 <1>
$ edit/compile/test; git commit -a
$ git checkout master
-$ git format-patch -k -m --stdout v2.6.14..private2.6.14 |
- git am -3 -k <2>
+$ git cherry-pick v2.6.14..private2.6.14 <2>
------------
+
<1> create a private branch based on a well known (but somewhat behind)
tag.
<2> forward port all changes in `private2.6.14` branch to `master` branch
-without a formal "merging".
+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[[Integrator]]
+Integrator[[INTEGRATOR]]
------------------------
A fairly central person acting as the integrator in a group
@@ -213,6 +242,13 @@ 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.
+
+
* linkgit:git-am[1] to apply patches e-mailed in from your
contributors.
@@ -229,19 +265,19 @@ commands in addition to the ones needed by participants.
Examples
~~~~~~~~
-My typical Git day.::
+A typical integrator's Git day.::
+
------------
$ git status <1>
-$ git show-branch <2>
+$ git branch --no-merged master <2>
$ mailx <3>
& 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 <4>
+$ git am -3 -i -s ./+to-apply <4>
$ compile/test
-$ git checkout -b hold/linus && git am -3 -i -s -u ./+hold-linus <5>
+$ git checkout -b hold/linus && git am -3 -i -s ./+hold-linus <5>
$ git checkout topic/one && git rebase master <6>
$ git checkout pu && git reset --hard next <7>
$ git merge topic/one topic/two && git merge hold/linus <8>
@@ -249,51 +285,51 @@ $ git checkout maint
$ git cherry-pick master~4 <9>
$ compile/test
$ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>
-$ git fetch ko && git show-branch master maint 'tags/ko-*' <11>
-$ git push ko <12>
-$ git push ko v0.99.9x <13>
+$ git fetch ko && for branch in master maint next pu <11>
+ do
+ git show-branch ko/$branch $branch <12>
+ done
+$ git push --follow-tags ko <13>
------------
+
-<1> see what I was in the middle of doing, if any.
-<2> see what topic branches I have and think about how ready
-they are.
+<1> see what you were in the middle of doing, if anything.
+<2> see which branches haven't been merged into `master` yet.
+Likewise for any other integration branches e.g. `maint`, `next`
+and `pu` (potential updates).
<3> read mails, save ones that are applicable, and save others
-that are not quite ready.
-<4> apply them, interactively, with my sign-offs.
-<5> create topic branch as needed and apply, again with my
-sign-offs.
+that are not quite ready (other mail readers are available).
+<4> apply them, interactively, with your sign-offs.
+<5> create topic branch as needed and apply, again with sign-offs.
<6> rebase internal topic branch that has not been merged to the
master or exposed as a part of a stable branch.
<7> restart `pu` every time from the next.
<8> and bundle topic branches still cooking.
<9> backport a critical fix.
<10> create a signed tag.
-<11> make sure I did not accidentally rewind master beyond what I
-already pushed out. `ko` shorthand points at the repository I have
-at kernel.org, and looks like this:
+<11> 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:
+
------------
-$ 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 .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.
-
-<12> push out the bleeding edge.
-<13> push the tag out, too.
+<12> In the output from `git show-branch`, `master` should have
+everything `ko/master` has, and `next` should have
+everything `ko/next` has, etc.
+<13> push out the bleeding edge, together with new tags that point
+into the pushed history.
-Repository Administration[[Repository Administration]]
-------------------------------------------------------
+Repository Administration[[ADMINISTRATION]]
+-------------------------------------------
A repository administrator uses the following tools to set up
and maintain access to the repository by developers.
@@ -304,9 +340,19 @@ and maintain access to the repository by developers.
* linkgit:git-shell[1] can be used as a 'restricted login shell'
for shared central repository users.
+ * linkgit:git-http-backend[1] provides a server side implementation
+ of Git-over-HTTP ("Smart http") allowing both fetch and push services.
+
+ * linkgit:gitweb[1] provides a web front-end to Git repositories,
+ which can be set-up using the linkgit:git-instaweb[1] 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
~~~~~~~~
@@ -335,22 +381,25 @@ $ cat /etc/xinetd.d/git-daemon
# 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
+ 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.::
+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 <1>
@@ -363,8 +412,8 @@ $ grep git /etc/shells <2>
------------
+
<1> log-in shell is set to /usr/bin/git-shell, which does not
-allow anything but `git push` and `git pull`. The users should
-get an ssh access to the machine.
+allow anything but `git push` and `git pull`. The users require
+ssh access to the machine.
<2> in many distributions /etc/shells needs to list what is used
as the login shell.
@@ -401,13 +450,6 @@ for branch policy control.
david is the release manager and is the only person who can
create and push version tags.
-HTTP server to support dumb protocol transfer.::
-+
-------------
-dev$ git update-server-info <1>
-dev$ ftp user@isp.example.com <2>
-ftp> cp -r .git /home/user/myproject.git
-------------
-+
-<1> make sure your info/refs and objects/info/packs are up-to-date
-<2> upload to public HTTP server hosted by your ISP.
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitglossary.txt b/Documentation/gitglossary.txt
index e52de7d..212e254 100644
--- a/Documentation/gitglossary.txt
+++ b/Documentation/gitglossary.txt
@@ -19,7 +19,7 @@ SEE ALSO
linkgit:gittutorial[7],
linkgit:gittutorial-2[7],
linkgit:gitcvs-migration[7],
-link:everyday.html[Everyday Git],
+linkgit:giteveryday[7],
link:user-manual.html[The Git User's Manual]
GIT
diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt
index 3109ea8..f6fbf81 100644
--- a/Documentation/gittutorial-2.txt
+++ b/Documentation/gittutorial-2.txt
@@ -403,7 +403,7 @@ 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 linkgit:giteveryday[7]. You
should be able to find any unknown jargon in linkgit:gitglossary[7].
The link:user-manual.html[Git User's Manual] provides a more
@@ -427,7 +427,7 @@ linkgit:gitcvs-migration[7],
linkgit:gitcore-tutorial[7],
linkgit:gitglossary[7],
linkgit:git-help[1],
-link:everyday.html[Everyday Git],
+linkgit:giteveryday[7],
link:user-manual.html[The Git User's Manual]
GIT
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
index 8262196..af9f709 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -656,7 +656,7 @@ digressions that may be interesting at this point are:
* linkgit:gitworkflows[7]: Gives an overview of recommended
workflows.
- * link:everyday.html[Everyday Git with 20 Commands Or So]
+ * linkgit:giteveryday[7]: Everyday Git with 20 Commands Or So.
* linkgit:gitcvs-migration[7]: Git for CVS users.
@@ -668,7 +668,7 @@ linkgit:gitcore-tutorial[7],
linkgit:gitglossary[7],
linkgit:git-help[1],
linkgit:gitworkflows[7],
-link:everyday.html[Everyday Git],
+linkgit:giteveryday[7],
link:user-manual.html[The Git User's Manual]
GIT
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 85d6353..dcf7429 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -95,7 +95,7 @@ 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:
@@ -115,19 +115,22 @@ The placeholders are:
- '%aD': author date, RFC2822 style
- '%ar': author date, relative
- '%at': author date, UNIX timestamp
-- '%ai': author date, ISO 8601 format
+- '%ai': author date, ISO 8601-like format
+- '%aI': author date, strict ISO 8601 format
- '%cn': committer name
- '%cN': committer name (respecting .mailmap, see
linkgit:git-shortlog[1] or linkgit:git-blame[1])
- '%ce': committer email
- '%cE': committer email (respecting .mailmap, see
linkgit:git-shortlog[1] or linkgit:git-blame[1])
-- '%cd': committer date
+- '%cd': committer date (format respects --date= option)
- '%cD': committer date, RFC2822 style
- '%cr': committer date, relative
- '%ct': committer date, UNIX timestamp
-- '%ci': committer date, ISO 8601 format
+- '%ci': committer date, ISO 8601-like format
+- '%cI': committer date, strict ISO 8601 format
- '%d': ref names, like the --decorate option of linkgit:git-log[1]
+- '%D': ref names without the " (", ")" wrapping.
- '%e': encoding
- '%s': subject
- '%f': sanitized subject line, suitable for a filename
@@ -182,8 +185,9 @@ The placeholders are:
NOTE: 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
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index deb8cca..3301fde 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -168,6 +168,15 @@ respectively, and they must begin with `refs/` when applied to `--glob`
or `--all`. If a trailing '/{asterisk}' is intended, it must be given
explicitly.
+--reflog::
+ Pretend as if all objects mentioned by reflogs are listed on the
+ command line as `<commit>`.
+
+--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.
+
--ignore-missing::
Upon seeing an invalid object name in the input, pretend as if
the bad input was not given.
@@ -677,7 +686,7 @@ include::pretty-options.txt[]
--relative-date::
Synonym for `--date=relative`.
---date=(relative|local|default|iso|rfc|short|raw)::
+--date=(relative|local|default|iso|iso-strict|rfc|short|raw)::
Only takes effect for dates shown in human-readable format, such
as when using `--pretty`. `log.date` config variable sets a default
value for the log command's `--date` option.
@@ -687,7 +696,16 @@ e.g. ``2 hours ago''.
+
`--date=local` shows timestamps in user's local time zone.
+
-`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format.
+`--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 email messages.
diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt
index 542946b..5a59b54 100644
--- a/Documentation/technical/api-allocation-growing.txt
+++ b/Documentation/technical/api-allocation-growing.txt
@@ -34,3 +34,6 @@ item[nr++] = value you like;
------------
You are responsible for updating the `nr` variable.
+
+If you need to specify the number of elements to allocate explicitly
+then use the macro `REALLOC_ARRAY(item, alloc)` instead of `ALLOC_GROW`.
diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index edd5018..0d8b99b 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -77,6 +77,99 @@ To read a specific file in git-config format, use
`git_config_from_file`. This takes the same callback and data parameters
as `git_config`.
+Querying For Specific Variables
+-------------------------------
+
+For programs wanting to query for specific variables in a non-callback
+manner, the config API provides two functions `git_config_get_value`
+and `git_config_get_value_multi`. They both read values from an internal
+cache generated previously from reading the config files.
+
+`int git_config_get_value(const char *key, const char **value)`::
+
+ Finds the highest-priority value for the configuration variable `key`,
+ stores the pointer to it in `value` and returns 0. When the
+ configuration variable `key` is not found, returns 1 without touching
+ `value`. The caller should not free or modify `value`, as it is owned
+ by the cache.
+
+`const struct string_list *git_config_get_value_multi(const char *key)`::
+
+ Finds and returns the value list, sorted in order of increasing priority
+ for the configuration variable `key`. When the configuration variable
+ `key` is not found, returns NULL. The caller should not free or modify
+ the returned pointer, as it is owned by the cache.
+
+`void git_config_clear(void)`::
+
+ Resets and invalidates the config cache.
+
+The config API also provides type specific API functions which do conversion
+as well as retrieval for the queried variable, including:
+
+`int git_config_get_int(const char *key, int *dest)`::
+
+ Finds and parses the value to an integer for the configuration variable
+ `key`. Dies on error; otherwise, stores the value of the parsed integer in
+ `dest` and returns 0. When the configuration variable `key` is not found,
+ returns 1 without touching `dest`.
+
+`int git_config_get_ulong(const char *key, unsigned long *dest)`::
+
+ Similar to `git_config_get_int` but for unsigned longs.
+
+`int git_config_get_bool(const char *key, int *dest)`::
+
+ Finds and parses the value into a boolean value, for the configuration
+ variable `key` respecting keywords like "true" and "false". Integer
+ values are converted into true/false values (when they are non-zero or
+ zero, respectively). Other values cause a die(). If parsing is successful,
+ stores the value of the parsed result in `dest` and returns 0. When the
+ configuration variable `key` is not found, returns 1 without touching
+ `dest`.
+
+`int git_config_get_bool_or_int(const char *key, int *is_bool, int *dest)`::
+
+ Similar to `git_config_get_bool`, except that integers are copied as-is,
+ and `is_bool` flag is unset.
+
+`int git_config_get_maybe_bool(const char *key, int *dest)`::
+
+ Similar to `git_config_get_bool`, except that it returns -1 on error
+ rather than dying.
+
+`int git_config_get_string_const(const char *key, const char **dest)`::
+
+ Allocates and copies the retrieved string into the `dest` parameter for
+ the configuration variable `key`; if NULL string is given, prints an
+ error message and returns -1. When the configuration variable `key` is
+ not found, returns 1 without touching `dest`.
+
+`int git_config_get_string(const char *key, char **dest)`::
+
+ Similar to `git_config_get_string_const`, except that retrieved value
+ copied into the `dest` parameter is a mutable string.
+
+`int git_config_get_pathname(const char *key, const char **dest)`::
+
+ Similar to `git_config_get_string`, but expands `~` or `~user` into
+ the user's home directory when found at the beginning of the path.
+
+`git_die_config(const char *key, const char *err, ...)`::
+
+ First prints the error message specified by the caller in `err` and then
+ dies printing the line number and the file name of the highest priority
+ value for the configuration variable `key`.
+
+`void git_die_config_linenr(const char *key, const char *filename, int linenr)`::
+
+ Helper function which formats the die error message according to the
+ parameters entered. Used by `git_die_config()`. It can be used by callers
+ handling `git_config_get_value_multi()` to print the correct error message
+ for the desired value.
+
+See test-config.c for usage examples.
+
Value Parsing Helpers
---------------------
@@ -134,6 +227,68 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)
`git_config` respects includes automatically. The lower-level
`git_config_from_file` does not.
+Custom Configsets
+-----------------
+
+A `config_set` can be used to construct an in-memory cache for
+config-like files that the caller specifies (i.e., files like `.gitmodules`,
+`~/.gitconfig` etc.). For example,
+
+---------------------------------------
+struct config_set gm_config;
+git_configset_init(&gm_config);
+int b;
+/* we add config files to the config_set */
+git_configset_add_file(&gm_config, ".gitmodules");
+git_configset_add_file(&gm_config, ".gitmodules_alt");
+
+if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) {
+ /* hack hack hack */
+}
+
+/* when we are done with the configset */
+git_configset_clear(&gm_config);
+----------------------------------------
+
+Configset API provides functions for the above mentioned work flow, including:
+
+`void git_configset_init(struct config_set *cs)`::
+
+ Initializes the config_set `cs`.
+
+`int git_configset_add_file(struct config_set *cs, const char *filename)`::
+
+ Parses the file and adds the variable-value pairs to the `config_set`,
+ dies if there is an error in parsing the file. Returns 0 on success, or
+ -1 if the file does not exist or is inaccessible. The user has to decide
+ if he wants to free the incomplete configset or continue using it when
+ the function returns -1.
+
+`int git_configset_get_value(struct config_set *cs, const char *key, const char **value)`::
+
+ Finds the highest-priority value for the configuration variable `key`
+ and config set `cs`, stores the pointer to it in `value` and returns 0.
+ When the configuration variable `key` is not found, returns 1 without
+ touching `value`. The caller should not free or modify `value`, as it
+ is owned by the cache.
+
+`const struct string_list *git_configset_get_value_multi(struct config_set *cs, const char *key)`::
+
+ Finds and returns the value list, sorted in order of increasing priority
+ for the configuration variable `key` and config set `cs`. When the
+ configuration variable `key` is not found, returns NULL. The caller
+ should not free or modify the returned pointer, as it is owned by the cache.
+
+`void git_configset_clear(struct config_set *cs)`::
+
+ Clears `config_set` structure, removes all saved variable-value pairs.
+
+In addition to above functions, the `config_set` API provides type specific
+functions in the vein of `git_config_get_int` and family but with an extra
+parameter, pointer to struct `config_set`.
+They all behave similarly to the `git_config_get*()` family described in
+"Querying For Specific Variables" above.
+
Writing Config Files
--------------------
diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt
index dd89404..93b5f23 100644
--- a/Documentation/technical/api-lockfile.txt
+++ b/Documentation/technical/api-lockfile.txt
@@ -3,20 +3,132 @@ lockfile API
The lockfile API serves two purposes:
-* Mutual exclusion. When we write out a new index file, first
- we create a new file `$GIT_DIR/index.lock`, write the new
- contents into it, and rename it to the final destination
- `$GIT_DIR/index`. We try to create the `$GIT_DIR/index.lock`
- file with O_EXCL so that we can notice and fail when somebody
- else is already trying to update the index file.
-
-* Automatic cruft removal. After we create the "lock" file, we
- may decide to `die()`, and we would want to make sure that we
- remove the file that has not been committed to its final
- destination. This is done by remembering the lockfiles we
- created in a linked list and cleaning them up from an
- `atexit(3)` handler. Outstanding lockfiles are also removed
- when the program dies on a signal.
+* Mutual exclusion and atomic file updates. When we want to change a
+ file, we create a lockfile `<filename>.lock`, write the new file
+ contents into it, and then rename the lockfile to its final
+ destination `<filename>`. We create the `<filename>.lock` file with
+ `O_CREAT|O_EXCL` so that we can notice and fail if somebody else has
+ already locked the file, then atomically rename the lockfile to its
+ final destination to commit the changes and unlock the file.
+
+* Automatic cruft removal. If the program exits after we lock a file
+ but before the changes have been committed, we want to make sure
+ that we remove the lockfile. This is done by remembering the
+ lockfiles we have created in a linked list and setting up an
+ `atexit(3)` handler and a signal handler that clean up the
+ lockfiles. This mechanism ensures that outstanding lockfiles are
+ cleaned up if the program exits (including when `die()` is called)
+ or if the program dies on a signal.
+
+Please note that lockfiles only block other writers. Readers do not
+block, but they are guaranteed to see either the old contents of the
+file or the new contents of the file (assuming that the filesystem
+implements `rename(2)` atomically).
+
+
+Calling sequence
+----------------
+
+The caller:
+
+* Allocates a `struct lock_file` either as a static variable or on the
+ heap, initialized to zeros. Once you use the structure to call the
+ `hold_lock_file_*` family of functions, it belongs to the lockfile
+ subsystem and its storage must remain valid throughout the life of
+ the program (i.e. you cannot use an on-stack variable to hold this
+ structure).
+
+* Attempts to create a lockfile by passing that variable and the path
+ of the final destination (e.g. `$GIT_DIR/index`) to
+ `hold_lock_file_for_update` or `hold_lock_file_for_append`.
+
+* Writes new content for the destination file by either:
+
+ * writing to the file descriptor returned by the `hold_lock_file_*`
+ functions (also available via `lock->fd`).
+
+ * calling `fdopen_lock_file` to get a `FILE` pointer for the open
+ file and writing to the file using stdio.
+
+When finished writing, the caller can:
+
+* Close the file descriptor and rename the lockfile to its final
+ destination by calling `commit_lock_file` or `commit_lock_file_to`.
+
+* Close the file descriptor and remove the lockfile by calling
+ `rollback_lock_file`.
+
+* Close the file descriptor without removing or renaming the lockfile
+ by calling `close_lock_file`, and later call `commit_lock_file`,
+ `commit_lock_file_to`, `rollback_lock_file`, or `reopen_lock_file`.
+
+Even after the lockfile is committed or rolled back, the `lock_file`
+object must not be freed or altered by the caller. However, it may be
+reused; just pass it to another call of `hold_lock_file_for_update` or
+`hold_lock_file_for_append`.
+
+If the program exits before you have called one of `commit_lock_file`,
+`commit_lock_file_to`, `rollback_lock_file`, or `close_lock_file`, an
+`atexit(3)` handler will close and remove the lockfile, rolling back
+any uncommitted changes.
+
+If you need to close the file descriptor you obtained from a
+`hold_lock_file_*` function yourself, do so by calling
+`close_lock_file`. You should never call `close(2)` or `fclose(3)`
+yourself! Otherwise the `struct lock_file` structure would still think
+that the file descriptor needs to be closed, and a commit or rollback
+would result in duplicate calls to `close(2)`. Worse yet, if you close
+and then later open another file descriptor for a completely different
+purpose, then a commit or rollback might close that unrelated file
+descriptor.
+
+
+Error handling
+--------------
+
+The `hold_lock_file_*` functions return a file descriptor on success
+or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see below). On
+errors, `errno` describes the reason for failure. Errors can be
+reported by passing `errno` to one of the following helper functions:
+
+unable_to_lock_message::
+
+ Append an appropriate error message to a `strbuf`.
+
+unable_to_lock_error::
+
+ Emit an appropriate error message using `error()`.
+
+unable_to_lock_die::
+
+ Emit an appropriate error message and `die()`.
+
+Similarly, `commit_lock_file`, `commit_lock_file_to`, and
+`close_lock_file` return 0 on success. On failure they set `errno`
+appropriately, do their best to roll back the lockfile, and return -1.
+
+
+Flags
+-----
+
+The following flags can be passed to `hold_lock_file_for_update` or
+`hold_lock_file_for_append`:
+
+LOCK_NO_DEREF::
+
+ Usually symbolic links in the destination path are resolved
+ and the lockfile is created by adding ".lock" to the resolved
+ path. If `LOCK_NO_DEREF` is set, then the lockfile is created
+ by adding ".lock" to the path argument itself. This option is
+ used, for example, when locking a symbolic reference, which
+ for backwards-compatibility reasons can be a symbolic link
+ containing the name of the referred-to-reference.
+
+LOCK_DIE_ON_ERROR::
+
+ If a lock is already taken for the file, `die()` with an error
+ message. If this option is not specified, trying to lock a
+ file that is already locked returns -1 to the caller.
The functions
@@ -24,51 +136,85 @@ The functions
hold_lock_file_for_update::
- Take a pointer to `struct lock_file`, the filename of
- the final destination (e.g. `$GIT_DIR/index`) and a flag
- `die_on_error`. Attempt to create a lockfile for the
- destination and return the file descriptor for writing
- to the file. If `die_on_error` flag is true, it dies if
- a lock is already taken for the file; otherwise it
- returns a negative integer to the caller on failure.
+ Take a pointer to `struct lock_file`, the path of the file to
+ be locked (e.g. `$GIT_DIR/index`) and a flags argument (see
+ above). Attempt to create a lockfile for the destination and
+ return the file descriptor for writing to the file.
+
+hold_lock_file_for_append::
+
+ Like `hold_lock_file_for_update`, but before returning copy
+ the existing contents of the file (if any) to the lockfile and
+ position its write pointer at the end of the file.
+
+fdopen_lock_file::
+
+ Associate a stdio stream with the lockfile. Return NULL
+ (*without* rolling back the lockfile) on error. The stream is
+ closed automatically when `close_lock_file` is called or when
+ the file is committed or rolled back.
+
+get_locked_file_path::
+
+ Return the path of the file that is locked by the specified
+ lock_file object. The caller must free the memory.
commit_lock_file::
- Take a pointer to the `struct lock_file` initialized
- with an earlier call to `hold_lock_file_for_update()`,
- close the file descriptor and rename the lockfile to its
- final destination. Returns 0 upon success, a negative
- value on failure to close(2) or rename(2).
+ Take a pointer to the `struct lock_file` initialized with an
+ earlier call to `hold_lock_file_for_update` or
+ `hold_lock_file_for_append`, close the file descriptor, and
+ rename the lockfile to its final destination. Return 0 upon
+ success. On failure, roll back the lock file and return -1,
+ with `errno` set to the value from the failing call to
+ `close(2)` or `rename(2)`. It is a bug to call
+ `commit_lock_file` for a `lock_file` object that is not
+ currently locked.
+
+commit_lock_file_to::
+
+ Like `commit_lock_file()`, except that it takes an explicit
+ `path` argument to which the lockfile should be renamed. The
+ `path` must be on the same filesystem as the lock file.
rollback_lock_file::
- Take a pointer to the `struct lock_file` initialized
- with an earlier call to `hold_lock_file_for_update()`,
- close the file descriptor and remove the lockfile.
+ Take a pointer to the `struct lock_file` initialized with an
+ earlier call to `hold_lock_file_for_update` or
+ `hold_lock_file_for_append`, close the file descriptor and
+ remove the lockfile. It is a NOOP to call
+ `rollback_lock_file()` for a `lock_file` object that has
+ already been committed or rolled back.
close_lock_file::
- Take a pointer to the `struct lock_file` initialized
- with an earlier call to `hold_lock_file_for_update()`,
- and close the file descriptor. Returns 0 upon success,
- a negative value on failure to close(2).
-
-Because the structure is used in an `atexit(3)` handler, its
-storage has to stay throughout the life of the program. It
-cannot be an auto variable allocated on the stack.
-
-Call `commit_lock_file()` or `rollback_lock_file()` when you are
-done writing to the file descriptor. If you do not call either
-and simply `exit(3)` from the program, an `atexit(3)` handler
-will close and remove the lockfile.
-
-If you need to close the file descriptor you obtained from
-`hold_lock_file_for_update` function yourself, do so by calling
-`close_lock_file()`. You should never call `close(2)` yourself!
-Otherwise the `struct
-lock_file` structure still remembers that the file descriptor
-needs to be closed, and a later call to `commit_lock_file()` or
-`rollback_lock_file()` will result in duplicate calls to
-`close(2)`. Worse yet, if you `close(2)`, open another file
-descriptor for completely different purpose, and then call
-`commit_lock_file()` or `rollback_lock_file()`, they may close
-that unrelated file descriptor.
+
+ Take a pointer to the `struct lock_file` initialized with an
+ earlier call to `hold_lock_file_for_update` or
+ `hold_lock_file_for_append`. Close the file descriptor (and
+ the file pointer if it has been opened using
+ `fdopen_lock_file`). Return 0 upon success. On failure to
+ `close(2)`, return a negative value and roll back the lock
+ file. Usually `commit_lock_file`, `commit_lock_file_to`, or
+ `rollback_lock_file` should eventually be called if
+ `close_lock_file` succeeds.
+
+reopen_lock_file::
+
+ Re-open a lockfile that has been closed (using
+ `close_lock_file`) but not yet committed or rolled back. This
+ can be used to implement a sequence of operations like the
+ following:
+
+ * Lock file.
+
+ * Write new contents to lockfile, then `close_lock_file` to
+ cause the contents to be written to disk.
+
+ * Pass the name of the lockfile to another program to allow it
+ (and nobody else) to inspect the contents you wrote, while
+ still holding the lock yourself.
+
+ * `reopen_lock_file` to reopen the lockfile. Make further
+ updates to the contents.
+
+ * `commit_lock_file` to make the final version permanent.
diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt
index 866792f..a9fdb45 100644
--- a/Documentation/technical/api-run-command.txt
+++ b/Documentation/technical/api-run-command.txt
@@ -169,6 +169,11 @@ string pointers (NULL terminated) in .env:
. If the string does not contain '=', it names an environment
variable that will be removed from the child process's environment.
+If the .env member is NULL, `start_command` will point it at the
+.env_array `argv_array` (so you may use one or the other, but not both).
+The memory in .env_array will be cleaned up automatically during
+`finish_command` (or during `start_command` when it is unsuccessful).
+
To specify a new initial working directory for the sub-process,
specify it in the .dir member.
diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
index f9c06a7..cca6543 100644
--- a/Documentation/technical/api-strbuf.txt
+++ b/Documentation/technical/api-strbuf.txt
@@ -160,6 +160,10 @@ then they will free() it.
Add a single character to the buffer.
+`strbuf_addchars`::
+
+ Add a character the specified number of times to the buffer.
+
`strbuf_insert`::
Insert data to the given position of the buffer. The remaining contents
@@ -307,6 +311,16 @@ same behaviour as well.
use it unless you need the correct position in the file
descriptor.
+`strbuf_getcwd`::
+
+ Set the buffer to the path of the current working directory.
+
+`strbuf_add_absolute_path`
+
+ Add a path to a buffer, converting a relative path to an
+ absolute one in the process. Symbolic links are not
+ resolved.
+
`stripspace`::
Strip whitespace from a buffer. The second parameter controls if
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 18dea8d..462e206 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -212,9 +212,9 @@ out of what the server said it could do with the first 'want' line.
want-list = first-want
*additional-want
- shallow-line = PKT_LINE("shallow" SP obj-id)
+ shallow-line = PKT-LINE("shallow" SP obj-id)
- depth-request = PKT_LINE("deepen" SP depth)
+ depth-request = PKT-LINE("deepen" SP depth)
first-want = PKT-LINE("want" SP obj-id SP capability-list LF)
additional-want = PKT-LINE("want" SP obj-id LF)
@@ -465,9 +465,9 @@ contain all the objects that the server will need to complete the new
references.
----
- update-request = *shallow command-list [pack-file]
+ update-request = *shallow ( command-list | push-cert ) [pack-file]
- shallow = PKT-LINE("shallow" SP obj-id)
+ shallow = PKT-LINE("shallow" SP obj-id LF)
command-list = PKT-LINE(command NUL capability-list LF)
*PKT-LINE(command LF)
@@ -481,12 +481,27 @@ references.
old-id = obj-id
new-id = obj-id
+ push-cert = PKT-LINE("push-cert" NUL capability-list LF)
+ PKT-LINE("certificate version 0.1" LF)
+ PKT-LINE("pusher" SP ident LF)
+ PKT-LINE("pushee" SP url LF)
+ PKT-LINE("nonce" SP nonce LF)
+ PKT-LINE(LF)
+ *PKT-LINE(command LF)
+ *PKT-LINE(gpg-signature-lines LF)
+ PKT-LINE("push-cert-end" LF)
+
pack-file = "PACK" 28*(OCTET)
----
If the receiving end does not support delete-refs, the sending end MUST
NOT ask for delete command.
+If the receiving end does not support push-cert, the sending end
+MUST NOT send a push-cert command. When a push-cert command is
+sent, command-list MUST NOT be sent; the commands recorded in the
+push certificate is used instead.
+
The pack-file MUST NOT be sent if the only command used is 'delete'.
A pack-file MUST be sent if either create or update command is used,
@@ -501,6 +516,34 @@ was being processed (the obj-id is still the same as the old-id), and
it will run any update hooks to make sure that the update is acceptable.
If all of that is fine, the server will then update the references.
+Push Certificate
+----------------
+
+A push certificate begins with a set of header lines. After the
+header and an empty line, the protocol commands follow, one per
+line.
+
+Currently, the following header fields are defined:
+
+`pusher` ident::
+ Identify the GPG key in "Human Readable Name <email@address>"
+ format.
+
+`pushee` url::
+ The repository URL (anonymized, if the URL contains
+ authentication material) the user who ran `git push`
+ intended to push into.
+
+`nonce` nonce::
+ The 'nonce' string the receiving repository asked the
+ pushing user to include in the certificate, to prevent
+ replay attacks.
+
+The GPG signature lines are a detached signature for the contents
+recorded in the push certificate before the signature block begins.
+The detached signature is used to certify that the commands were
+given by the pusher, who must be the signer.
+
Report Status
-------------
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index e174343..0c92dee 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -18,8 +18,8 @@ was sent. Server MUST NOT ignore capabilities that client requested
and server advertised. As a consequence of these rules, server MUST
NOT advertise capabilities it does not understand.
-The 'report-status', 'delete-refs', and 'quiet' capabilities are sent and
-recognized by the receive-pack (push to server) process.
+The 'report-status', 'delete-refs', 'quiet', and 'push-cert' capabilities
+are sent and recognized by the receive-pack (push to server) process.
The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
by both upload-pack and receive-pack protocols. The 'agent' capability
@@ -250,3 +250,12 @@ allow-tip-sha1-in-want
If the upload-pack server advertises this capability, fetch-pack may
send "want" lines with SHA-1s that exist at the server but are not
advertised by upload-pack.
+
+push-cert=<nonce>
+-----------------
+
+The receive-pack server that advertises this capability is willing
+to accept a signed push certificate, and asks the <nonce> to be
+included in the push certificate. A send-pack client MUST NOT
+send a push-cert packet unless the receive-pack server advertises
+this capability.