[clang] 422e6e7 - [docs] Document git-clang-format

[Nico Weber via cfe-commits]

Author: Nico Weber
Date: 2022-07-13T21:06:00-04:00
New Revision: 422e6e762935b4466c2ef1871df6917ab1c31262

URL: https://github.com/llvm/llvm-project/commit/422e6e762935b4466c2ef1871df6917ab1c31262
DIFF: https://github.com/llvm/llvm-project/commit/422e6e762935b4466c2ef1871df6917ab1c31262.diff

LOG: [docs] Document git-clang-format

clang-format's documentation documented the more general clang-format-diff.py
script. Add documentation for the less general but arguably easier-to-use
git integration as well.

Differential Revision: https://reviews.llvm.org/D129563

Added: 
    

Modified: 
    clang/docs/ClangFormat.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/ClangFormat.rst b/clang/docs/ClangFormat.rst
index 150f0aa009e9..3059355c03b1 100644
--- a/clang/docs/ClangFormat.rst
+++ b/clang/docs/ClangFormat.rst
@@ -229,6 +229,59 @@ Visual Studio Code Integration
 
 Get the latest Visual Studio Code extension from the `Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`_. The default key-binding is Alt-Shift-F.
 
+Git integration
+===============
+
+The script `clang/tools/clang-format/git-clang-format` can be used to
+format just the lines touched in git commits:
+
+.. code-block:: console
+
+  % git clang-format -h
+  usage: git clang-format [OPTIONS] [<commit>] [<commit>|--staged] [--] [<file>...]
+
+  If zero or one commits are given, run clang-format on all lines that 
diff er
+  between the working directory and <commit>, which defaults to HEAD.  Changes are
+  only applied to the working directory, or in the stage/index.
+
+  Examples:
+    To format staged changes, i.e everything that's been `git add`ed:
+      git clang-format
+
+    To also format everything touched in the most recent commit:
+      git clang-format HEAD~1
+
+    If you're on a branch off main, to format everything touched on your branch:
+      git clang-format main
+
+  If two commits are given (requires --
diff ), run clang-format on all lines in the
+  second <commit> that 
diff er from the first <commit>.
+
+  The following git-config settings set the default of the corresponding option:
+    clangFormat.binary
+    clangFormat.commit
+    clangFormat.extensions
+    clangFormat.style
+
+  positional arguments:
+    <commit>              revision from which to compute the 
diff 
+    <file>...             if specified, only consider 
diff erences in these files
+
+  optional arguments:
+    -h, --help            show this help message and exit
+    --binary BINARY       path to clang-format
+    --commit COMMIT       default commit to use if none is specified
+    --
diff                 print a 
diff  instead of applying the changes
+    --
diff stat            print a 
diff stat instead of applying the changes
+    --extensions EXTENSIONS
+                          comma-separated list of file extensions to format, excluding the period and case-insensitive
+    -f, --force           allow changes to unstaged files
+    -p, --patch           select hunks interactively
+    -q, --quiet           print less information
+    --staged, --cached    format lines in the stage instead of the working dir
+    --style STYLE         passed to clang-format
+    -v, --verbose         print extra information
+
 
 Script for patch reformatting
 =============================