diff options
Diffstat (limited to 'Documentation')
32 files changed, 1230 insertions, 108 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index a48448de32..9f4bb3c4bf 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -12,6 +12,9 @@ cmds-*.txt mergetools-*.txt SubmittingPatches.txt tmp-doc-diff/ +tmp-meson-diff/ GIT-ASCIIDOCFLAGS /.build/ /GIT-EXCLUDED-PROGRAMS +/asciidoc.conf +/asciidoctor-extensions.rb diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 87904791cb..ba047ed224 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -583,7 +583,7 @@ For C programs: Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or run `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git foo` to use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" - ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + ./bin-wrappers/git log` (See `bin-wrappers/wrap-for-bin.sh`.) - The primary data structure that a subsystem 'S' deals with is called `struct S`. Functions that operate on `struct S` are named @@ -703,16 +703,30 @@ Program Output Error Messages - - Do not end error messages with a full stop. + - Do not end a single-sentence error message with a full stop. - Do not capitalize the first word, only because it is the first word - in the message ("unable to open %s", not "Unable to open %s"). But + in the message ("unable to open '%s'", not "Unable to open '%s'"). But "SHA-3 not supported" is fine, because the reason the first word is capitalized is not because it is at the beginning of the sentence, but because the word would be spelled in capital letters even when it appeared in the middle of the sentence. - - Say what the error is first ("cannot open %s", not "%s: cannot open") + - Say what the error is first ("cannot open '%s'", not "%s: cannot open"). + + - Enclose the subject of an error inside a pair of single quotes, + e.g. `die(_("unable to open '%s'"), path)`. + + - Unless there is a compelling reason not to, error messages from + porcelain commands should be marked for translation, e.g. + `die(_("bad revision %s"), revision)`. + + - Error messages from the plumbing commands are sometimes meant for + machine consumption and should not be marked for translation, + e.g., `die("bad revision %s", revision)`. + + - BUG("message") are for communicating the specific error to developers, + thus should not be translated. Externally Visible Names diff --git a/Documentation/Makefile b/Documentation/Makefile index 0f55baa252..aedfe99d1d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,6 +1,8 @@ # Import tree-wide shared Makefile behavior and libraries include ../shared.mak +.PHONY: FORCE + # Guard against environment variables MAN1_TXT = MAN5_TXT = @@ -111,6 +113,7 @@ TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format +TECH_DOCS += technical/build-systems TECH_DOCS += technical/bundle-uri TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/long-running-process-protocol @@ -148,16 +151,12 @@ man5dir = $(mandir)/man5 man7dir = $(mandir)/man7 # DESTDIR = -GIT_DATE := $(shell git show --quiet --pretty='%as') - ASCIIDOC = asciidoc ASCIIDOC_EXTRA = ASCIIDOC_HTML = xhtml11 ASCIIDOC_DOCBOOK = docbook ASCIIDOC_CONF = -f asciidoc.conf -ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ - -amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' \ - -arevdate='$(GIT_DATE)' +ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) @@ -182,6 +181,10 @@ endif -include ../config.mak.autogen -include ../config.mak +# Set GIT_VERSION_OVERRIDE such that version_gen knows to substitute +# GIT_VERSION in case it was set by the user. +GIT_VERSION_OVERRIDE := $(GIT_VERSION) + ifndef NO_MAN_BOLD_LITERAL XMLTO_EXTRA += -m manpage-bold-literal.xsl endif @@ -210,6 +213,12 @@ ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation XMLTO_EXTRA += -x manpage.xsl + +asciidoctor-extensions.rb: asciidoctor-extensions.rb.in FORCE + $(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@) +else +asciidoc.conf: asciidoc.conf.in FORCE + $(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@) endif ASCIIDOC_DEPS += docinfo.html @@ -218,6 +227,7 @@ SHELL_PATH ?= $(SHELL) # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) +ASCIIDOC_EXTRA += -abuild_dir='$(shell pwd)' ifdef DEFAULT_PAGER DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER)) ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)' @@ -268,22 +278,17 @@ install-pdf: pdf install-html: html '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir) -../GIT-VERSION-FILE: FORCE - $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE - -ifneq ($(filter-out lint-docs clean,$(MAKECMDGOALS)),) --include ../GIT-VERSION-FILE -endif +mergetools_txt = mergetools-diff.txt mergetools-merge.txt # # Determine "include::" file references in asciidoc files. # docdep_prereqs = \ - mergetools-list.made $(mergetools_txt) \ + $(mergetools_txt) \ cmd-list.made $(cmds_txt) doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl - $(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR) + $(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl "$(shell pwd)" >$@ $(QUIET_STDERR) ifneq ($(MAKECMDGOALS),clean) -include doc.dep @@ -305,22 +310,14 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) - $(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \ + $(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl .. . $(cmds_txt) && \ 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) \ - $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=diff && \ - . ../git-mergetool--lib.sh && \ - show_tool_names can_diff' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-diff.txt && \ - $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=merge && \ - . ../git-mergetool--lib.sh && \ - show_tool_names can_merge' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-merge.txt && \ - date >$@ +mergetools-%.txt: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*) +mergetools-diff.txt: + $(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. diff $@ +mergetools-merge.txt: + $(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. merge $@ TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) @@ -341,6 +338,8 @@ clean: $(RM) SubmittingPatches.txt $(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 $< >$@ @@ -364,16 +363,16 @@ 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 asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS +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 \ - asciidoc.conf GIT-ASCIIDOCFLAGS + $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt SubmittingPatches.txt: SubmittingPatches @@ -413,16 +412,16 @@ 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 +$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS) $(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,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS +$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC) \ sed -e '1,/^$$/d' $< | \ $(TXT_TO_HTML) - >$@ @@ -496,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 @@ -503,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 b9d1b129cd..eff93be37a 100644 --- a/Documentation/RelNotes/2.48.0.txt +++ b/Documentation/RelNotes/2.48.0.txt @@ -21,6 +21,24 @@ UI, Workflows & Features * Drop support for older libcURL and Perl. + * End-user experience of "git mergetool" when the command errors out + has been improved. + + * "git bundle --unbundle" and "git clone" running on a bundle file + both learned to trigger fsck over the new objects with configurable + fck check levels. + + * When "git fetch $remote" notices that refs/remotes/$remote/HEAD is + missing and discovers what branch the other side points with its + HEAD, refs/remotes/$remote/HEAD is updated to point to it. + + * "git fetch" honors "remote.<remote>.followRemoteHEAD" settings to + tweak the remote-tracking HEAD in "refs/remotes/<remote>/HEAD". + + * "git range-diff" learned to optionally show and compare merge + commits in the ranges being compared, with the --diff-merges + option. + Performance, Internal Implementation, Development Support etc. -------------------------------------------------------------- @@ -29,15 +47,15 @@ Performance, Internal Implementation, Development Support etc. * The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got - vastly pleasant to work with. + vastly more pleasant to work with. * The reftable library is now prepared to expect that the memory allocation function given to it may fail to allocate and to deal with such an error. * An extra worktree attached to a repository points at each other to - allow finding the repository from the worktree and vice versa - possible. Turn this linkage to relative paths. + allow finding the repository from the worktree (and vice versa) + possible. Use relative paths for this linkage. * Enable Windows-based CI in GitLab. @@ -76,7 +94,7 @@ Performance, Internal Implementation, Development Support etc. * Update the project's CodingGuidelines to discourage naming functions with a "_1()" suffix. - * Updates the '.clang-format' to match project conventions. + * Update '.clang-format' to match project conventions. * Centralize documentation for repository extensions into a single place. @@ -98,7 +116,7 @@ Performance, Internal Implementation, Development Support etc. * The migration procedure between two ref backends has been optimized. * "git fsck" learned to issue warnings on "curiously formatted" ref - contents that have always been taken valid but something Git + contents that have always been treated as valid but that Git wouldn't have written itself (e.g., missing terminating end-of-line after the full object name). @@ -107,18 +125,61 @@ Performance, Internal Implementation, Development Support etc. * Built-in Git subcommands are supplied the repository object to work with; they learned to do the same when they invoke sub-subcommands. + * Drop support for ancient environments in various CI jobs. + + * Isolate the reftable subsystem from the rest of Git's codebase by + using fewer pieces of Git's infrastructure. + + * Optimize reading random references out of the reftable backend by + allowing reuse of iterator objects. + + * Backport oss-fuzz tests to our codebase. + + * Introduce a new repository extension to prevent older Git versions + from mis-interpreting worktrees created with relative paths. + + * Yet another "pass the repository through the callchain" topic. + + * "git describe" learned to stop digging the history needlessly + deeper. + + * Build procedure update plus introduction of Meson based builds. + + * Recent reftable updates mistook a NULL return from a request for + 0-byte allocation as OOM and died unnecessarily, which has been + corrected. + + * Reftable backend adds check for upper limit of log's update_index. + + * Start working to make the codebase buildable with -Wsign-compare. + + * Regression fix for 'show-index' when run outside of a repository. + + * The meson-build procedure is integrated into CI to catch and + prevent bitrotting. + + * "git refs migrate" learned to also migrate the reflog data across + backends. + + * The developer documentation has been updated to give the latest + 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 ----------------- * Doc update to clarify how periodical maintenance are scheduled, - spread across time to avoid thundering hurds. + spread across time to avoid thundering herds. * Use after free and double freeing at the end in "git log -L... -p" had been identified and fixed. * On macOS, fsmonitor can fall into a race condition that results in - a client waiting forever to be notified for an event that have + a client waiting forever to be notified about an event that has already happened. This problem has been corrected. * "git maintenance start" crashed due to an uninitialized variable @@ -142,7 +203,7 @@ Fixes since v2.47 * The dumb-http code regressed when the result of re-indexing a pack yielded an *.idx file that differs in content from the *.idx file it downloaded from the remote. This has been corrected by no longer - relying on: the *.idx file we got from the remote. + relying on the *.idx file we got from the remote. * When called with '--left-right' and '--use-bitmap-index', 'rev-list' will produce output without any left/right markers, which has been @@ -166,7 +227,7 @@ Fixes since v2.47 * "git gc" discards any objects that are outside promisor packs that are referred to by an object in a promisor pack, and we do not refetch them from the promisor at runtime, resulting an unusable - repository. Work it around by including these objects in the + repository. Work around it by including these objects in the referring promisor pack at the receiving end of the fetch. * Avoid build/test breakage on a system without working malloc debug @@ -204,8 +265,66 @@ Fixes since v2.47 * The sequencer failed to honor core.commentString in some places. + * Describe a case where an option value needs to be spelled as a + separate argument, i.e. "--opt val", not "--opt=val". + (merge 1bc1e94091 jc/doc-opt-tilde-expand later to maint). + + * Loosen overly strict ownership check introduced in the recent past, + to keep the promise "cloning a suspicious repository is a safe + first step to inspect it". + (merge 0ffb5a6bf1 bc/allow-upload-pack-from-other-people later to maint). + + * "git fast-import" learned to reject paths with ".." and "." as + their components to avoid creating invalid tree objects. + (merge 8cb4c6e62f en/fast-import-verify-path later to maint). + + * The --ancestry-path option is designed to be given a commit that is + on the path, which was not documented, which has been corrected. + (merge bc1a980759 kk/doc-ancestry-path later to maint). + + * "git tag" has been taught to refuse to create refs/tags/HEAD + since such a tag will be confusing in the context of the UI provided by + the Git Porcelain commands. + (merge bbd445d5ef jc/forbid-head-as-tagname later to maint). + + * The advice messages now tell the newer 'git config set' command to + set the advice.token configuration variable to squelch a message. + (merge 6c397d0104 bf/explicit-config-set-in-advice-messages later to maint). + + * The syntax ":/<text>" to name the latest commit with the matching + text was broken with a recent change, which has been corrected. + (merge 0ff919e87a ps/commit-with-message-syntax-fix later to maint). + + * Fix performance regression of a recent "fatten promisor pack with + local objects" protection against an unwanted gc. + + * "git log -p --remerge-diff --reverse" was completely broken. + (merge f94bfa1516 js/log-remerge-keep-ancestry later to maint). + + * "git bundle create" with an annotated tag on the positive end of + the revision range had a workaround code for older limitation in + the revision walker, which has become unnecessary. + (merge dd1072dfa8 tc/bundle-with-tag-remove-workaround later to maint). + + * GitLab CI updates. + (merge c6b43f663e ps/ci-gitlab-update later to maint). + + * Code to reuse objects based on bitmap contents have been tightened + 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). (merge 68e3c69efa kh/trailer-in-glossary later to maint). (merge 91f88f76e6 tb/boundary-traversal-fix later to maint). + (merge 168ebb7159 jc/doc-error-message-guidelines later to maint). + (merge 18693d7d65 kh/doc-bundle-typofix later to maint). + (merge e2f5d3b491 kh/doc-update-ref-grammofix later to maint). + (merge 8525e92886 mh/doc-windows-home-env later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index db17bc7fe2..958e3cc3d5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -692,16 +692,17 @@ rebase when I receive your patches). Some parts of the system have dedicated maintainers with their own repositories. -- `git-gui/` comes from git-gui project, maintained by Johannes Sixt: +- `git-gui/` comes from the git-gui project, maintained by Johannes Sixt: https://github.com/j6t/git-gui -- `gitk-git/` comes from Paul Mackerras's gitk project: + Contibutions should go via the git mailing list. - git://git.ozlabs.org/~paulus/gitk +- `gitk-git/` comes from the gitk project, maintained by Johannes Sixt: - Those who are interested in improving gitk can volunteer to help Paul - maintain it, cf. <YntxL/fTplFm8lr6@cleo>. + https://github.com/j6t/gitk + + Contibutions should go via the git mailing list. - `po/` comes from the localization coordinator, Jiang Xin: diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf.in index f6da6d1fbd..f2aef6cb79 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf.in @@ -21,13 +21,26 @@ tilde=~ apostrophe=' backtick=` litdd=-- +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#<citerefentry>} {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} {0#</citerefentry>} +endif::doctype-book[] +ifdef::doctype-book[] +<ulink url="{target}.html">{target}{0?({0})}</ulink> +endif::doctype-book[] [literal-inlinemacro] {eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb.in index cb24480b63..2494f17a51 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb.in @@ -29,13 +29,12 @@ module Git class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor def process document, output if document.basebackend? 'docbook' - mansource = document.attributes['mansource'] - manversion = document.attributes['manversion'] - manmanual = document.attributes['manmanual'] + output = output.sub(/<refmiscinfo class="source">.*?<\/refmiscinfo>/, "") + output = output.sub(/<refmiscinfo class="manual">.*?<\/refmiscinfo>/, "") + output = output.sub(/<date>.*?<\/date>/, "<date>@GIT_DATE@</date>") new_tags = "" \ - "<refmiscinfo class=\"source\">#{mansource}</refmiscinfo>\n" \ - "<refmiscinfo class=\"version\">#{manversion}</refmiscinfo>\n" \ - "<refmiscinfo class=\"manual\">#{manmanual}</refmiscinfo>\n" + "<refmiscinfo class=\"source\">Git @GIT_VERSION@</refmiscinfo>\n" \ + "<refmiscinfo class=\"manual\">Git Manual</refmiscinfo>\n" output = output.sub(/<\/refmeta>/, new_tags + "</refmeta>") end output diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl index 1b3ac8fdd9..315efaa2fa 100755 --- a/Documentation/build-docdep.perl +++ b/Documentation/build-docdep.perl @@ -1,5 +1,6 @@ #!/usr/bin/perl +my ($build_dir) = @ARGV; my %include = (); my %included = (); @@ -10,6 +11,7 @@ for my $text (<*.txt>) { chomp; s/^include::\s*//; s/\[\]//; + s/{build_dir}/${build_dir}/; $include{$text}{$_} = 1; $included{$_} = 1; } diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 755a110bc4..e260a98977 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -3,12 +3,13 @@ use File::Compare qw(compare); sub format_one { - my ($out, $nameattr) = @_; + my ($source_dir, $out, $nameattr) = @_; my ($name, $attr) = @$nameattr; + my ($path) = "$source_dir/Documentation/$name.txt"; my ($state, $description); my $mansection; $state = 0; - open I, '<', "$name.txt" or die "No such file $name.txt"; + open I, '<', "$path" or die "No such file $path.txt"; while (<I>) { if (/^(?:git|scalar)[a-z0-9-]*\(([0-9])\)$/) { $mansection = $1; @@ -29,7 +30,7 @@ sub format_one { } close I; if (!defined $description) { - die "No description found in $name.txt"; + die "No description found in $path.txt"; } if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) { print $out "linkgit:$name\[$mansection\]::\n\t"; @@ -43,9 +44,9 @@ sub format_one { } } -my ($input, @categories) = @ARGV; +my ($source_dir, $build_dir, @categories) = @ARGV; -open IN, "<$input"; +open IN, "<$source_dir/command-list.txt"; while (<IN>) { last if /^### command list/; } @@ -63,17 +64,17 @@ close IN; for my $out (@categories) { my ($cat) = $out =~ /^cmds-(.*)\.txt$/; - open O, '>', "$out+" or die "Cannot open output file $out+"; + my ($path) = "$build_dir/$out"; + open O, '>', "$path+" or die "Cannot open output file $out+"; for (@{$cmds{$cat}}) { - format_one(\*O, $_); + format_one($source_dir, \*O, $_); } close O; - if (-f "$out" && compare("$out", "$out+") == 0) { - unlink "$out+"; + if (-f "$path" && compare("$path", "$path+") == 0) { + unlink "$path+"; } else { - print STDERR "$out\n"; - rename "$out+", "$out"; + rename "$path+", "$path"; } } diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 45f3fe855c..fdae13a212 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -218,7 +218,7 @@ endif::git-diff[] Set this option to `true` to make the diff driver cache the text conversion outputs. See linkgit:gitattributes[5] for details. -include::../mergetools-diff.txt[] +include::{build_dir}/mergetools-diff.txt[] `diff.indentHeuristic`:: Set this option to `false` to disable the default heuristics diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt index 5dc569d1c9..5cb4721a0e 100644 --- a/Documentation/config/extensions.txt +++ b/Documentation/config/extensions.txt @@ -63,6 +63,12 @@ Note that this setting should only be set by linkgit:git-init[1] or linkgit:git-clone[1]. Trying to change it after initialization will not work and will produce hard-to-diagnose issues. +relativeWorktrees:: + If enabled, indicates at least one worktree has been linked with + relative paths. Automatically set if a worktree has been created or + repaired with either the `--relative-paths` option or with the + `worktree.useRelativePaths` config set to `true`. + worktreeConfig:: If enabled, then worktrees will load config settings from the `$GIT_DIR/config.worktree` file in addition to the diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index 8851b6cede..82554d65a0 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -101,7 +101,7 @@ merge.guitool:: Any other value is treated as a custom merge tool and requires that a corresponding mergetool.<guitool>.cmd variable is defined. -include::../mergetools-merge.txt[] +include::{build_dir}/mergetools-merge.txt[] merge.verbosity:: Controls the amount of output shown by the recursive merge diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt index 6d8b7d6c63..4118c219c1 100644 --- a/Documentation/config/remote.txt +++ b/Documentation/config/remote.txt @@ -101,6 +101,19 @@ remote.<name>.serverOption:: The default set of server options used when fetching from this remote. These server options can be overridden by the `--server-option=` command line arguments. + +remote.<name>.followRemoteHEAD:: + How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`. + The default value is "create", which will create `remotes/<name>/HEAD` + if it exists on the remote, but not locally, but will not touch an + already existing local reference. Setting to "warn" will print + a message if the remote has a different value, than the local one and + in case there is no local reference, it behaves like "create". + A variant on "warn" is "warn-if-not-$branch", which behaves like + "warn", but if `HEAD` on the remote is `$branch` it will be silent. + Setting to "always" will silently update it to the value on the remote. + Finally, setting it to "never" will never change or create the local + reference. + This is a multi-valued variable, and an empty value can be used in a higher priority configuration file (e.g. `.git/config` in a repository) to clear diff --git a/Documentation/config/worktree.txt b/Documentation/config/worktree.txt index 048e349482..5e35c7d018 100644 --- a/Documentation/config/worktree.txt +++ b/Documentation/config/worktree.txt @@ -7,3 +7,13 @@ worktree.guessRemote:: such a branch exists, it is checked out and set as "upstream" for the new branch. If no such match can be found, it falls back to creating a new branch from the current HEAD. + +worktree.useRelativePaths:: + Link worktrees using relative paths (when "true") or absolute + paths (when "false"). This is particularly useful for setups + where the repository and worktrees may be moved between + different locations or environments. Defaults to "false". ++ +Note that setting `worktree.useRelativePaths` to "true" implies enabling the +`extension.relativeWorktrees` config (see linkgit:git-config[1]), +thus making it incompatible with older versions of Git. diff --git a/Documentation/generate-mergetool-list.sh b/Documentation/generate-mergetool-list.sh new file mode 100755 index 0000000000..6700498b93 --- /dev/null +++ b/Documentation/generate-mergetool-list.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +if test "$#" -ne 3 +then + echo >&2 "USAGE: $0 <SOURCE_DIR> <MODE> <OUTPUT>" + exit 1 +fi + +SOURCE_DIR="$1" +TOOL_MODE="$2" +OUTPUT="$3" +MERGE_TOOLS_DIR="$SOURCE_DIR/mergetools" + +( + . "$SOURCE_DIR"/git-mergetool--lib.sh && + show_tool_names can_$TOOL_MODE +) | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >"$OUTPUT" diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 504b8a8143..03cd36fe8d 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -32,7 +32,7 @@ Git commands that fetch or otherwise "read" via protocols such as possible linkgit:git-clone[1] a new repository from a bundle, to use linkgit:git-fetch[1] to fetch from one, and to list the references contained within it with linkgit:git-ls-remote[1]. There's no -corresponding "write" support, i.e.a 'git push' into a bundle is not +corresponding "write" support, i.e. a 'git push' into a bundle is not supported. BUNDLE FORMAT diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 7acb4cb176..de8d8f5893 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -63,6 +63,9 @@ symbolic link, the clone will fail. This is a security measure to prevent the unintentional copying of files by dereferencing the symbolic links. + +This option does not work with repositories owned by other users for security +reasons, and `--no-local` must be specified for the clone to succeed. ++ *NOTE*: this operation can race with concurrent modification to the source repository, similar to running `cp -r <src> <dst>` while modifying _<src>_. @@ -384,6 +387,12 @@ $ cd my-linux $ git clone --bare -l /home/proj/.git /pub/scm/proj.git ------------ +* Clone a local repository from a different user: ++ +------------ +$ git clone --no-local /home/otheruser/proj.git /pub/scm/proj.git +------------ + CONFIGURATION ------------- diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt index fbdbe0befe..db0e4279b5 100644 --- a/Documentation/git-range-diff.txt +++ b/Documentation/git-range-diff.txt @@ -10,7 +10,8 @@ SYNOPSIS [verse] 'git range-diff' [--color=[<when>]] [--no-color] [<diff-options>] [--no-dual-color] [--creation-factor=<factor>] - [--left-only | --right-only] + [--left-only | --right-only] [--diff-merges=<format>] + [--remerge-diff] ( <range1> <range2> | <rev1>...<rev2> | <base> <rev1> <rev2> ) [[--] <path>...] @@ -81,6 +82,20 @@ to revert to color all lines according to the outer diff markers Suppress commits that are missing from the second specified range (or the "right range" when using the `<rev1>...<rev2>` format). +--diff-merges=<format>:: + Instead of ignoring merge commits, generate diffs for them using the + corresponding `--diff-merges=<format>` option of linkgit:git-log[1], + and include them in the comparison. ++ +Note: In the common case, the `remerge` mode will be the most natural one +to use, as it shows only the diff on top of what Git's merge machinery would +have produced. In other words, if a merge commit is the result of a +non-conflicting `git merge`, the `remerge` mode will represent it with an empty +diff. + +--remerge-diff:: + Convenience option, equivalent to `--diff-merges=remerge`. + --[no-]notes[=<ref>]:: This flag is passed to the `git log` program (see linkgit:git-log[1]) that generates the patches. diff --git a/Documentation/git-refs.txt b/Documentation/git-refs.txt index ce31f93061..9829984b0a 100644 --- a/Documentation/git-refs.txt +++ b/Documentation/git-refs.txt @@ -57,8 +57,6 @@ KNOWN LIMITATIONS The ref format migration has several known limitations in its current form: -* It is not possible to migrate repositories that have reflogs. - * It is not possible to migrate repositories that have worktrees. * There is no way to block concurrent writes to the repository during an diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 8a4281cde9..9e6935d38d 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -93,11 +93,11 @@ update:: ref does not exist before the update. create:: - Create <ref> with <new-oid> after verifying it does not + Create <ref> with <new-oid> after verifying that it does not exist. The given <new-oid> may not be zero. delete:: - Delete <ref> after verifying it exists with <old-oid>, if + Delete <ref> after verifying that it exists with <old-oid>, if given. If given, <old-oid> may not be zero. symref-update:: @@ -110,11 +110,11 @@ verify:: <old-oid> is zero or missing, the ref must not exist. symref-create: - Create symbolic ref <ref> with <new-target> after verifying + Create symbolic ref <ref> with <new-target> after verifying that it does not exist. symref-delete:: - Delete <ref> after verifying it exists with <old-target>, if given. + Delete <ref> after verifying that it exists with <old-target>, if given. symref-verify:: Verify symbolic <ref> against <old-target> but do not change it. diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 70437c815f..8340b7f028 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -216,6 +216,14 @@ To remove a locked worktree, specify `--force` twice. This can also be set up as the default behaviour by using the `worktree.guessRemote` config option. +--[no-]relative-paths:: + Link worktrees using relative paths or absolute paths (default). + Overrides the `worktree.useRelativePaths` config option, see + linkgit:git-config[1]. ++ +With `repair`, the linking files will be updated if there's an absolute/relative +mismatch, even if the links are correct. + --[no-]track:: When creating a new branch, if `<commit-ish>` is a branch, mark it as "upstream" from the new branch. This is the diff --git a/Documentation/git.txt b/Documentation/git.txt index d15a869762..e89a91dd0d 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -245,17 +245,17 @@ ancillary user utilities. Main porcelain commands ~~~~~~~~~~~~~~~~~~~~~~~ -include::cmds-mainporcelain.txt[] +include::{build_dir}/cmds-mainporcelain.txt[] Ancillary Commands ~~~~~~~~~~~~~~~~~~ Manipulators: -include::cmds-ancillarymanipulators.txt[] +include::{build_dir}/cmds-ancillarymanipulators.txt[] Interrogators: -include::cmds-ancillaryinterrogators.txt[] +include::{build_dir}/cmds-ancillaryinterrogators.txt[] Interacting with Others @@ -264,7 +264,7 @@ Interacting with Others These commands are to interact with foreign SCM and with other people via patch over e-mail. -include::cmds-foreignscminterface.txt[] +include::{build_dir}/cmds-foreignscminterface.txt[] Reset, restore and revert ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -313,13 +313,13 @@ repositories. Manipulation commands ~~~~~~~~~~~~~~~~~~~~~ -include::cmds-plumbingmanipulators.txt[] +include::{build_dir}/cmds-plumbingmanipulators.txt[] Interrogation commands ~~~~~~~~~~~~~~~~~~~~~~ -include::cmds-plumbinginterrogators.txt[] +include::{build_dir}/cmds-plumbinginterrogators.txt[] In general, the interrogate commands do not touch the files in the working tree. @@ -328,12 +328,12 @@ the working tree. Syncing repositories ~~~~~~~~~~~~~~~~~~~~ -include::cmds-synchingrepositories.txt[] +include::{build_dir}/cmds-synchingrepositories.txt[] The following are helper commands used by the above; end users typically do not use them directly. -include::cmds-synchelpers.txt[] +include::{build_dir}/cmds-synchelpers.txt[] Internal helper commands @@ -342,14 +342,14 @@ Internal helper commands These are internal helper commands used by other commands; end users typically do not use them directly. -include::cmds-purehelpers.txt[] +include::{build_dir}/cmds-purehelpers.txt[] Guides ------ The following documentation pages are guides about Git concepts. -include::cmds-guide.txt[] +include::{build_dir}/cmds-guide.txt[] Repository, command and file interfaces --------------------------------------- @@ -358,7 +358,7 @@ This documentation discusses repository and command interfaces which users are expected to interact with directly. See `--user-formats` in linkgit:git-help[1] for more details on the criteria. -include::cmds-userinterfaces.txt[] +include::{build_dir}/cmds-userinterfaces.txt[] File formats, protocols and other developer interfaces ------------------------------------------------------ @@ -367,7 +367,7 @@ This documentation discusses file formats, over-the-wire protocols and other git developer interfaces. See `--developer-interfaces` in linkgit:git-help[1]. -include::cmds-developerinterfaces.txt[] +include::{build_dir}/cmds-developerinterfaces.txt[] Configuration Mechanism ----------------------- @@ -477,6 +477,14 @@ 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: + `$HOMEDRIVE$HOMEPATH` if both `$HOMEDRIVE` and `$HOMEPATH` exist; + otherwise `$USERPROFILE` if `$USERPROFILE` exists. + The Git Repository ~~~~~~~~~~~~~~~~~~ These environment variables apply to 'all' core Git commands. Nb: it diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 7c709324ba..fcd86d2eee 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -90,6 +90,15 @@ scripting Git: for long options. An option that takes optional option-argument must be 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 + 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 + the latter. Some of our commands know how to tilde-expand the + option value even when given in the stuck form, but not all of + them do. + * When you give a revision parameter to a command, make sure the parameter is not ambiguous with a name of a file in the work tree. E.g. do not write `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 71dd19731a..35a7452c8f 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -242,6 +242,12 @@ Here are some example specifications: [credential] helper = "foo --bar='whitespace arg'" +# store helper (discouraged) with custom location for the db file; +# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`, +# to allow the shell to expand tilde to the home directory. +[credential] + helper = "store --file ~/.git-secret.txt" + # you can also use an absolute path, which will not use the git wrapper [credential] helper = "/path/to/my/helper --with-arguments" diff --git a/Documentation/howto-index.sh b/Documentation/howto/howto-index.sh index 167b363668..eecd123a93 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 0000000000..c023c10416 --- /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 new file mode 100644 index 0000000000..2a26fa8a5f --- /dev/null +++ b/Documentation/meson.build @@ -0,0 +1,504 @@ +manpages = { + # Category 1. + 'git-add.txt' : 1, + 'git-am.txt' : 1, + 'git-annotate.txt' : 1, + 'git-apply.txt' : 1, + 'git-archimport.txt' : 1, + 'git-archive.txt' : 1, + 'git-bisect.txt' : 1, + 'git-blame.txt' : 1, + 'git-branch.txt' : 1, + 'git-bugreport.txt' : 1, + 'git-bundle.txt' : 1, + 'git-cat-file.txt' : 1, + 'git-check-attr.txt' : 1, + 'git-check-ignore.txt' : 1, + 'git-check-mailmap.txt' : 1, + 'git-checkout-index.txt' : 1, + 'git-checkout.txt' : 1, + 'git-check-ref-format.txt' : 1, + 'git-cherry-pick.txt' : 1, + 'git-cherry.txt' : 1, + 'git-citool.txt' : 1, + 'git-clean.txt' : 1, + 'git-clone.txt' : 1, + 'git-column.txt' : 1, + 'git-commit-graph.txt' : 1, + 'git-commit-tree.txt' : 1, + 'git-commit.txt' : 1, + 'git-config.txt' : 1, + 'git-count-objects.txt' : 1, + 'git-credential-cache--daemon.txt' : 1, + 'git-credential-cache.txt' : 1, + 'git-credential-store.txt' : 1, + 'git-credential.txt' : 1, + 'git-cvsexportcommit.txt' : 1, + 'git-cvsimport.txt' : 1, + 'git-cvsserver.txt' : 1, + 'git-daemon.txt' : 1, + 'git-describe.txt' : 1, + 'git-diagnose.txt' : 1, + 'git-diff-files.txt' : 1, + 'git-diff-index.txt' : 1, + 'git-difftool.txt' : 1, + 'git-diff-tree.txt' : 1, + 'git-diff.txt' : 1, + 'git-fast-export.txt' : 1, + 'git-fast-import.txt' : 1, + 'git-fetch-pack.txt' : 1, + 'git-fetch.txt' : 1, + 'git-filter-branch.txt' : 1, + 'git-fmt-merge-msg.txt' : 1, + 'git-for-each-ref.txt' : 1, + 'git-for-each-repo.txt' : 1, + 'git-format-patch.txt' : 1, + 'git-fsck-objects.txt' : 1, + 'git-fsck.txt' : 1, + 'git-fsmonitor--daemon.txt' : 1, + 'git-gc.txt' : 1, + 'git-get-tar-commit-id.txt' : 1, + 'git-grep.txt' : 1, + 'git-gui.txt' : 1, + 'git-hash-object.txt' : 1, + 'git-help.txt' : 1, + 'git-hook.txt' : 1, + 'git-http-backend.txt' : 1, + 'git-http-fetch.txt' : 1, + 'git-http-push.txt' : 1, + 'git-imap-send.txt' : 1, + 'git-index-pack.txt' : 1, + 'git-init-db.txt' : 1, + 'git-init.txt' : 1, + 'git-instaweb.txt' : 1, + 'git-interpret-trailers.txt' : 1, + 'git-log.txt' : 1, + 'git-ls-files.txt' : 1, + 'git-ls-remote.txt' : 1, + 'git-ls-tree.txt' : 1, + 'git-mailinfo.txt' : 1, + 'git-mailsplit.txt' : 1, + 'git-maintenance.txt' : 1, + 'git-merge-base.txt' : 1, + 'git-merge-file.txt' : 1, + 'git-merge-index.txt' : 1, + 'git-merge-one-file.txt' : 1, + 'git-mergetool--lib.txt' : 1, + 'git-mergetool.txt' : 1, + 'git-merge-tree.txt' : 1, + 'git-merge.txt' : 1, + 'git-mktag.txt' : 1, + 'git-mktree.txt' : 1, + 'git-multi-pack-index.txt' : 1, + 'git-mv.txt' : 1, + 'git-name-rev.txt' : 1, + 'git-notes.txt' : 1, + 'git-p4.txt' : 1, + 'git-pack-objects.txt' : 1, + 'git-pack-redundant.txt' : 1, + 'git-pack-refs.txt' : 1, + 'git-patch-id.txt' : 1, + 'git-prune-packed.txt' : 1, + 'git-prune.txt' : 1, + 'git-pull.txt' : 1, + 'git-push.txt' : 1, + 'git-quiltimport.txt' : 1, + 'git-range-diff.txt' : 1, + 'git-read-tree.txt' : 1, + 'git-rebase.txt' : 1, + 'git-receive-pack.txt' : 1, + 'git-reflog.txt' : 1, + 'git-refs.txt' : 1, + 'git-remote-ext.txt' : 1, + 'git-remote-fd.txt' : 1, + 'git-remote.txt' : 1, + 'git-repack.txt' : 1, + 'git-replace.txt' : 1, + 'git-replay.txt' : 1, + 'git-request-pull.txt' : 1, + 'git-rerere.txt' : 1, + 'git-reset.txt' : 1, + 'git-restore.txt' : 1, + 'git-revert.txt' : 1, + 'git-rev-list.txt' : 1, + 'git-rev-parse.txt' : 1, + 'git-rm.txt' : 1, + 'git-send-email.txt' : 1, + 'git-send-pack.txt' : 1, + 'git-shell.txt' : 1, + 'git-sh-i18n--envsubst.txt' : 1, + 'git-sh-i18n.txt' : 1, + 'git-shortlog.txt' : 1, + 'git-show-branch.txt' : 1, + 'git-show-index.txt' : 1, + 'git-show-ref.txt' : 1, + 'git-show.txt' : 1, + 'git-sh-setup.txt' : 1, + 'git-sparse-checkout.txt' : 1, + 'git-stage.txt' : 1, + 'git-stash.txt' : 1, + 'git-status.txt' : 1, + 'git-stripspace.txt' : 1, + 'git-submodule.txt' : 1, + 'git-svn.txt' : 1, + 'git-switch.txt' : 1, + 'git-symbolic-ref.txt' : 1, + 'git-tag.txt' : 1, + 'git-unpack-file.txt' : 1, + 'git-unpack-objects.txt' : 1, + 'git-update-index.txt' : 1, + 'git-update-ref.txt' : 1, + 'git-update-server-info.txt' : 1, + 'git-upload-archive.txt' : 1, + 'git-upload-pack.txt' : 1, + 'git-var.txt' : 1, + 'git-verify-commit.txt' : 1, + 'git-verify-pack.txt' : 1, + 'git-verify-tag.txt' : 1, + 'git-version.txt' : 1, + 'git-web--browse.txt' : 1, + 'git-whatchanged.txt' : 1, + 'git-worktree.txt' : 1, + 'git-write-tree.txt' : 1, + 'git.txt' : 1, + 'gitk.txt' : 1, + 'gitweb.txt' : 1, + 'scalar.txt' : 1, + + # Category 5. + 'gitattributes.txt' : 5, + 'gitformat-bundle.txt' : 5, + 'gitformat-chunk.txt' : 5, + 'gitformat-commit-graph.txt' : 5, + 'gitformat-index.txt' : 5, + 'gitformat-pack.txt' : 5, + 'gitformat-signature.txt' : 5, + 'githooks.txt' : 5, + 'gitignore.txt' : 5, + 'gitmailmap.txt' : 5, + 'gitmodules.txt' : 5, + 'gitprotocol-capabilities.txt' : 5, + 'gitprotocol-common.txt' : 5, + 'gitprotocol-http.txt' : 5, + 'gitprotocol-pack.txt' : 5, + 'gitprotocol-v2.txt' : 5, + 'gitrepository-layout.txt' : 5, + 'gitweb.conf.txt' : 5, + + # Category 7. + 'gitcli.txt' : 7, + 'gitcore-tutorial.txt' : 7, + 'gitcredentials.txt' : 7, + 'gitcvs-migration.txt' : 7, + 'gitdiffcore.txt' : 7, + 'giteveryday.txt' : 7, + 'gitfaq.txt' : 7, + 'gitglossary.txt' : 7, + 'gitpacking.txt' : 7, + 'gitnamespaces.txt' : 7, + 'gitremote-helpers.txt' : 7, + 'gitrevisions.txt' : 7, + 'gitsubmodules.txt' : 7, + 'gittutorial-2.txt' : 7, + 'gittutorial.txt' : 7, + 'gitworkflows.txt' : 7, +} + +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 + +if docs_backend == 'asciidoc' + asciidoc = find_program('asciidoc', required: true) + asciidoc_html = 'xhtml11' + asciidoc_docbook = 'docbook' + xmlto_extra = [ ] + + 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', + 'cmds-ancillarymanipulators.txt', + 'cmds-mainporcelain.txt', + 'cmds-plumbinginterrogators.txt', + 'cmds-plumbingmanipulators.txt', + 'cmds-synchingrepositories.txt', + 'cmds-synchelpers.txt', + 'cmds-guide.txt', + 'cmds-developerinterfaces.txt', + 'cmds-userinterfaces.txt', + 'cmds-purehelpers.txt', + 'cmds-foreignscminterface.txt', +] + +documentation_deps += custom_target( + command: [ + perl, + '@INPUT@', + meson.project_source_root(), + meson.current_build_dir(), + ] + cmd_lists, + input: 'cmd-list.perl', + output: cmd_lists +) + +foreach mode : [ 'diff', 'merge' ] + documentation_deps += custom_target( + command: [ + shell, + '@INPUT@', + '..', + mode, + '@OUTPUT@' + ], + env: [ + 'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools', + ], + input: 'generate-mergetool-list.sh', + output: 'mergetools-' + mode + '.txt', + ) +endforeach + +foreach manpage, category : manpages + if get_option('docs').contains('man') + manpage_xml_target = custom_target( + command: asciidoc_common_options + [ + '--backend=' + asciidoc_docbook, + '--doctype=manpage', + '--out-file=@OUTPUT@', + '@INPUT@', + ], + depends: documentation_deps, + input: manpage, + output: fs.stem(manpage) + '.xml', + ) + + manpage_path = fs.stem(manpage) + '.' + category.to_string() + manpage_target = custom_target( + command: [ + xmlto, + '-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, + install_dir: get_option('mandir') / 'man' + category.to_string(), + ) + endif + + if get_option('docs').contains('html') + custom_target( + command: asciidoc_common_options + [ + '--backend=' + asciidoc_html, + '--doctype=manpage', + '--out-file=@OUTPUT@', + '@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/rev-list-options.txt b/Documentation/rev-list-options.txt index 00ccf68744..459e5a02f5 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -412,7 +412,8 @@ Default mode:: --ancestry-path[=<commit>]:: When given a range of commits to display (e.g. 'commit1..commit2' - or 'commit2 {caret}commit1'), only display commits in that range + or 'commit2 {caret}commit1'), and a commit <commit> in that range, + only display commits in that range that are ancestors of <commit>, descendants of <commit>, or <commit> itself. If no commit is specified, use 'commit1' (the excluded part of the range) as <commit>. Can be passed multiple diff --git a/Documentation/technical/api-index.sh b/Documentation/technical/api-index.sh index 9c3f4131b8..2964885574 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 <SOURCE_DIR> <OUTPUT>" + exit 1 +fi + +SOURCE_DIR="$1" +OUTPUT="$2" + ( + cd "$SOURCE_DIR" + c=//////////////////////////////////////////////////////////////// skel=api-index-skel.txt sed -e '/^\/\/ table of contents begin/q' "$skel" @@ -18,11 +29,11 @@ done echo "$c" sed -n -e '/^\/\/ table of contents end/,$p' "$skel" -) >api-index.txt+ +) >"$OUTPUT"+ -if test -f api-index.txt && cmp api-index.txt api-index.txt+ >/dev/null +if test -f "$OUTPUT" && cmp "$OUTPUT" "$OUTPUT"+ >/dev/null then - rm -f api-index.txt+ + rm -f "$OUTPUT"+ else - mv api-index.txt+ api-index.txt + mv "$OUTPUT"+ "$OUTPUT" fi diff --git a/Documentation/technical/build-systems.txt b/Documentation/technical/build-systems.txt new file mode 100644 index 0000000000..d9dafb407c --- /dev/null +++ b/Documentation/technical/build-systems.txt @@ -0,0 +1,224 @@ += Build Systems + +The build system is the primary way for both developers and system integrators +to interact with the Git project. As such, being easy to use and extend for +those who are not directly developing Git itself is just as important as other +requirements we have on any potential build system. + +This document outlines the different requirements that we have for the build +system and then compares available build systems using these criteria. + +== Requirements + +The following subsections present a list of requirements that we have for any +potential build system. Sections are sorted by decreasing priority. + +=== Platform support + +The build system must have support for all of our platforms that we continually +test against as outlined by our platform support policy. These platforms are: + + - Linux + - Windows + - macOS + +Furthermore, the build system should have support for the following platforms +that generally have somebody running test pipelines against regularly: + + - AIX + - FreeBSD + - NetBSD + - NonStop + - OpenBSD + +The platforms which must be supported by the tool should be aligned with our +[platform support policy](platform-support.txt). + +=== Auto-detection of supported features + +The build system must support auto-detection of features which are or aren't +available on the current platform. Platform maintainers should not be required +to manually configure the complete build. + +Auto-detection of the following items is considered to be important: + + - Check for the existence of headers. + - Check for the existence of libraries. + - Check for the existence of exectuables. + - Check for the runtime behavior of specific functions. + - Check for specific link order requirements when multiple libraries are + involved. + +=== Ease of use + +The build system should be both easy to use and easy to extend. While this is +naturally a subjective metric it is likely not controversial to say that some +build systems are considerably harder to use than others. + +=== IDE support + +The build system should integrate with well-known IDEs. Well-known IDEs include: + + - Microsoft Visual Studio + - Visual Studio Code + - Xcode + +There are four levels of support: + + - Native integration into the IDE. + - Integration into the IDE via a plugin. + - Integration into the IDE via generating a project description with the build + system. + - No integration. + +Native integration is preferable, but integration via either a plugin or by +generating a project description via the build system are considered feasible +alternatives. + +Another important distinction is the level of integration. There are two +features that one generally wants to have: + + - Integration of build targets. + - Automatic setup of features like code completion with detected build + dependencies. + +The first bullet point is the bare minimum, but is not sufficient to be +considered proper integration. + +=== Out-of-tree builds + +The build system should support out-of-tree builds. Out-of-tree builds allow a +developer to configure multiple different build directories with different +configuration, e.g. one "debug" build and one "release" build. + +=== Cross-platform builds + +The build system should support cross-platform builds, e.g. building for arm on +an x86-64 host. + +=== Language support + +The following languages and toolchains are of relevance and should be supported +by the build system: + + - C: the primary compiled language used by Git, must be supported. Relevant + toolchains are GCC, Clang and MSVC. + - Rust: candidate as a second compiled lanugage, should be supported. Relevant + toolchains is the LLVM-based rustc. + +Built-in support for the respective languages is preferred over support that +needs to be wired up manually to avoid unnecessary complexity. Native support +includes the following features: + + - Compiling objects. + - Dependency tracking. + - Detection of available features. + - Discovery of relevant toolchains. + - Linking libraries and executables. + - Templating placeholders in scripts. + +=== Test integration + +It should be possible to integrate tests into the build system such that it is +possible to build and test Git within the build system. Features which are nice +to have: + + - Track build-time dependencies for respective tests. Unit tests have + different requirements than integration tests. + - Allow filtering of which tests to run. + - Allow running tests such that utilities like `test_pause` or `debug` work. + +== Comparison + +The following list of build systems are considered: + +- GNU Make +- autoconf +- CMake +- Meson + +=== GNU Make + +- Platform support: ubitquitous on all platforms, but not well-integrated into Windows. +- Auto-detection: no built-in support for auto-detection of features. +- Ease of use: easy to use, but discovering available options is hard. Makefile + rules can quickly get out of hand once reaching a certain scope. +- IDE support: execution of Makefile targets is supported by many IDEs +- Out-of-tree builds: supported in theory, not wired up in practice. +- Cross-platform builds: supported in theory, not wired up in practice. +- Language support: + - C: Limited built-in support, many parts need to be wired up manually. + - Rust: No built-in support, needs to be wired up manually. +- Test integration: partially supported, many parts need to be wired up + manually. + +=== autoconf + +- Platform support: ubiquitous on all platforms, but not well-integrated into Windows. +- Auto-detection: supported. +- Ease of use: easy to use, discovering available options is comparatively + easy. The autoconf syntax is prohibitively hard to extend though due to its + complex set of interacting files and the hard-to-understand M4 language. +- IDE support: no integration into IDEs at generation time. The generated + Makefiles have the same level of support as GNU Make. +- Out-of-tree builds: supported in theory, not wired up in practice. +- Cross-platform builds: supported. +- Language support: + - C: Limited built-in support, many parts need to be wired up manually. + - Rust: No built-in support, needs to be wired up manually. +- Test integration: partially supported, many parts need to be wired up + manually. + +=== CMake + +- Platform support: not as extensive as GNU Make or autoconf, but all major + platforms are supported. + - AIX + - Cygwin + - FreeBSD + - Linux + - OpenBSD + - Solaris + - Windows + - macOS +- Ease of use: easy to use, discovering available options is not always + trivial. The scripting language used by CMake is somewhat cumbersome to use, + but extending CMake build instructions is doable. +- IDE support: natively integrated into Microsoft Visual Studio. Can generate + project descriptions for Xcode. An extension is available for Visual Studio + Code. Many other IDEs have plugins for CMake. +- Out-of-tree builds: supported. +- Cross-platform builds: supported. +- Language support: + - C: Supported for GCC, Clang, MSVC and other toolchains. + - Rust: No built-in support, needs to be wired up manually. +- Test integration: supported, even though test dependencies are a bit + cumbersome to use via "test fixtures". Interactive test runs are not + supported. + +=== Meson + +- Platform: not as extensive as GNU Make or autoconf, but all major platforms + and some smaller ones are supported. + - AIX + - Cygwin + - DragonflyBSD + - FreeBSD + - Haiku + - Linux + - NetBSD + - OpenBSD + - Solaris + - Windows + - macOS +- Ease of use: easy to use, discovering available options is easy. The + scripting language is straight-forward to use. +- IDE support: Supports generating build instructions for Xcode and Microsoft + Visual Studio, a plugin exists for Visual Studio Code. +- Out-of-tree builds: supported. +- Cross-platform builds: supported. +- Language support: + - C: Supported for GCC, Clang, MSVC and other toolchains. + - Rust: Supported for rustc. +- Test integration: supported. Interactive tests are supported starting with + Meson 1.5.0 via the `--interactive` flag. diff --git a/Documentation/technical/meson.build b/Documentation/technical/meson.build new file mode 100644 index 0000000000..21dfb8b5c9 --- /dev/null +++ b/Documentation/technical/meson.build @@ -0,0 +1,66 @@ +api_docs = [ + 'api-error-handling.txt', + 'api-merge.txt', + 'api-parse-options.txt', + 'api-simple-ipc.txt', + 'api-trace2.txt', +] + +articles = [ + 'bitmap-format.txt', + 'build-systems.txt', + 'bundle-uri.txt', + 'commit-graph.txt', + 'directory-rename-detection.txt', + 'hash-function-transition.txt', + 'long-running-process-protocol.txt', + 'multi-pack-index.txt', + 'packfile-uri.txt', + 'pack-heuristics.txt', + 'parallel-checkout.txt', + 'partial-clone.txt', + 'platform-support.txt', + 'racy-git.txt', + 'reftable.txt', + 'remembering-renames.txt', + 'repository-version.txt', + 'rerere.txt', + 'scalar.txt', + 'send-pack-pipeline.txt', + 'shallow.txt', + 'sparse-checkout.txt', + 'sparse-index.txt', + 'trivial-merge.txt', + 'unit-tests.txt', +] + +api_index = custom_target( + command: [ + shell, + meson.current_source_dir() / 'api-index.sh', + meson.current_source_dir(), + '@OUTPUT@', + ], + env: script_environment, + input: api_docs, + output: 'api-index.txt', +) + +custom_target( + command: asciidoc_html_options, + input: api_index, + output: 'api-index.html', + depends: documentation_deps, + install: true, + install_dir: get_option('datadir') / 'doc/git-doc/technical', +) + +foreach article : api_docs + articles + custom_target( + command: asciidoc_html_options, + input: article, + output: fs.stem(article) + '.html', + install: true, + install_dir: get_option('datadir') / 'doc/git-doc/technical', + ) +endforeach diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf deleted file mode 100644 index 0148f126dc..0000000000 --- a/Documentation/user-manual.conf +++ /dev/null @@ -1,11 +0,0 @@ -[titles] - underlines="__","==","--","~~","^^" - -[attributes] -caret=^ -startsb=[ -endsb=] -tilde=~ - -[linkgit-inlinemacro] -<ulink url="{target}.html">{target}{0?({0})}</ulink> |