diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 649df89474d357..9f4bb3c4bf9e9e 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -12,6 +12,7 @@ cmds-*.txt
mergetools-*.txt
SubmittingPatches.txt
tmp-doc-diff/
+tmp-meson-diff/
GIT-ASCIIDOCFLAGS
/.build/
/GIT-EXCLUDED-PROGRAMS
diff --git a/Documentation/Makefile b/Documentation/Makefile
index a89823e1d1ee50..aedfe99d1d3588 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -339,6 +339,7 @@ clean:
$(RM) $(cmds_txt) $(mergetools_txt) *.made
$(RM) GIT-ASCIIDOCFLAGS
$(RM) asciidoc.conf asciidoctor-extensions.rb
+ $(RM) -rf tmp-meson-diff
docinfo.html: docinfo-html.in
$(QUIET_GEN)$(RM) $@ && cat $< >$@
@@ -362,12 +363,12 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
%.xml : %.txt $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
-user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC_DEPS)
+user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<
technical/api-index.txt: technical/api-index-skel.txt \
technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
- $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
+ $(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
@@ -411,8 +412,8 @@ gitman.info: gitman.texi
$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@
-howto-index.txt: howto-index.sh $(HOWTO_TXT)
- $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@
+howto-index.txt: howto/howto-index.sh $(HOWTO_TXT)
+ $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@
$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
@@ -494,6 +495,20 @@ lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
lint-docs-manpages:
$(QUIET_GEN)./lint-manpages.sh
+.PHONY: lint-docs-meson
+lint-docs-meson:
+ @# awk acts up when trying to match single quotes, so we use \047 instead.
+ @mkdir -p tmp-meson-diff && \
+ awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \
+ grep -v -e '#' -e '^$$' | \
+ sort >tmp-meson-diff/meson.txt && \
+ ls git*.txt scalar.txt | grep -v -e git-bisect-lk2009.txt -e git-tools.txt >tmp-meson-diff/actual.txt && \
+ if ! cmp tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; then \
+ echo "Meson man pages differ from actual man pages:"; \
+ diff -u tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; \
+ exit 1; \
+ fi
+
## Lint: list of targets above
.PHONY: lint-docs
lint-docs: lint-docs-fsck-msgids
@@ -501,6 +516,7 @@ lint-docs: lint-docs-gitlink
lint-docs: lint-docs-man-end-blurb
lint-docs: lint-docs-man-section-order
lint-docs: lint-docs-manpages
+lint-docs: lint-docs-meson
ifeq ($(wildcard po/Makefile),po/Makefile)
doc-l10n install-l10n::
diff --git a/Documentation/RelNotes/2.48.0.txt b/Documentation/RelNotes/2.48.0.txt
index f9fc8c10860ba4..d62c62dc17ad0b 100644
--- a/Documentation/RelNotes/2.48.0.txt
+++ b/Documentation/RelNotes/2.48.0.txt
@@ -165,6 +165,10 @@ Performance, Internal Implementation, Development Support etc.
info on gitk and git-gui maintainer.
+ * CI jobs that run threaded programs under LSan has been giving false
+ positives from time to time, which has been worked around.
+
+
Fixes since v2.47
-----------------
@@ -310,6 +314,12 @@ Fixes since v2.47
to avoid race condition even when multiple packs are involved.
(merge 62b3ec8a3f tb/bitmap-fix-pack-reuse later to maint).
+ * An earlier "csum-file checksum does not have to be computed with
+ sha1dc" topic had a few code paths that had initialized an
+ implementation of a hash function to be used by an unmatching hash
+ by mistake, which have been corrected.
+ (merge 599a63409b ps/weak-sha1-for-tail-sum-fix later to maint).
+
* Other code cleanup, docfix, build fix, etc.
(merge 77af53f56f aa/t7300-modernize later to maint).
(merge dcd590a39d bf/t-readme-mention-reftable later to maint).
diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in
index b89bccf2309d78..f2aef6cb79f47c 100644
--- a/Documentation/asciidoc.conf.in
+++ b/Documentation/asciidoc.conf.in
@@ -25,12 +25,22 @@ manmanual=Git Manual
mansource=Git @GIT_VERSION@
revdate=@GIT_DATE@
+ifdef::doctype-book[]
+[titles]
+ underlines="__","==","--","~~","^^"
+endif::doctype-book[]
+
ifdef::backend-docbook[]
[linkgit-inlinemacro]
+ifndef::doctype-book[]
{0%{target}}
{0#}
{0#{target}{0}}
{0#}
+endif::doctype-book[]
+ifdef::doctype-book[]
+{target}{0?({0})}
+endif::doctype-book[]
[literal-inlinemacro]
{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 81498393af540b..e89a91dd0d034c 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -478,7 +478,7 @@ their values the same way as Boolean valued configuration variables, e.g.
Here are the variables:
System
-~~~~~~~~~~~~~~~~~~
+~~~~~~
`HOME`::
Specifies the path to the user's home directory. On Windows, if
unset, Git will set a process environment variable equal to:
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index bd62cbd0439508..fcd86d2eee0038 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -91,7 +91,7 @@ scripting Git:
written in the 'stuck' form.
* Despite the above suggestion, when Arg is a path relative to the
- home directory of a user, e.g. ~/directory/file or ~u/d/f, you
+ home directory of a user, e.g. `~/directory/file` or `~u/d/f`, you
may want to use the separate form, e.g. `git foo --file ~/mine`,
not `git foo --file=~/mine`. The shell will expand `~/` in the
former to your home directory, but most shells keep the tilde in
diff --git a/Documentation/howto-index.sh b/Documentation/howto/howto-index.sh
similarity index 92%
rename from Documentation/howto-index.sh
rename to Documentation/howto/howto-index.sh
index 167b363668b8b5..eecd123a936079 100755
--- a/Documentation/howto-index.sh
+++ b/Documentation/howto/howto-index.sh
@@ -48,7 +48,7 @@ do
file="$txt"
fi
- echo "* link:$file[$title] $from
+ echo "* link:howto/$(basename "$file")[$title] $from
$abstract
"
diff --git a/Documentation/howto/meson.build b/Documentation/howto/meson.build
new file mode 100644
index 00000000000000..c023c104161e61
--- /dev/null
+++ b/Documentation/howto/meson.build
@@ -0,0 +1,62 @@
+howto_sources = [
+ 'coordinate-embargoed-releases.txt',
+ 'keep-canonical-history-correct.txt',
+ 'maintain-git.txt',
+ 'new-command.txt',
+ 'rebase-from-internal-branch.txt',
+ 'rebuild-from-update-hook.txt',
+ 'recover-corrupted-blob-object.txt',
+ 'recover-corrupted-object-harder.txt',
+ 'revert-a-faulty-merge.txt',
+ 'revert-branch-rebase.txt',
+ 'separating-topic-branches.txt',
+ 'setup-git-server-over-http.txt',
+ 'update-hook-example.txt',
+ 'use-git-daemon.txt',
+ 'using-merge-subtree.txt',
+ 'using-signed-tag-in-pull-request.txt',
+]
+
+howto_index = custom_target(
+ command: [
+ shell,
+ meson.current_source_dir() / 'howto-index.sh',
+ '@INPUT@',
+ ],
+ env: script_environment,
+ capture: true,
+ input: howto_sources,
+ output: 'howto-index.txt',
+)
+
+custom_target(
+ command: asciidoc_html_options,
+ input: howto_index,
+ output: 'howto-index.html',
+ depends: documentation_deps,
+ install: true,
+ install_dir: get_option('datadir') / 'doc/git-doc',
+)
+
+foreach howto : howto_sources
+ howto_stripped = custom_target(
+ command: [
+ find_program('sed'),
+ '-e',
+ '1,/^$/d',
+ '@INPUT@',
+ ],
+ input: howto,
+ output: fs.stem(howto) + '.stripped',
+ capture: true,
+ )
+
+ custom_target(
+ command: asciidoc_html_options,
+ input: howto_stripped,
+ output: fs.stem(howto_stripped.full_path()) + '.html',
+ depends: documentation_deps,
+ install: true,
+ install_dir: get_option('datadir') / 'doc/git-doc/howto',
+ )
+endforeach
diff --git a/Documentation/meson.build b/Documentation/meson.build
index fca3eab1f1360a..292834d069e2c6 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -6,6 +6,7 @@ manpages = {
'git-apply.txt' : 1,
'git-archimport.txt' : 1,
'git-archive.txt' : 1,
+ 'git-backfill.txt' : 1,
'git-bisect.txt' : 1,
'git-blame.txt' : 1,
'git-branch.txt' : 1,
@@ -140,6 +141,7 @@ manpages = {
'git-status.txt' : 1,
'git-stripspace.txt' : 1,
'git-submodule.txt' : 1,
+ 'git-survey.txt' : 1,
'git-svn.txt' : 1,
'git-switch.txt' : 1,
'git-symbolic-ref.txt' : 1,
@@ -204,29 +206,87 @@ manpages = {
'gitworkflows.txt' : 7,
}
-asciidoc = find_program('asciidoc')
-git = find_program('git', required: false)
-xmlto = find_program('xmlto')
+docs_backend = get_option('docs_backend')
+if docs_backend == 'auto'
+ if find_program('asciidoc', required: false).found()
+ docs_backend = 'asciidoc'
+ elif find_program('asciidoctor', required: false).found()
+ docs_backend = 'asciidoctor'
+ else
+ error('Neither asciidoc nor asciidoctor were found.')
+ endif
+endif
-asciidoc_conf = custom_target(
- command: [
- shell,
- meson.project_source_root() / 'GIT-VERSION-GEN',
- meson.project_source_root(),
- '@INPUT@',
- '@OUTPUT@',
- ],
- input: meson.current_source_dir() / 'asciidoc.conf.in',
- output: 'asciidoc.conf',
- depends: [git_version_file],
- env: version_gen_environment,
-)
+if docs_backend == 'asciidoc'
+ asciidoc = find_program('asciidoc', required: true)
+ asciidoc_html = 'xhtml11'
+ asciidoc_docbook = 'docbook'
+ xmlto_extra = [ ]
-asciidoc_common_options = [
- asciidoc,
- '--conf-file=' + asciidoc_conf.full_path(),
- '--attribute=build_dir=' + meson.current_build_dir(),
-]
+ asciidoc_conf = custom_target(
+ command: [
+ shell,
+ meson.project_source_root() / 'GIT-VERSION-GEN',
+ meson.project_source_root(),
+ '@INPUT@',
+ '@OUTPUT@',
+ ],
+ input: 'asciidoc.conf.in',
+ output: 'asciidoc.conf',
+ depends: [git_version_file],
+ env: version_gen_environment,
+ )
+
+ asciidoc_common_options = [
+ asciidoc,
+ '--conf-file=' + asciidoc_conf.full_path(),
+ '--attribute=build_dir=' + meson.current_build_dir(),
+ ]
+
+ documentation_deps = [
+ asciidoc_conf,
+ ]
+elif docs_backend == 'asciidoctor'
+ asciidoctor = find_program('asciidoctor', required: true)
+ asciidoc_html = 'xhtml5'
+ asciidoc_docbook = 'docbook5'
+ xmlto_extra = [
+ '--skip-validation',
+ '-x', meson.current_source_dir() / 'manpage.xsl',
+ ]
+
+ asciidoctor_extensions = custom_target(
+ command: [
+ shell,
+ meson.project_source_root() / 'GIT-VERSION-GEN',
+ meson.project_source_root(),
+ '@INPUT@',
+ '@OUTPUT@',
+ ],
+ input: 'asciidoctor-extensions.rb.in',
+ output: 'asciidoctor-extensions.rb',
+ depends: [git_version_file],
+ env: version_gen_environment,
+ )
+
+ asciidoc_common_options = [
+ asciidoctor,
+ '--attribute', 'compat-mode',
+ '--attribute', 'tabsize=8',
+ '--attribute', 'litdd=--',
+ '--attribute', 'docinfo=shared',
+ '--attribute', 'build_dir=' + meson.current_build_dir(),
+ '--load-path', meson.current_build_dir(),
+ '--require', 'asciidoctor-extensions',
+ ]
+
+ documentation_deps = [
+ asciidoctor_extensions,
+ ]
+endif
+
+git = find_program('git', required: false)
+xmlto = find_program('xmlto')
cmd_lists = [
'cmds-ancillaryinterrogators.txt',
@@ -243,17 +303,14 @@ cmd_lists = [
'cmds-foreignscminterface.txt',
]
-documentation_deps = [
- asciidoc_conf,
-]
-
documentation_deps += custom_target(
command: [
perl,
- meson.current_source_dir() / 'cmd-list.perl',
+ '@INPUT@',
meson.project_source_root(),
meson.current_build_dir(),
] + cmd_lists,
+ input: 'cmd-list.perl',
output: cmd_lists
)
@@ -261,15 +318,15 @@ foreach mode : [ 'diff', 'merge' ]
documentation_deps += custom_target(
command: [
shell,
- meson.current_source_dir() / 'generate-mergetool-list.sh',
+ '@INPUT@',
'..',
- 'diff',
+ mode,
'@OUTPUT@'
],
env: [
'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools',
- 'TOOL_MODE=' + mode,
],
+ input: 'generate-mergetool-list.sh',
output: 'mergetools-' + mode + '.txt',
)
endforeach
@@ -278,12 +335,13 @@ foreach manpage, category : manpages
if get_option('docs').contains('man')
manpage_xml_target = custom_target(
command: asciidoc_common_options + [
- '--backend=docbook',
+ '--backend=' + asciidoc_docbook,
'--doctype=manpage',
'--out-file=@OUTPUT@',
- meson.current_source_dir() / manpage,
+ '@INPUT@',
],
depends: documentation_deps,
+ input: manpage,
output: fs.stem(manpage) + '.xml',
)
@@ -291,16 +349,18 @@ foreach manpage, category : manpages
manpage_target = custom_target(
command: [
xmlto,
- '-m',
- meson.current_source_dir() / 'manpage-normal.xsl',
- '-m',
- meson.current_source_dir() / 'manpage-bold-literal.xsl',
+ '-m', '@INPUT0@',
+ '-m', '@INPUT1@',
'--stringparam',
'man.base.url.for.relative.links=' + get_option('prefix') / get_option('mandir'),
'man',
manpage_xml_target,
'-o',
meson.current_build_dir(),
+ ] + xmlto_extra,
+ input: [
+ 'manpage-normal.xsl',
+ 'manpage-bold-literal.xsl',
],
output: manpage_path,
install: true,
@@ -308,18 +368,139 @@ foreach manpage, category : manpages
)
endif
- if get_option('docs').contains('html') and category == 1
+ if get_option('docs').contains('html')
custom_target(
command: asciidoc_common_options + [
- '--backend=xhtml11',
+ '--backend=' + asciidoc_html,
'--doctype=manpage',
'--out-file=@OUTPUT@',
- meson.current_source_dir() / manpage,
+ '@INPUT@',
],
depends: documentation_deps,
+ input: manpage,
output: fs.stem(manpage) + '.html',
install: true,
install_dir: get_option('datadir') / 'doc/git-doc',
)
endif
endforeach
+
+if get_option('docs').contains('html')
+ configure_file(
+ input: 'docinfo-html.in',
+ output: 'docinfo.html',
+ copy: true,
+ install: true,
+ install_dir: get_option('datadir') / 'doc/git-doc',
+ )
+
+ configure_file(
+ input: 'docbook-xsl.css',
+ output: 'docbook-xsl.css',
+ copy: true,
+ install: true,
+ install_dir: get_option('datadir') / 'doc/git-doc',
+ )
+
+ install_symlink('index.html',
+ install_dir: get_option('datadir') / 'doc/git-doc',
+ pointing_to: 'git.html',
+ )
+
+ xsltproc = find_program('xsltproc')
+
+ user_manual_xml = custom_target(
+ command: asciidoc_common_options + [
+ '--backend=' + asciidoc_docbook,
+ '--doctype=book',
+ '--out-file=@OUTPUT@',
+ '@INPUT@',
+ ],
+ input: 'user-manual.txt',
+ output: 'user-manual.xml',
+ depends: documentation_deps,
+ )
+
+ custom_target(
+ command: [
+ xsltproc,
+ '--xinclude',
+ '--stringparam', 'html.stylesheet', 'docbook-xsl.css',
+ '--param', 'generate.consistent.ids', '1',
+ '--output', '@OUTPUT@',
+ '@INPUT@',
+ user_manual_xml,
+ ],
+ input: 'docbook.xsl',
+ output: 'user-manual.html',
+ install: true,
+ install_dir: get_option('datadir') / 'doc/git-doc',
+ )
+
+ articles = [
+ 'DecisionMaking.txt',
+ 'MyFirstContribution.txt',
+ 'MyFirstObjectWalk.txt',
+ 'ReviewingGuidelines.txt',
+ 'SubmittingPatches',
+ 'ToolsForGit.txt',
+ 'git-bisect-lk2009.txt',
+ 'git-tools.txt',
+ ]
+
+ foreach article : articles
+ custom_target(
+ command: asciidoc_common_options + [
+ '--backend=' + asciidoc_html,
+ '--out-file=@OUTPUT@',
+ '@INPUT@',
+ ],
+ input: article,
+ output: fs.stem(article) + '.html',
+ depends: documentation_deps,
+ install: true,
+ install_dir: get_option('datadir') / 'doc/git-doc',
+ )
+ endforeach
+
+ asciidoc_html_options = asciidoc_common_options + [
+ '--backend=' + asciidoc_html,
+ '--out-file=@OUTPUT@',
+ '--attribute', 'git-relative-html-prefix=../',
+ '@INPUT@',
+ ]
+
+ subdir('howto')
+ subdir('technical')
+endif
+
+# Sanity check that we are not missing any tests present in 't/'. This check
+# only runs once at configure time and is thus best-effort, only. Furthermore,
+# it only verifies man pages for the sake of simplicity.
+configured_manpages = manpages.keys() + [ 'git-bisect-lk2009.txt', 'git-tools.txt' ]
+actual_manpages = run_command(shell, '-c', 'ls git*.txt scalar.txt',
+ check: true,
+ env: script_environment,
+).stdout().strip().split('\n')
+
+if configured_manpages != actual_manpages
+ missing_manpage = [ ]
+ foreach actual_manpage : actual_manpages
+ if actual_manpage not in configured_manpages
+ missing_manpage += actual_manpage
+ endif
+ endforeach
+ if missing_manpage.length() > 0
+ error('Man page found, but not configured:\n\n - ' + '\n - '.join(missing_manpage))
+ endif
+
+ superfluous_manpage = [ ]
+ foreach configured_manpage : configured_manpages
+ if configured_manpage not in actual_manpages
+ superfluous_manpage += configured_manpage
+ endif
+ endforeach
+ if superfluous_manpage.length() > 0
+ error('Man page configured, but not found:\n\n - ' + '\n - '.join(superfluous_manpage))
+ endif
+endif
diff --git a/Documentation/technical/api-index.sh b/Documentation/technical/api-index.sh
index 9c3f4131b85864..296488557434b7 100755
--- a/Documentation/technical/api-index.sh
+++ b/Documentation/technical/api-index.sh
@@ -1,6 +1,17 @@
#!/bin/sh
+if test $# -ne 2
+then
+ echo >&2 "USAGE: $0