[NFC] Improve doc string to mention that paths in diff are used as-is

[ctetreau]

Summary

Add --relative to the suggested git-diff one liner. If the user does not
pass this argument, then git will produce a diff with the path relative
to the repository root. If the user's working directory is not the
repository root, then clang-format will complain that the file is not
found. The --relative argument makes git produce a diff with the files
relative to the working directory.

Add note to doc string to warn users about the fact that filenames
embedded in the diff are used as-is with no attempts to "do what they
mean, not what they say"

[ctetreau]

I considered trying to find a way to work around the issue. Something like "if the file is not found, and the current directory is /foo/bar/, and the computed filename is bar/baz.c, then use /foo/bar/baz.c". But I don't think there's any way we can reliably know that such a computed file is correct, and I think it's better to error out than to silently do the wrong thing.

I think the behavior of taking the filename from the diff as-is is reasonable as long as it's documented.

[efriedma]

We should probably encourage people to use git-clang-format with git repositories. It naturally doesn't have this sort of fragility because it integrates with the repository more tightly.

clang/tools/clang-format/clang-format-diff.py

45

That isn't specific to -i. If you look more carefully at what the command is doing, it always goes back to the original source file.

[ctetreau]

address code review issues

[ctetreau]

In D79054#2018912, @efriedma wrote:

We should probably encourage people to use git-clang-format with git repositories. It naturally doesn't have this sort of fragility because it integrates with the repository more tightly.

That may be a better choice for me personally, but other version control systems exist, and this is a tool with broader appeal.

[efriedma]

LGTM

clang/tools/clang-format/clang-format-diff.py

 #!/usr/bin/env python
 #
 #===- clang-format-diff.py - ClangFormat Diff Reformatter ----*- python -*--===#
 #
 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 # See https://llvm.org/LICENSE.txt for license information.
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
 """
 This script reads input from a unified diff and reformats all the changed
 lines. This is useful to reformat all the lines touched by a specific patch.
 Example usage for git/svn users:
 
-  git diff -U0 --no-color HEAD^ | clang-format-diff.py -p1 -i
+  git diff -U0 --no-color --relative HEAD^ | clang-format-diff.py -p1 -i
   svn diff --diff-cmd=diff -x-U0 | clang-format-diff.py -i
 
+It should be noted that the filename contained in the diff is used unmodified
+to determine the source file to update. Users calling this script directly
+should be careful to ensure that the path in the diff is correct relative to the
+current working directory.
 """
 from __future__ import absolute_import, division, print_function
 
 import argparse
 import difflib
 import re
 import subprocess
 import sys
 
 if sys.version_info.major >= 3:
     from io import StringIO
 else:
     from io import BytesIO as StringIO
 
 
 def main():
   parser = argparse.ArgumentParser(description=__doc__,
                                    formatter_class=
                                            argparse.RawDescriptionHelpFormatter)
   parser.add_argument('-i', action='store_true', default=False,
                       help='apply edits to files instead of displaying a diff')
   parser.add_argument('-p', metavar='NUM', default=0,
                       help='strip the smallest prefix containing P slashes')
   parser.add_argument('-regex', metavar='PATTERN', default=None,
                       help='custom pattern selecting file paths to reformat '
                       '(case sensitive, overrides -iregex)')
   parser.add_argument('-iregex', metavar='PATTERN', default=
                       r'.*\.(cpp|cc|c\+\+|cxx|c|cl|h|hh|hpp|m|mm|inc|js|ts|proto'
                       r'|protodevel|java|cs)',
                       help='custom pattern selecting file paths to reformat '
                       '(case insensitive, overridden by -regex)')