[PATCH] D129563: [docs] Document git-clang-format

[Nico Weber via Phabricator via cfe-commits]

thakis created this revision.
thakis added reviewers: curdeius, MyDeveloperDay.
Herald added a project: All.
thakis requested review of this revision.

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.


https://reviews.llvm.org/D129563

Files:
  clang/docs/ClangFormat.rst


Index: clang/docs/ClangFormat.rst
===================================================================
--- clang/docs/ClangFormat.rst
+++ clang/docs/ClangFormat.rst
@@ -229,6 +229,59 @@
 
 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 differ
+  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 differ 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 differences 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
+    --diffstat            print a diffstat 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
 =============================


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D129563.443945.patch
Type: text/x-patch
Size: 2641 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20220712/3d18e78a/attachment-0001.bin>