kernel/git - git - PowerEL Git System

Commit Graph

Author	SHA1	Message	Date
Taylor Blau	3d89a8c118	Documentation/technical: add cruft-packs.txt Create a technical document to explain cruft packs. It contains a brief overview of the problem, some background, details on the implementation, and a couple of alternative approaches not considered here. Signed-off-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
COGONI Guillaume	7a06a854ee	Documentation/ToolsForGit.txt: Tools for developing Git This document gathers tips, scripts and configuration file to help people working on Git’s codebase use their favorite tools while following Git’s coding style. Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools. But, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines because there is also information about the coding style in it. Helped-by: Matthieu Moy <Matthieu.Moy@univ-lyon1.fr> Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: COGONI Guillaume <cogoni.guillaume@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Ævar Arnfjörð Bjarmason	8af0699b7a	Documentation/Makefile: fix "make info" regression in `dad9cd7d51` Fix a regression in my `dad9cd7d51` (Makefile: move ".SUFFIXES" rule to shared.mak, 2022-03-03). As explained in the GNU make documentation for the $* variable, available at: info make --index-search='$' This rule relied on ".texi" being in the default list of suffixes, as seen at: make -f/dev/null -p \| grep -v -e ^# -e ^$\|grep -F .SUFFIXES The documentation explains what was going on here: In an explicit rule, there is no stem; so '$' cannot be determined in that way. Instead, if the target name ends with a recognized suffix (note Old-Fashioned Suffix Rules: Suffix Rules.), '$' is set to the target name minus the suffix. For example, if the target name is 'foo.c', then '$' is set to 'foo', since '.c' is a suffix. GNU 'make' does this bizarre thing only for compatibility with other implementations of 'make'. You should generally avoid using '$' except in implicit rules or static pattern rules. If the target name in an explicit rule does not end with a recognized suffix, '$' is set to the empty string for that rule. I.e. this rule added back in `5cefc33bff` (Documentation: add gitman.info target, 2007-12-10) was resolving gitman.texi from gitman.info. We can instead just use the more obvious $< variable referring to the prerequisite. This was the only use of $ in our Makefiles in an explicit rule, the three remaining ones are all implicit rules, and therefore didn't depend on the ".SUFFIXES" list. Reported-by: Adam Dinwoodie <adam@dinwoodie.org> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Tested-by: Adam Dinwoodie <adam@dinwoodie.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Fernando Ramos	7b5cf8be18	vimdiff: add tool documentation Running 'git {merge,diff}tool --tool-help' now also prints usage information about the vimdiff tool (and its variants) instead of just its name. Two new functions ('diff_cmd_help()' and 'merge_cmd_help()') have been added to the set of functions that each merge tool (ie. scripts found inside "mergetools/") can overwrite to provided tool specific information. Right now, only 'mergetools/vimdiff' implements these functions, but other tools are encouraged to do so in the future, specially if they take configuration options not explained anywhere else (as it is the case with the 'vimdiff' tool and the new 'layout' option) Note that the function 'show_tool_names', used in the implementation of 'git mergetool --tool-help', is also used in Documentation/Makefile to generate the list of allowed values for the configuration variables '{diff,merge}.{gui,}tool'. Adjust the rule so its output is an Asciidoc "description list" instead of a plain list, with the tool name as the item and the newly added tool description as the description. In addition, a section has been added to "Documentation/git-mergetool.txt" to explain the new "layout" configuration option with examples. Helped-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Fernando Ramos <greenfoo@u92.eu> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Ævar Arnfjörð Bjarmason	0b6d0bc924	Makefiles: add and use wildcard "mkdir -p" template Add a template to do the "mkdir -p" of $(@D) (the parent dir of $@) for us, and use it for the "make lint-docs" targets I added in `8650c6298c` (doc lint: make "lint-docs" non-.PHONY, 2021-10-15). As seen in `4c64fb5aad` (Documentation/Makefile: fix lint-docs mkdir dependency, 2021-10-26) maintaining these manual lists of parent directory dependencies is fragile, in addition to being obviously verbose. I used this pattern at the time because I couldn't find another method than "order-only" prerequisites to avoid doing a "mkdir -p $(@D)" for every file being created, which as noted in [1] would be significantly slower. But as it turns out we can use this neat trick of only doing a "mkdir -p" if the $(wildcard) macro tells us the path doesn't exist. A re-run of a performance test similar to that noted downthread of [1] in [2] shows that this is faster, in addition to being less verbose and more reliable (this uses my "git-hyperfine" thin wrapper for "hyperfine"[3]): $ git -c hyperfine.hook.setup= hyperfine -L rev HEAD~1,HEAD~0 -s 'make -C Documentation lint-docs' -p 'rm -rf Documentation/.build' 'make -C Documentation -j1 lint-docs' Benchmark 1: make -C Documentation -j1 lint-docs' in 'HEAD~1 Time (mean ± σ): 2.914 s ± 0.062 s [User: 2.449 s, System: 0.489 s] Range (min … max): 2.834 s … 3.020 s 10 runs Benchmark 2: make -C Documentation -j1 lint-docs' in 'HEAD~0 Time (mean ± σ): 2.315 s ± 0.062 s [User: 1.950 s, System: 0.386 s] Range (min … max): 2.229 s … 2.397 s 10 runs Summary 'make -C Documentation -j1 lint-docs' in 'HEAD~0' ran 1.26 ± 0.04 times faster than 'make -C Documentation -j1 lint-docs' in 'HEAD~1' So let's use that pattern both for the "lint-docs" target, and a few miscellaneous other targets. This method of creating parent directories is explicitly racy in that we don't know if we're going to say always create a "foo" followed by a "foo/bar" under parallelism, or skip the "foo" because we created "foo/bar" first. In this case it doesn't matter for anything except that we aren't guaranteed to get the same number of rules firing when running make in parallel. 1. https://lore.kernel.org/git/211028.861r45y3pt.gmgdl@evledraar.gmail.com/ 2. https://lore.kernel.org/git/211028.86o879vvtp.gmgdl@evledraar.gmail.com/ 3. https://gitlab.com/avar/git-hyperfine/ Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Ævar Arnfjörð Bjarmason	a9fda017f4	Makefile: add "$(QUIET)" boilerplate to shared.mak The $(QUIET) variables we define are largely duplicated between our various Makefiles, let's define them in the new "shared.mak" instead. Since we're not using the environment to pass these around we don't need to export the "QUIET_GEN" and "QUIET_BUILT_IN" variables anymore. The "QUIET_GEN" variable is used in "git-gui/Makefile" and "gitweb/Makefile", but they've got their own definition for those. The "QUIET_BUILT_IN" variable is only used in the top-level "Makefile". We still need to export the "V" variable. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Ævar Arnfjörð Bjarmason	8df786d298	Makefiles: add "shared.mak", move ".DELETE_ON_ERROR" to it We have various behavior that's shared across our Makefiles, or that really should be (e.g. via defined templates). Let's create a top-level "shared.mak" to house those sorts of things, and start by adding the ".DELETE_ON_ERROR" flag to it. See my own `7b76d6bf22` (Makefile: add and use the ".DELETE_ON_ERROR" flag, 2021-06-29) and `db10fc6c09` (doc: simplify Makefile using .DELETE_ON_ERROR, 2021-05-21) for the addition and use of the ".DELETE_ON_ERROR" flag. I.e. this changes the behavior of existing rules in the altered Makefiles (except "Makefile" & "Documentation/Makefile"). I'm confident that this is safe having read the relevant rules in those Makfiles, and as the GNU make manual notes that it isn't the default behavior is out of an abundance of backwards compatibility caution. From edition 0.75 of its manual, covering GNU make 4.3: [Enabling '.DELETE_ON_ERROR' is] almost always what you want 'make' to do, but it is not historical practice; so for compatibility, you must explicitly request it. This doesn't introduce a bug by e.g. having this ".DELETE_ON_ERROR" flag only apply to this new shared.mak, Makefiles have no such scoping semantics. It does increase the danger that any Makefile without an explicit "The default target of this Makefile is..." snippet to define the default target as "all" could have its default rule changed if our new shared.mak ever defines a "real" rule. In subsequent commits we'll be careful not to do that, and such breakage would be obvious e.g. in the case of "make -C t". We might want to make that less fragile still (e.g. by using ".DEFAULT_GOAL" as noted in the preceding commit), but for now let's simply include "shared.mak" without adding that boilerplate to all the Makefiles that don't have it already. Most of those are already exposed to that potential caveat e.g. due to including "config.mak*". Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Jeff King	4c64fb5aad	Documentation/Makefile: fix lint-docs mkdir dependency 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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Ævar Arnfjörð Bjarmason	8650c6298c	doc lint: make "lint-docs" non-.PHONY Speed up the "lint-docs" target by making it non-.PHONY. Similar to my `c234e8a0ec` (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 `db10fc6c09` (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 <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Ævar Arnfjörð Bjarmason	8cc804d0ab	doc build: speed up "make lint-docs" Extend the trick we use to speed up the "clean" target to also extend to the "lint-docs" target. See `54df87555b` (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 <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Ævar Arnfjörð Bjarmason	7e19e2efa9	doc lint: fix error-hiding regression Fix the broken "make lint-docs" (or "make check-docs" at the top-level) target, which has been broken since my `cafd9828e8` (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 <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Todd Zullinger	6e4fd8bfcd	doc: add bundle-format to TECH_DOCS 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 <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	3 years ago
Felipe Contreras	7ba3016729	doc: avoid using rm directly That's what we have $(RM) for. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Felipe Contreras	db10fc6c09	doc: simplify Makefile using .DELETE_ON_ERROR 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 <avarab@gmail.com> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Felipe Contreras	471e7b2cf6	doc: remove unnecessary rm instances Commits `50cff52f1a` (When generating manpages, delete outdated targets first., 2007-08-02) and `f9286765b2` (Documentation/Makefile: remove cmd-list.made before redirecting to it., 2007-08-06) created these rm instances for a very rare corner-case: building as root by mistake. It's odd to have workarounds here, but nowhere else in the Makefile-- which already fails in this stuation, starting from Documentation/technical/. We gain nothing but complexity, so let's remove them. Comments-by: Jeff King <peff@peff.net> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Felipe Contreras	56da21392b	doc: improve asciidoc dependencies asciidoc needs asciidoc.conf, asciidoctor asciidoctor-extensions.rb. Neither needs the other. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Felipe Contreras	12d078ed2b	doc: refactor common asciidoc dependencies Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Matheus Tavares	68e66f2987	parallel-checkout: add design documentation Co-authored-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Ævar Arnfjörð Bjarmason	ea8b9271b1	doc lint: lint relative section order Add a linting script to check the relative order of the sections in the documentation. We should have NAME, then SYNOPSIS, DESCRIPTION, OPTIONS etc. in that order. That holds true throughout our documentation, except for a few exceptions which are hardcoded in the linting script. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Ævar Arnfjörð Bjarmason	cafd9828e8	doc lint: lint and fix missing "GIT" end sections Lint for and fix the three manual pages that were missing the standard "Part of the linkgit:git[1] suite" end section. We only do this for the man[157] section documents (we don't have anything outside those sections), not files to be included, howto *.txt files etc. We could also add this to the existing (and then renamed) lint-gitlink.perl, but I'm not doing that here. Obviously all of that fits in one script, but I think for something like this that's a one-off script with global variables it's much harder to follow when a large part of your script is some if/else or keeping/resetting of state simply to work around the script doing two things instead of one. Especially because in this case this script wants to process the file as one big string, but lint-gitlink.perl wants to look at it one line at a time. We could also consolidate this whole thing and t/check-non-portable-shell.pl, but that one likes to join lines as part of its shell parsing. So let's just add another script, whole scaffolding is basically: use strict; use warnings; sub report { ... } my $code = 0; while (<>) { ... } exit $code; We'd spend more lines effort trying to consolidate them than just copying that around. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Ævar Arnfjörð Bjarmason	d2c9908076	doc lint: fix bugs in, simplify and improve lint script The lint-gitlink.perl script added in `ab81411ced` (ci: validate "linkgit:" in documentation, 2016-05-04) was more complex than it needed to be. It: - Was using File::Find to recursively find .txt files in Documentation/, let's instead use the Makefile as a source of truth for .txt files, and pass it down to the script. - We now don't lint linkgit:* in RelNotes/* or technical/, which we shouldn't have been doing in the first place anyway. - When the doc-diff script was added in `beb188e22a` (add a script to diff rendered documentation, 2018-08-06) we started sometimes having a "git worktree" under Documentation/. This tree contains a full checkout of git.git, as a result the "lint" script would recurse into that, and lint any .txt file found in that entire repository. In practice the only in-tree "linkgit" outside of the Documentation/ tree is contrib/contacts/git-contacts.txt and contrib/subtree/git-subtree.txt, so this wouldn't emit any errors Now we instead simply trust the Makefile to give us *.txt files. Since the Makefile also knows what sections each page should be in we don't have to open the files ourselves and try to parse that out. As a bonus this will also catch bugs with the section line in the files themselves being incorrect. The structure of the new script is mostly based on t/check-non-portable-shell.pl. As an added bonus it will also use pos() to print where the problems it finds are, e.g. given an issue like: diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt [...] and line numbers. git-cherry therefore detects when commits have been -"copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or -linkgit:git-rebase[1]. +"copied" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3] or +linkgit:git-rebase[4]. We'll now emit: git-cherry.txt:20: error: git-cherry-pick[2]: wrong section (should be 1), shown with 'HERE' below: git-cherry.txt:20: '"copied" by means of linkgit:git-cherry-pick[2]' <-- HERE git-cherry.txt:20: error: git-am[3]: wrong section (should be 1), shown with 'HERE' below: git-cherry.txt:20: '"copied" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE git-cherry.txt:21: error: git-rebase[4]: wrong section (should be 1), shown with 'HERE' below: git-cherry.txt:21: 'linkgit:git-rebase[4]' <-- HERE Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Ævar Arnfjörð Bjarmason	19bcc73e70	Documentation/Makefile: make doc.dep dependencies a variable again Re-introduce a variable to declare what .txt files need to be considered for the purposes of scouring files to generate a dependency graph of includes. When doc.dep was introduced in `a5ae8e64cf` (Fix documentation dependency generation., 2005-11-07) we had such a variable called TEXTFILES, but it was refactored away just a few commits after that in `fb612d54c1` (Documentation: fix dependency generation., 2005-11-07). I'm planning to add more wildcards here, so let's bring it back. I'm not calling it TEXTFILES because we e.g. don't consider Documentation/technical/.txt when generating the graph (they don't use includes). Let's instead call it DOC_DEP_TXT. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Ævar Arnfjörð Bjarmason	824c621b76	Documentation/Makefile: make $(wildcard howto/.txt) a var Refactor occurrences of $(wildcard howto/.txt) into a single HOWTO_TXT variable for readability and consistency. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Johannes Schindelin	09420b7648	Document how we do embargoed releases Whenever we fix critical vulnerabilities, we follow some sort of protocol (e.g. setting a coordinated release date, keeping the fix under embargo until that time, coordinating with packagers and/or hosting sites, etc). Similar in spirit to `Documentation/howto/maintain-git.txt`, let's formalize the details in a document. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Ævar Arnfjörð Bjarmason	42957af027	mailmap doc: create a new "gitmailmap(5)" man page Create a gitmailmap(5) page similar to how .gitmodules and .gitignore have their own pages at gitmodules(5) and gitignore(5). Now instead of "check-mailmap", "blame" and "shortlog" documentation including the description of the format we link to one canonical place. This makes things easier for readers, since in our manpage or web-based[1] output it's not clear that the "MAPPING AUTHORS" sections aren't subtly different, as opposed to just included. 1. https://git-scm.com/docs/git-check-mailmap Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Ramsay Jones	7a9272a836	Documentation/Makefile: conditionally include ../GIT-VERSION-FILE The 'clean' target is still noticeably slow on cygwin, despite the substantial improvement made by the previous patch. For example, the second invocation of 'make clean' below: $ make clean >/dev/null 2>&1 $ make clean ... make[1]: Entering directory '/home/ramsay/git/Documentation' make[2]: Entering directory '/home/ramsay/git' make[2]: 'GIT-VERSION-FILE' is up to date. make[2]: Leaving directory '/home/ramsay/git' ... $ has been timed at 12.364s on my laptop (an old core i5-4200M @ 2.50GHz, 8GB RAM, 1TB HDD). Notice that the 'clean' target is making a nested call to the parent Makefile to ensure that the GIT-VERSION-FILE is up-to-date (prior to the previous patch, there would have been _two_ such invocations). This is to ensure that the $(GIT_VERSION) make variable is set, once that file had been included. However, the 'clean' target does not use the $(GIT_VERSION) variable, directly or indirectly, so it does not have any affect on what the target removes. Therefore, the time spent on ensuring an up to date GIT-VERSION-FILE is wasted effort. In order to eliminate such wasted effort, use the value of the internal $(MAKECMDGOALS) variable to only '-include ../GIT-VERSION-FILE' when the target is not 'clean'. (This drops the time down to 10.361s, on my laptop, giving an improvement of 16.20%). Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Ramsay Jones	54df87555b	Documentation/Makefile: conditionally include doc.dep The 'clean' target is noticeably slow on cygwin, even for a 'do-nothing' invocation of 'make clean'. For example, the second 'make clean' below: $ make clean >/dev/null 2>&1 $ make clean GIT_VERSION = 2.29.0 ... make[1]: Entering directory '/home/ramsay/git/Documentation' GEN mergetools-list.made GEN cmd-list.made GEN doc.dep ... $ has been timed at 23.339s, using git v2.29.0, on my laptop (an old core i5-4200M @ 2.50GHz, 8GB RAM, 1TB HDD). Notice that, since the 'doc.dep' file does not exist, make takes the time (about 8s) to generate several files in order to create the doc.dep include file. (If an 'include' file is missing, but a target for the said file is present in the Makefile, make will execute that target and, if that file now exists, throw away all its internal data and re-read and re-parse the Makefile). Having spent the time to include the 'doc.dep' file, the 'clean' target immediately deletes those files. The document dependencies specified in the 'doc.dep' include file, expressed as make targets and prerequisites, do not affect what the 'clean' target removes. Therefore, the time spent in generating the dependencies is completely wasted effort. In order to eliminate such wasted effort, use the value of the internal $(MAKECMDGOALS) variable to only '-include doc.dep' when the target is not 'clean'. (This drops the time down to 12.364s, on my laptop, giving an improvement of 47.02%). Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Arnout Engelen	3569e11d69	doc: make HTML manual reproducible Versions of docbook-xsl newer than 1.79.1 allows xsltproc to assign IDs to nodes in the generated HTML consistently, to make the output resulting from the same source stable and reproducible. Pass the generate.consistent.ids parameter from the command line to ask for this feature. Older versions of the tool simply ignores the parameter and produces their output the same way as before this change, so there is no need to check for toolchain version. Signed-off-by: Arnout Engelen <arnout@bzzt.net> Helped-by: brian m. carlson <sandals@crustytoothpaste.net> Helped-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	4 years ago
Philippe Blain	f442f28a81	git.txt: add list of guides Not all man5/man7 guides are mentioned in the 'git(1)' documentation, which makes the missing ones somewhat hard to find. Add a list of the guides to git(1) by leveraging the existing `Documentation/cmd-list.perl` script to generate a file `cmds-guide.txt` which gets included in git.txt. Also, do not hard-code the manual section '1'. Instead, use a regex so that the manual section is discovered from the first line of each `git*.txt` file. This addition was hinted at in `1b81d8cb19` (help: use command-list.txt for the source of guides, 2018-05-20). Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Junio C Hamano	e7a9807a62	Documentation: don't hardcode command categories twice Instead of hard-coding the list of command categories in both `Documentation/Makefile` and `Documentation/cmd-list.perl`, make the Makefile the authoritative source and tweak `cmd-list.perl` so that it receives the list of command categories as argument. Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Philippe Blain	2135e1ad70	command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers' The guides 'gitcredentials' and 'gitremote-helpers' do not currently appear in command-list.txt. 'gitcredentials' was forgotten back when guides were added to command-list.txt in `1b81d8cb19` (help: use command-list.txt for the source of guides, 2018-05-20). 'gitremote-helpers' was moved to section 7 in `439cc74632` (docs: move gitremote-helpers into section 7, 2019-03-25), but command-list.txt was not updated at the time. Add these two guides to the list of guides in 'command-list.txt', so that they appear in the output of 'git help --guides', and capitalize the first word of the description of 'gitcredentials', as was done in `1b81d8c` (help: use command-list.txt for the source of guides, 2018-05-20) for the other guides. While at it, add a comment in Documentation/Makefile to remind developers to update command-list.txt if they add a new guide. Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Jonathan Nieder	35e6c47404	reftable: file format documentation Shawn Pearce explains: Some repositories contain a lot of references (e.g. android at 866k, rails at 31k). The reftable format provides: - Near constant time lookup for any single reference, even when the repository is cold and not in process or kernel cache. - Near constant time verification if a SHA-1 is referred to by at least one reference (for allow-tip-sha1-in-want). - Efficient lookup of an entire namespace, such as `refs/tags/`. - Support atomic push `O(size_of_update)` operations. - Combine reflog storage with ref storage. This file format spec was originally written in July, 2017 by Shawn Pearce. Some refinements since then were made by Shawn and by Han-Wen Nienhuys based on experiences implementing and experimenting with the format. (All of this was in the context of our work at Google and Google is happy to contribute the result to the Git project.) Imported from JGit[1]'s current version (c217d33ff, "Documentation/technical/reftable: improve repo layout", 2020-02-04) of Documentation/technical/reftable.md and converted to asciidoc by running pandoc -t asciidoc -f markdown reftable.md >reftable.txt using pandoc 2.2.1. The result required the following additional minor changes: - removed the [TOC] directive to add a table of contents, since asciidoc does not support it - replaced git-scm.com/docs links with linkgit: directives that link to other pages within Git's documentation [1] https://eclipse.googlesource.com/jgit/jgit Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
brian m. carlson	2149b6748f	docs: add a FAQ Git is an enormously flexible and powerful piece of software. However, it can be intimidating for many users and there are a set of common questions that users often ask. While we already have some new user documentation, it's worth adding a FAQ to address common questions that users often have. Even though some of this is addressed elsewhere in the documentation, experience has shown that it is difficult for users to find, so a centralized location is helpful. Add such a FAQ and fill it with some common questions and answers. While there are few entries now, we can expand it in the future to cover more things as we find new questions that users have. Let's also add section markers so that people answering questions can directly link users to the proper answer. The FAQ also addresses common configuration questions that apply not only to Git as an independent piece of software but also the ecosystem of CI tools and hosting providers that people use, since these are the source of common questions. An attempt has been made to avoid mentioning any particular provider or tool, but to nevertheless cover common configurations that apply to a wide variety of such tools. Note that the long lines for certain questions are required, since Asciidoctor does not permit broken lines there. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Martin Ågren	388f5b52b0	Doc: drop support for docbook-xsl before 1.73.0 Drop the DOCBOOK_XSL_172 config knob, which was needed with docbook-xsl 1.72 (but neither 1.71 nor 1.73). Version 1.73.0 is more than twelve years old. Together with the last few commits, we are now at a point where we don't have any Makefile knobs to cater to old/broken versions of docbook-xsl. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Martin Ågren	40b970078b	Doc: drop support for docbook-xsl before 1.72.0 docbook-xsl 1.72.0 is thirteen years old. Drop the ASCIIDOC_ROFF knob which was needed to support 1.68.1 - 1.71.1. The next commit will increase the required/assumed version further. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Martin Ågren	def3ce00ae	Doc: drop support for docbook-xsl before 1.71.1 Drop the DOCBOOK_SUPPRESS_SP mechanism, which needs to be used with docbook-xsl versions 1.69.1 through 1.71.0. We probably broke this for Asciidoctor builds in `f6461b82b9` ("Documentation: fix build with Asciidoctor 2", 2019-09-15). That is, we should/could fix this similar to `55aca515eb` ("manpage-bold-literal.xsl: match for namespaced "d:literal" in template", 2019-10-31). But rather than digging out such an old version of docbook-xsl to test that, let's just use this as an excuse for dropping this decade-old workaround. DOCBOOK_SUPPRESS_SP was not needed with docbook-xsl 1.69.0 and older. Maybe such old versions still work fine on our docs, or maybe not. Let's just refer to everything before 1.71.1 as "not supported". The next commit will increase the required/assumed version further. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Emily Shaffer	e0479fa073	documentation: add tutorial for object walking Existing documentation on object walks seems to be primarily intended as a reference for those already familiar with the procedure. This tutorial attempts to give an entry-level guide to a couple of bare-bones object walks so that new Git contributors can learn the concepts without having to wade through options parsing or special casing. The target audience is a Git contributor who is just getting started with the concept of object walking. The goal is to prepare this contributor to be able to understand and modify existing commands which perform revision walks more easily, although it will also prepare contributors to create new commands which perform walks. The tutorial covers a basic overview of the structs involved during object walk, setting up a basic commit walk, setting up a basic all-object walk, and adding some configuration changes to both walk types. It intentionally does not cover how to create new commands or search for options from the command line or gitconfigs. There is an associated patchset at https://github.com/nasamuffin/git/tree/revwalk that contains a reference implementation of the code generated by this tutorial. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Martin Ågren	226daba280	Doc/Makefile: give mansource/-version/-manual attributes Rather than hardcoding "Git Manual" and "Git" as the manual and source in asciidoc.conf, provide them as attributes `manmanual` and `mansource`. Rename the `git_version` attribute to `manversion`. These new attribute names are not arbitrary, see, e.g., [1]. For AsciiDoc (8.6.10) and Asciidoctor <1.5.7, this is a no-op. Starting with Asciidoctor 1.5.7, `manmanual` and `mansource` actually end up in the xml-files and eventually in the rendered manpages. In particular, the manpage headers now render just as with AsciiDoc. No versions of Asciidoctor pick up the `manversion` [2], and older versions don't pick up any of these attributes. -- We'll fix that with a bit of a hack in the next commit. [1] https://asciidoctor.org/docs/user-manual/#man-pages [2] Note how [1] says "Not used by Asciidoctor". Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
brian m. carlson	f6461b82b9	Documentation: fix build with Asciidoctor 2 Our documentation toolchain has traditionally been built around DocBook 4.5. This version of DocBook is the last DTD-based version of DocBook. In 2009, DocBook 5 was introduced using namespaces and its syntax is expressed in RELAX NG, which is more expressive and allows a wider variety of syntax forms. Asciidoctor, one of the alternatives for building our documentation, moved support for DocBook 4.5 out of core in its recent 2.0 release and now only supports DocBook 5 in the main release. The DocBoook 4.5 converter is still available as a separate component, but this is not available in most distro packages. This would not be a problem but for the fact that we use xmlto, which is still stuck in the DocBook 4.5 era. xmlto performs DTD validation as part of the build process. This is not problematic for DocBook 4.5, which has a valid DTD, but it clearly cannot work for DocBook 5, since no DTD can adequately express its full syntax. In addition, even if xmlto did support RELAX NG validation, that wouldn't be sufficient because it uses the libxml2-based xmllint to do so, which has known problems with validating interleaves in RELAX NG. Fortunately, there's an easy way forward: ask Asciidoctor to use its DocBook 5 backend and tell xmlto to skip validation. Asciidoctor has supported DocBook 5 since v0.1.4 in 2013 and xmlto has supported skipping validation for probably longer than that. We also need to teach xmlto how to use the namespaced DocBook XSLT stylesheets instead of the non-namespaced ones it usually uses. Normally these stylesheets are interchangeable, but the non-namespaced ones have a bug that causes them not to strip whitespace automatically from certain elements when namespaces are in use. This results in additional whitespace at the beginning of list elements, which is jarring and unsightly. We can do this by passing a custom stylesheet with the -x option that simply imports the namespaced stylesheets via a URL. Any system with support for XML catalogs will automatically look this URL up and reference a local copy instead without us having to know where this local copy is located. We know that anyone using xmlto will already have catalogs set up properly since the DocBook 4.5 DTD used during validation is also looked up via catalogs. All major Linux distributions distribute the necessary stylesheets and have built-in catalog support, and Homebrew does as well, albeit with a requirement to set an environment variable to enable catalog support. On the off chance that someone lacks support for catalogs, it is possible for xmlto (via xmllint) to download the stylesheets from the URLs in question, although this will likely perform poorly enough to attract attention. People still have the option of using the prebuilt documentation that we ship, so happily this should not be an impediment. Finally, we need to filter out some messages from other stylesheets that occur when invoking dblatex in the CI job. This tool strips namespaces much like the unnamespaced DocBook stylesheets and prints similar messages. If we permit these messages to be printed to standard error, our documentation CI job will fail because we check standard error for unexpected output. Due to dblatex's reliance on Python 2, we may need to revisit its use in the future, in which case this problem may go away, but this can be delayed until a future patch. The final message we filter is due to libxslt on modern Debian and Ubuntu. The patch which they use to implement reproducible ID generation also prints messages about the ID generation. While this doesn't affect our current CI images since they use Ubuntu 16.04 which lacks this patch, if we upgrade to Ubuntu 18.04 or a modern Debian, these messages will appear and, like the above messages, cause a CI failure. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>	5 years ago
Emily Shaffer	76644e3268	documentation: add tutorial for first contribution This tutorial covers how to add a new command to Git and, in the process, everything from cloning git/git to getting reviewed on the mailing list. It's meant for new contributors to go through interactively, learning the techniques generally used by the git/git development community. Reviewed-by: Johannes Schindelin <johannes.schindelin@gmx.de> Reviewed-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Johannes Schindelin	faa7a096d8	docs: exclude documentation for commands that have been excluded When building with certain build options, some commands are excluded from the build. For example, `git-credential-cache` is skipped when building with `NO_UNIX_SOCKETS`. Let's not build or package documentation for those excluded commands. This issue was pointed out rightfully when running `make check-docs` on Windows, where we do not yet have Unix sockets, and therefore the `credential-cache` command is excluded (yet its documentation was built and shipped). Note: building the documentation via `make -C Documentation` leaves the build system with no way to determine which commands have been excluded. If called thusly, we gracefully fail to exclude their documentation. Only when building the documentation via the top-level Makefile will it get excluded properly, or after building `Documentation/GIT-EXCLUDED-PROGRAMS` manually. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Johannes Schindelin	439cc74632	docs: move gitremote-helpers into section 7 It is currently in section 1, but that section is intended for "Executable programs or shell commands". A more appropriate place is section 7: "Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)". This issue should have been detected earlier by `make check-docs`, but was missed due to a bug in that Makefile target (that we are about to fix). Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Martin Ågren	9a71722b4d	Doc: auto-detect changed build flags If you build the documentation switching between different options, e.g., to build with both Asciidoc and Asciidoctor, you'll probably find yourself running `make -C Documentation clean` either too often (wasting time) or too rarely (getting mixed builds). Track the flags we're using in the documentation build, similar to how the main Makefile tracks CFLAGS and prefix flags. Track ASCIIDOC_COMMON directly rather than its individual components -- that should make it harder to forget to update the tracking if/when we modify the build commands. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Martin Ågren	a15ef383e7	Documentation/Makefile: add missing dependency on asciidoctor-extensions asciidoctor-extensions.rb has never changed, but when it does -- such as in the next commit --, it helps if the xml-files depend on it. We're casting the net a bit too wide here, since we'll be rebuilding even with AsciiDoc, which won't look at this file. But since this file changes so rarely, that should be ok. It's better than missing a dependency. Similarly, most of the html-files are produced directly from ".txt'; make the html-files too depend on asciidoctor-extensions.rb, both the HTMLified manual pages as well as the user-manual that does use .xml intermediary. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Martin Ågren	c91d03aade	Documentation/Makefile: add missing xsl dependencies for manpages These stylesheets very rarely change, but when they do, it really helps if the manpages depend on them. We're casting the net a bit too wide here, since we'll only ever use a subset of the stylesheets, but since these files change so rarely, that should be ok. It's better than missing a dependency. Observe that manpage-base-url.xsl is a generated file, so we need to list it explicitly, besides the `wildcard` expression we're adding here. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Jean-Noel Avila	3d5b568f1a	Documentation/Makefile add optional targets for l10n The standard doc lists can be filtered to allow using the compilation rules with translated manpages where all the pages of the original version may not be present. The install variable are reused in the secondary repo so that the configured paths can be used for translated manpages too. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Todd Zullinger	6056817879	Documentation: build technical/multi-pack-index The git-multi-pack-index doc links to technical/multi-pack-index.html. Ensure it is built to prevent a broken link. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Nguyễn Thái Ngọc Duy	76b993afd6	Update makefile in preparation for Documentation/config/*.txt config.txt is going to be broken down in smaller pieces and put under Documentation/config directory. Update build rules to take these files into account. A dummy file is added to make sure wildcard expansion is predictable (depending on shell setting it could expand to nothing or becomes a path if config directory is empty). The file will be deleted once the move is over. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	6 years ago
Junio C Hamano	6b6547b46f	Revert "doc/Makefile: drop doc-diff worktree and temporary files on "make clean"" This reverts commit `6f924265a0`, which started to require that we have an executable git available in order to say "make clean", which gives us a chicken-and-egg problem. Having to have Git installed, or be in a repository, in order to be able to run an optional "doc-diff" tool is fine. Requiring either in order to run "make clean" is a different story. Reported by Jonathan Nieder <jrnieder@gmail.com>.	6 years ago
Eric Sunshine	6f924265a0	doc/Makefile: drop doc-diff worktree and temporary files on "make clean" doc-diff creates a temporary working tree (git-worktree) and generates a bunch of temporary files which it does not remove since they act as a cache to speed up subsequent runs. Although doc-diff's working tree and generated files are not strictly build products of the Makefile (which, itself, never runs doc-diff), as a convenience, update "make clean" to clean up doc-diff's working tree and generated files along with other development detritus normally removed by "make clean". Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>	7 years ago

1 2 3 4 5 ...

267 Commits (746aae3dd1a8e8dba31797ac237916d9533e4254)