git/Documentation/Makefile, branch v2.35.2

Merge branch 'ab/fix-make-lint-docs'

2021-10-29T22:43:13Z

Hotfix for a topic recently merged to 'master'. * ab/fix-make-lint-docs: Documentation/Makefile: fix lint-docs mkdir dependency

Documentation/Makefile: fix lint-docs mkdir dependency

2021-10-27T23:57:14Z

Since 8650c6298c (doc lint: make "lint-docs" non-.PHONY, 2021-10-15), we put the output for gitlink linter into .build/lint-docs/gitlink. There are order-only dependencies to create the sequence of subdirs like: .build/lint-docs: | .build $(QUIET)mkdir $@ .build/lint-docs/gitlink: | .build/lint-docs $(QUIET)mkdir $@ where each level has to depend on the prior one (since the parent directory must exist for us to create something inside it). But the "howto" and "config" subdirectories of gitlink have the wrong dependency; they depend on "lint-docs", not "lint-docs/gitlink". This usually works out, because the LINT_DOCS_GITLINK targets which depend on "gitlink/howto" also depend on just "gitlink", so the directory gets created anyway. But since we haven't given make an explicit ordering, things can racily happen out of order. If you stick a "sleep 1" in the rule to build "gitlink" like this: ## Lint: gitlink .build/lint-docs/gitlink: | .build/lint-docs - $(QUIET)mkdir $@ + $(QUIET)sleep 1 && mkdir $@ then "make clean; make lint-docs" will fail reliably. Or you can see it as-is just by building the directory in isolation: $ make clean [...] $ make .build/lint-docs/gitlink/howto GEN mergetools-list.made GEN cmd-list.made GEN doc.dep SUBDIR ../ make[1]: 'GIT-VERSION-FILE' is up to date. SUBDIR ../ make[1]: 'GIT-VERSION-FILE' is up to date. mkdir: cannot create directory ‘.build/lint-docs/gitlink/howto’: No such file or directory make: *** [Makefile:476: .build/lint-docs/gitlink/howto] Error 1 The fix is easy: we just need to depend on the correct parent directory. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

Merge branch 'ab/fix-make-lint-docs'

2021-10-25T23:07:01Z

Build fix. * ab/fix-make-lint-docs: doc lint: make "lint-docs" non-.PHONY doc build: speed up "make lint-docs" doc lint: emit errors on STDERR doc lint: fix error-hiding regression

Merge branch 'tz/doc-link-to-bundle-format-fix'

2021-10-18T22:47:59Z

Doc update. * tz/doc-link-to-bundle-format-fix: doc: add bundle-format to TECH_DOCS

doc lint: make "lint-docs" non-.PHONY

2021-10-15T17:29:11Z

Speed up the "lint-docs" target by making it non-.PHONY. Similar to my c234e8a0ecf (Makefile: make the "sparse" target non-.PHONY, 2021-09-23). We'll now create empty files corresponding to a dependency graph for each of these lint scripts. This speeds things up a bit[1], and makes the output correspond to any in-tree changes we have: $ touch git-add.txt; make lint-docs; make lint-docs GEN cmd-list.made GEN doc.dep LINT GITLINK git-add.txt LINT MAN END git-add.txt LINT MAN SEC git-add.txt make: Nothing to be done for 'lint-docs'. As with the "sparse" target changes this has a hard dependency on the use of ".DELETE_ON_ERROR" in the Makefile, added here in db10fc6c09f (doc: simplify Makefile using .DELETE_ON_ERROR, 2021-05-21). This method also depends on the output for us emitting any errors on STDERR (fixed in a preceding commit), as well us these scripts exiting with non-zero on any errors (which they were already doing). 1. $ git show HEAD~:Documentation/Makefile >Makefile.old $ hyperfine --warmup 2 -L f ",.old" 'make -j1 -f Makefile{f} lint-docs' Benchmark #1: make -j1 -f Makefile lint-docs Time (mean ± σ): 60.8 ms ± 1.4 ms [User: 58.7 ms, System: 2.5 ms] Range (min … max): 58.9 ms … 64.0 ms 48 runs Benchmark #2: make -j1 -f Makefile.old lint-docs Time (mean ± σ): 84.0 ms ± 1.5 ms [User: 78.6 ms, System: 5.7 ms] Range (min … max): 81.8 ms … 87.8 ms 35 runs Summary 'make -j1 -f Makefile lint-docs' ran 1.38 ± 0.04 times faster than 'make -j1 -f Makefile.old lint-docs' Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

doc build: speed up "make lint-docs"

2021-10-15T17:20:21Z

Extend the trick we use to speed up the "clean" target to also extend to the "lint-docs" target. See 54df87555b1 (Documentation/Makefile: conditionally include doc.dep, 2020-12-08) for the "clean" implementation. The "doc-lint" target only depends on *.txt files, so we don't need to generate GIT-VERSION-FILE etc. if that's all we're doing. This makes the "make lint-docs" target more than 2x as fast: $ git show HEAD~:Documentation/Makefile >Makefile.old $ hyperfine -L f ",.old" 'make -f Makefile{f} lint-docs' Benchmark #1: make -f Makefile lint-docs Time (mean ± σ): 100.2 ms ± 1.3 ms [User: 93.7 ms, System: 6.7 ms] Range (min … max): 98.4 ms … 103.1 ms 29 runs Benchmark #2: make -f Makefile.old lint-docs Time (mean ± σ): 220.0 ms ± 20.0 ms [User: 206.0 ms, System: 18.0 ms] Range (min … max): 206.6 ms … 267.5 ms 11 runs Summary 'make -f Makefile lint-docs' ran 2.19 ± 0.20 times faster than 'make -f Makefile.old lint-docs' Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

doc lint: fix error-hiding regression

2021-10-15T17:16:36Z

Fix the broken "make lint-docs" (or "make check-docs" at the top-level) target, which has been broken since my cafd9828e89 (doc lint: lint and fix missing "GIT" end sections, 2021-04-09). The CI for "seen" is emitting an error about a broken gitlink, but due to there being 3x scripts chained via ";" instead of "&&" we're not carrying forward the non-zero exit code. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

doc: add bundle-format to TECH_DOCS

2021-10-13T18:05:04Z

A link to the bundle-format was added in 5c8273d57c (bundle doc: rewrite the "DESCRIPTION" section, 2021-07-31). Ensure `technical/bundle-format.html` is created to avoid a broken link in `git-bundle.html`. Signed-off-by: Todd Zullinger Signed-off-by: Junio C Hamano

doc: avoid using rm directly

2021-05-24T09:08:22Z

That's what we have $(RM) for. Signed-off-by: Felipe Contreras Signed-off-by: Junio C Hamano

doc: simplify Makefile using .DELETE_ON_ERROR

2021-05-24T09:08:22Z

Currently GNU make already removes files when catching an interruption signal, however, in order to deal with other kinds of errors a workaround is in place to store target output to a temporary file, and only move it to its right place on success. By enabling the built-in .DELETE_ON_ERROR we let make do this task, so we don't have to. This way the rules can be simplified a lot. Suggested-by: Ævar Arnfjörð Bjarmason Signed-off-by: Felipe Contreras Signed-off-by: Junio C Hamano