git/Documentation/doc-diff, branch jch

doc-diff: drop SOURCE_DATE_EPOCH override

2023-05-05T21:28:03Z

The original doc-diff script set SOURCE_DATE_EPOCH to make asciidoc's output deterministic. Otherwise, the mtime of the source files would end up in the footer of the manpage, causing noisy and uninteresting diff hunks. But this has been unused since 28fde3a1f4 (doc: set actual revdate for manpages, 2023-04-13), as the footer uses the externally-specified GIT_DATE instead (that needs to be set consistently, too, which it now is as of the previous commit). Asciidoc sets several automatic attributes based on the mtime (or manual epoch), so it's still possible to write a document that would need SOURCE_DATE_EPOCH set to be deterministic. But if we wrote such a thing, it's probably a mistake, and we're better off having doc-diff loudly show it. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

doc: doc-diff: specify date

2023-05-05T01:16:29Z

Earlier we changed the manual page formatting machinery to use the dates from the commit the documentation source was taken from, instead of the date the manual page was produced. When "doc-diff" compares two commits from different dates, the different dates from the two commits would result in unnecessary differences in the output because of the change. Compensate by setting a fixed date when "doc-diff" formats the pages to be compared to work around this issue. Signed-off-by: Felipe Contreras Signed-off-by: Junio C Hamano

doc-diff: use single-colon rule in rendering Makefile

2020-02-18T21:53:30Z

When rendering the troff manpages to text via "man", we create an ad-hoc Makefile and feed it to "make". The purpose here is two-fold: - reuse results from a prior interrupted render of the same tree - use make's -j option to build in parallel But the second part doesn't seem to work (at least with my version of GNU make, 4.2.1). It just runs one render at a time. We use a double-colon "all" rule for each file, like: all:: foo foo: ...actual render recipe... all:: bar bar: ...actual render recipe... ...and so on... And it's this double-colon that seems to inhibit the parallelism. We can just switch to a regular single-colon rule. Even though we do have multiple rules for "all" here, we don't have any recipe to execute for "all" (we only care about triggering its dependencies), so the distinction is irrelevant. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

doc-diff: replace --cut-header-footer with --cut-footer

2019-09-16T19:27:38Z

After the previous commit, AsciiDoc and Asciidoctor render the manpage headers identically, so we no longer need the "cut the header" part of our `--cut-header-footer` option. We do still need the "cut the footer" part, though. The previous commits improved the rendering of the footer in Asciidoctor by quite a bit, but the two programs still disagree on how to format the date in the footer: 01/01/1970 vs 1970-01-01. We could keep using `--cut-header-footer`, but it would be nice if we had a slightly smaller hammer `--cut-footer` that would be less likely to hide regressions. Rather than simply adding such an option, let's also drop `--cut-header-footer`, i.e., rework it to lose the "header" part of its name and functionality. `--cut-header-footer` is just a developer tool and it probably has no more than a handful of users, so we can afford to be aggressive. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

doc-diff: add `--cut-header-footer`

2019-03-18T06:54:17Z

AsciiDoc and Asciidoctor do not agree on what to write in the header and footer of each man-page, i.e., the very first and the very last line of *.[157]. Those differences can certainly be interesting in their own right, but they clutter the output of `./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD` quite a bit since the diff contains some 10-15 lines of noise per file diffed. Teach doc-diff to cut away the first two and last two lines, i.e., the header/footer and the empty line immediately following/preceding it. Because Asciidoctor uses an extra empty line compared to AsciiDoc, remove one more line at each end of the file, but only if it's empty. An alternative approach might be to pass down `--no-header-footer`, which both AsciiDoc and Asciidoctor understand, but it has some drawbacks. First of all, the result doesn't build -- `xmlto` stumbles on the resulting xml since it has multiple root elements. Second, it cuts too much -- dropping the header loses the synopsis, which would be interesting to diff. Like in the previous commit, encode this option into the directory name of the "installed" and "rendered" files. Otherwise, we wouldn't be able to trust that what we use out of that cache actually corresponds to the options given for this run. (We could optimize this caching a little since this flag doesn't affect the contents of "installed" at all, but let's punt on that.) Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

doc-diff: support diffing from/to AsciiDoc(tor)

2019-03-18T06:54:17Z

Provide `--from-asciidoctor` and `--to-asciidoctor` to select that the "from" resp. "to" commit should be built with Asciidoctor, and provide an `--asciidoctor` shortcut for giving both. Similarly, provide --{from-,to-,}asciidoc for explicitly selecting AsciiDoc. Implement this using the USE_ASCIIDOCTOR flag. Let's not enforce a default here, but instead just let the Makefile fall back on whatever is in config.mak, so that `./doc-diff foo bar` without any of of these new options behaves exactly like it did before this commit. Encode the choice into the directory names of our "installed" and "rendered" files, so that we can run `./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD` without our two runs stomping on each other. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

doc-diff: let `render_tree()` take an explicit directory name

2019-03-18T06:54:17Z

In `render_tree()`, `$1` is documented to be the commit-ish/oid and we use it as that with `git checkout`, but we mostly use it to form the name of various directories. To separate these concerns, and because we are about to construct the directory names a bit differently, take two distinct arguments instead. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

Merge branch 'ma/doc-diff-usage-fix'

2019-02-07T06:05:30Z

Running "Documentation/doc-diff x" from anywhere other than the top-level of the working tree did not show the usage string correctly, which has been fixed. * ma/doc-diff-usage-fix: doc-diff: don't `cd_to_toplevel`

doc-diff: don't `cd_to_toplevel`

2019-02-04T21:12:37Z

`usage` tries to call $0, which might very well be "./doc-diff", so if we `cd_to_toplevel` before calling `usage`, we'll end with an error to the effect of "./doc-diff: not found" rather than a friendly `doc-diff -h` output. This regressed in ad51743007 ("doc-diff: add --clean mode to remove temporary working gunk", 2018-08-31) where we moved the call to `cd_to_toplevel` to much earlier. A general fix might be to teach git-sh-setup to save away the absolute path for $0 and then use that, instead. I'm not aware of any portable way of doing that, see, e.g., d2addc3b96 ("t7800: readlink may not be available", 2016-05-31). An early version of this patch moved `cd_to_toplevel` back to where it was before ad51743007 and taught the "--clean" code to cd on its own. But let's try instead to get rid of the cd-ing entirely. We don't really need it and we can work with absolute paths instead. There's just one use of $PWD that we need to adjust by simply dropping it. Suggested-by: Jeff King Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

Merge branch 'es/worktree-forced-ops-fix'

2018-09-17T20:53:59Z

Fix a bug in which the same path could be registered under multiple worktree entries if the path was missing (for instance, was removed manually). Also, as a convenience, expand the number of cases in which --force is applicable. * es/worktree-forced-ops-fix: doc-diff: force worktree add worktree: delete .git/worktrees if empty after 'remove' worktree: teach 'remove' to override lock when --force given twice worktree: teach 'move' to override lock when --force given twice worktree: teach 'add' to respect --force for registered but missing path worktree: disallow adding same path multiple times worktree: prepare for more checks of whether path can become worktree worktree: generalize delete_git_dir() to reduce code duplication worktree: move delete_git_dir() earlier in file for upcoming new callers worktree: don't die() in library function find_worktree()