git/Documentation/doc-diff, branch v2.20.2

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()

doc-diff: force worktree add

2018-09-05T17:47:21Z

We avoid re-creating our temporary worktree if it's already there. But we may run into a situation where the worktree has been deleted, but an entry still exists in $GIT_DIR/worktrees. Older versions of git-worktree would annoyingly create a series of duplicate entries. Recent versions now detect and prevent this, allowing you to override with "-f". Since we know that the worktree in question was just our temporary workspace, it's safe for us to always pass "-f". Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

doc-diff: add --clean mode to remove temporary working gunk

2018-08-31T18:49:51Z

As part of its operation, doc-diff creates a bunch of temporary working files and holds onto them in order to speed up subsequent invocations. These files are never deleted. Moreover, it creates a temporary working tree (via git-wortkree) which likewise never gets removed. Without knowing the implementation details of the tool, a user may not know how to clean up manually afterward. Worse, the user may find it surprising and alarming to discover a working tree which s/he did not create explicitly. To address these issues, add a --clean mode which removes the temporary working tree and deletes all generated files. Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano

doc-diff: fix non-portable 'man' invocation

2018-08-31T18:49:49Z

doc-diff invokes 'man' with the -l option to force "local" mode, however, neither MacOS nor FreeBSD recognize this option. On those platforms, if the argument to 'man' contains a slash, it is automatically interpreted as a file specification, so a "local"-like mode is not needed. And, it turns out, 'man' which does support -l falls back to enabling -l automatically if it can't otherwise find a manual entry corresponding to the argument. Since doc-diff always passes an absolute path of the nroff source file to 'man', the -l option kicks in anyhow, despite not being specified explicitly. Therefore, make the invocation portable to the various platforms by simply dropping -l. Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano

doc-diff: always use oids inside worktree

2018-08-30T17:09:05Z

The doc-diff script immediately resolves its two endpoints to actual object ids, so that we can reuse cached results even if they appear under a different name. But we still use the original name the user fed us when running "git checkout" in our temporary worktree. This can lead to confusing results: - the namespace inside the worktree is different than the one outside. In particular, "./doc-diff origin HEAD" will resolve HEAD inside the worktree, whose detached HEAD will be pointing at origin! As a result, such a diff would always be empty. - worse, we will store this result under the oid we got by resolving HEAD in the main worktree, thus polluting our cache - we didn't pass --detach, which meant that using a branch name would cause us to actually check out that branch, making it unavailable to other worktrees. We can solve this by feeding the already-resolved object id to git-checkout. That naturally forces a detached HEAD, but just to make clear our expectation, let's explicitly pass --detach. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

SubmittingPatches: mention doc-diff

2018-08-21T19:54:33Z

We already advise people to make sure their documentation formats correctly. Let's point them at the doc-diff script, which can help with that. Let's also put a brief note in the script about its purpose, since that otherwise can only be found in the original commit message. Along with the existing -h/usage text, that's hopefully enough for developers to make use of it. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

add a script to diff rendered documentation

2018-08-06T19:30:23Z

After making a change to the documentation, it's easy to forget to check the rendered version to make sure it was formatted as you intended. And simply doing a diff between the two built versions is less trivial than you might hope: - diffing the roff or html output isn't particularly readable; what we really care about is what the end user will see - you have to tweak a few build variables to avoid spurious differences (e.g., version numbers, build times) Let's provide a script that builds and installs the manpages for two commits, renders the results using "man", and diffs the result. Since this is time-consuming, we'll also do our best to avoid repeated work, keeping intermediate results between runs. Some of this could probably be made a little less ugly if we built support into Documentation/Makefile. But by relying only on "make install-man" working, this script should work for generating a diff between any two versions, whether they include this script or not. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano