Merge branch 'da/mergetool-docs'
authorJunio C Hamano <gitster@pobox.com>
Thu, 7 Feb 2013 22:42:08 +0000 (14:42 -0800)
committerJunio C Hamano <gitster@pobox.com>
Thu, 7 Feb 2013 22:42:16 +0000 (14:42 -0800)
Build on top of the clean-up done by jk/mergetool and automatically
generate the list of mergetool and difftool backends the build
supports to be included in the documentation.

* da/mergetool-docs:
doc: generate a list of valid merge tools
mergetool--lib: list user configured tools in '--tool-help'
mergetool--lib: add functions for finding available tools
mergetool--lib: improve the help text in guess_merge_tool()
mergetool--lib: simplify command expressions

1  2 
Documentation/Makefile
Documentation/diff-config.txt
Documentation/merge-config.txt
diff --combined Documentation/Makefile
index ae27aa5cdd439269924d693c4cf0cb5ea49e25d2,9209cf277df7c86dc0175e3f244328d7814c274e..62dbd9ac7c93e8df4359b00b7c3a59b614bd8d57
@@@ -1,41 -1,19 +1,41 @@@
 -MAN1_TXT= \
 -      $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
 -              $(wildcard git-*.txt)) \
 -      gitk.txt gitweb.txt git.txt
 -MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
 -      gitrepository-layout.txt gitweb.conf.txt
 -MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
 -      gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
 -      gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt
 +# Guard against environment variables
 +MAN1_TXT =
 +MAN5_TXT =
 +MAN7_TXT =
 +
 +MAN1_TXT += $(filter-out \
 +              $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
 +              $(wildcard git-*.txt))
 +MAN1_TXT += git.txt
 +MAN1_TXT += gitk.txt
 +MAN1_TXT += gitremote-helpers.txt
 +MAN1_TXT += gitweb.txt
 +
 +MAN5_TXT += gitattributes.txt
 +MAN5_TXT += githooks.txt
 +MAN5_TXT += gitignore.txt
 +MAN5_TXT += gitmodules.txt
 +MAN5_TXT += gitrepository-layout.txt
 +MAN5_TXT += gitweb.conf.txt
 +
 +MAN7_TXT += gitcli.txt
 +MAN7_TXT += gitcore-tutorial.txt
  MAN7_TXT += gitcredentials.txt
 +MAN7_TXT += gitcvs-migration.txt
 +MAN7_TXT += gitdiffcore.txt
 +MAN7_TXT += gitglossary.txt
 +MAN7_TXT += gitnamespaces.txt
 +MAN7_TXT += gitrevisions.txt
 +MAN7_TXT += gittutorial-2.txt
 +MAN7_TXT += gittutorial.txt
 +MAN7_TXT += gitworkflows.txt
  
  MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
  MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
  MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
  
 -DOC_HTML=$(MAN_HTML)
 +OBSOLETE_HTML = git-remote-helpers.html
 +DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML)
  
  ARTICLES = howto-index
  ARTICLES += everyday
@@@ -43,33 -21,11 +43,33 @@@ ARTICLES += git-tool
  ARTICLES += git-bisect-lk2009
  # with their own formatting rules.
  SP_ARTICLES = user-manual
 +SP_ARTICLES += howto/new-command
  SP_ARTICLES += howto/revert-branch-rebase
  SP_ARTICLES += howto/using-merge-subtree
  SP_ARTICLES += howto/using-signed-tag-in-pull-request
 +SP_ARTICLES += howto/use-git-daemon
 +SP_ARTICLES += howto/update-hook-example
 +SP_ARTICLES += howto/setup-git-server-over-http
 +SP_ARTICLES += howto/separating-topic-branches
 +SP_ARTICLES += howto/revert-a-faulty-merge
 +SP_ARTICLES += howto/recover-corrupted-blob-object
 +SP_ARTICLES += howto/rebuild-from-update-hook
 +SP_ARTICLES += howto/rebase-from-internal-branch
 +SP_ARTICLES += howto/maintain-git
  API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
  SP_ARTICLES += $(API_DOCS)
 +
 +TECH_DOCS = technical/index-format
 +TECH_DOCS += technical/pack-format
 +TECH_DOCS += technical/pack-heuristics
 +TECH_DOCS += technical/pack-protocol
 +TECH_DOCS += technical/protocol-capabilities
 +TECH_DOCS += technical/protocol-common
 +TECH_DOCS += technical/racy-git
 +TECH_DOCS += technical/send-pack-pipeline
 +TECH_DOCS += technical/shallow
 +TECH_DOCS += technical/trivial-merge
 +SP_ARTICLES += $(TECH_DOCS)
  SP_ARTICLES += technical/api-index
  
  DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
@@@ -200,6 -156,8 +200,6 @@@ all: html ma
  
  html: $(DOC_HTML)
  
 -$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7): asciidoc.conf
 -
  man: man1 man5 man7
  man1: $(DOC_MAN1)
  man5: $(DOC_MAN5)
@@@ -244,7 -202,11 +244,11 @@@ install-html: htm
  #
  # Determine "include::" file references in asciidoc files.
  #
- doc.dep : $(wildcard *.txt) build-docdep.perl
+ docdep_prereqs = \
+       mergetools-list.made $(mergetools_txt) \
+       cmd-list.made $(cmds_txt)
+ doc.dep : $(docdep_prereqs) $(wildcard *.txt) build-docdep.perl
        $(QUIET_GEN)$(RM) $@+ $@ && \
        $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \
        mv $@+ $@
@@@ -268,27 -230,35 +272,41 @@@ cmd-list.made: cmd-list.perl ../command
        $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \
        date >$@
  
+ mergetools_txt = mergetools-diff.txt mergetools-merge.txt
+ $(mergetools_txt): mergetools-list.made
+ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
+       $(QUIET_GEN)$(RM) $@ && \
+       $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \
+               . ../git-mergetool--lib.sh && \
+               show_tool_names can_diff "* " || :' >mergetools-diff.txt && \
+       $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \
+               . ../git-mergetool--lib.sh && \
+               show_tool_names can_merge "* " || :' >mergetools-merge.txt && \
+       date >$@
  clean:
        $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
        $(RM) *.texi *.texi+ *.texi++ git.info gitman.info
        $(RM) *.pdf
        $(RM) howto-index.txt howto/*.html doc.dep
 -      $(RM) technical/api-*.html technical/api-index.txt
 +      $(RM) technical/*.html technical/api-index.txt
-       $(RM) $(cmds_txt) *.made
+       $(RM) $(cmds_txt) $(mergetools_txt) *.made
        $(RM) manpage-base-url.xsl
  
 -$(MAN_HTML): %.html : %.txt
 +$(MAN_HTML): %.html : %.txt asciidoc.conf
        $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
        $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
                $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
        mv $@+ $@
  
 +$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf
 +      $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 +      $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
 +              $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
 +      mv $@+ $@
 +
  manpage-base-url.xsl: manpage-base-url.xsl.in
        sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
  
        $(QUIET_XMLTO)$(RM) $@ && \
        $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
  
 -%.xml : %.txt
 +%.xml : %.txt asciidoc.conf
        $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
        $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
                $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
@@@ -312,7 -282,7 +330,7 @@@ technical/api-index.txt: technical/api-
        $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
  
  technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
 -$(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
 +$(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
  
@@@ -357,7 -327,7 +375,7 @@@ $(patsubst %.txt,%.texi,$(MAN_TXT)): %.
  
  howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
        $(QUIET_GEN)$(RM) $@+ $@ && \
 -      '$(SHELL_PATH_SQ)' ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \
 +      '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \
        mv $@+ $@
  
  $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
@@@ -374,8 -344,8 +392,8 @@@ $(patsubst %.txt,%.html,$(wildcard howt
  install-webdoc : html
        '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST)
  
 -# You must have a clone of git-htmldocs and git-manpages repositories
 -# next to the git repository itself for the following to work.
 +# You must have a clone of 'git-htmldocs' and 'git-manpages' repositories
 +# next to the 'git' repository itself for the following to work.
  
  quick-install: quick-install-man
  
index 6d06aa4357f62ca1fb68b0dad5ffc3157e61c00a,7c968d1bab9cd6194aa1a80f1ee20a8f52ec840b..7c70c2a2feca88a2c1247794e2ee0fbed767bb4a
@@@ -56,10 -56,6 +56,10 @@@ diff.statGraphWidth:
        Limit the width of the graph part in --stat output. If set, applies
        to all commands generating --stat output except format-patch.
  
 +diff.context::
 +      Generate diffs with <n> lines of context instead of the default
 +      of 3. This value is overridden by the -U option.
 +
  diff.external::
        If this config variable is set, diff generation is not
        performed using the internal diff machinery, but using the
@@@ -99,7 -95,7 +99,7 @@@ diff.renameLimit:
        detection; equivalent to the 'git diff' option '-l'.
  
  diff.renames::
 -      Tells git to detect renames.  If set to any boolean value, it
 +      Tells Git to detect renames.  If set to any boolean value, it
        will enable basic rename detection.  If set to "copies" or
        "copy", it will detect copies, as well.
  
@@@ -107,19 -103,6 +107,19 @@@ diff.suppressBlankEmpty:
        A boolean to inhibit the standard behavior of printing a space
        before each empty output line. Defaults to false.
  
 +diff.submodule::
 +      Specify the format in which differences in submodules are
 +      shown.  The "log" format lists the commits in the range like
 +      linkgit:git-submodule[1] `summary` does.  The "short" format
 +      format just shows the names of the commits at the beginning
 +      and end of the range.  Defaults to short.
 +
 +diff.wordRegex::
 +      A POSIX Extended Regular Expression used to determine what is a "word"
 +      when performing word-by-word difference calculations.  Character
 +      sequences that match the regular expression are "words", all other
 +      characters are *ignorable* whitespace.
 +
  diff.<driver>.command::
        The custom diff driver command.  See linkgit:gitattributes[5]
        for details.
@@@ -149,9 -132,10 +149,10 @@@ diff.<driver>.cachetextconv:
        conversion outputs.  See linkgit:gitattributes[5] for details.
  
  diff.tool::
-       The diff tool to be used by linkgit:git-difftool[1].  This
-       option overrides `merge.tool`, and has the same valid built-in
-       values as `merge.tool` minus "tortoisemerge" and plus
-       "kompare".  Any other value is treated as a custom diff tool,
-       and there must be a corresponding `difftool.<tool>.cmd`
-       option.
+       Controls which diff tool is used by linkgit:git-difftool[1].
+       This variable overrides the value configured in `merge.tool`.
+       The list below shows the valid built-in values.
+       Any other value is treated as a custom diff tool and requires
+       that a corresponding difftool.<tool>.cmd variable is defined.
+ include::mergetools-diff.txt[]
index 897329bbd9f01fa0dcc308a3e3e17a576006cace,5f40e719bbba9037627450c5b9bb6797b4bc2f4c..d78d6d854e5fa0a2d4f030d821984f3e6827b9c1
@@@ -9,18 -9,18 +9,18 @@@ merge.conflictstyle:
  merge.defaultToUpstream::
        If merge is called without any commit argument, merge the upstream
        branches configured for the current branch by using their last
 -      observed values stored in their remote tracking branches.
 +      observed values stored in their remote-tracking branches.
        The values of the `branch.<current branch>.merge` that name the
        branches at the remote named by `branch.<current branch>.remote`
        are consulted, and then they are mapped via `remote.<remote>.fetch`
 -      to their corresponding remote tracking branches, and the tips of
 +      to their corresponding remote-tracking branches, and the tips of
        these tracking branches are merged.
  
  merge.ff::
 -      By default, git does not create an extra merge commit when merging
 +      By default, Git does not create an extra merge commit when merging
        a commit that is a descendant of the current commit. Instead, the
        tip of the current branch is fast-forwarded. When set to `false`,
 -      this variable tells git to create an extra merge commit in such
 +      this variable tells Git to create an extra merge commit in such
        a case (equivalent to giving the `--no-ff` option from the command
        line). When set to `only`, only such fast-forward merges are
        allowed (equivalent to giving the `--ff-only` option from the
@@@ -38,10 -38,10 +38,10 @@@ merge.renameLimit:
        diff.renameLimit.
  
  merge.renormalize::
 -      Tell git that canonical representation of files in the
 +      Tell Git that canonical representation of files in the
        repository has changed over time (e.g. earlier commits record
        text files with CRLF line endings, but recent ones use LF line
 -      endings).  In such a repository, git can convert the data
 +      endings).  In such a repository, Git can convert the data
        recorded in commits to a canonical form before performing a
        merge to reduce unnecessary conflicts.  For more information,
        see section "Merging branches with differing checkin/checkout
@@@ -52,12 -52,12 +52,12 @@@ merge.stat:
        at the end of the merge.  True by default.
  
  merge.tool::
-       Controls which merge resolution program is used by
-       linkgit:git-mergetool[1].  Valid built-in values are: "araxis",
-       "bc3", "diffuse", "ecmerge", "emerge", "gvimdiff", "kdiff3", "meld",
-       "opendiff", "p4merge", "tkdiff", "tortoisemerge", "vimdiff"
-       and "xxdiff".  Any other value is treated is custom merge tool
-       and there must be a corresponding mergetool.<tool>.cmd option.
+       Controls which merge tool is used by linkgit:git-mergetool[1].
+       The list below shows the valid built-in values.
+       Any other value is treated as a custom merge tool and requires
+       that a corresponding mergetool.<tool>.cmd variable is defined.
+ include::mergetools-merge.txt[]
  
  merge.verbosity::
        Controls the amount of output shown by the recursive merge