Issue #660 - Add documentation for git clang-format (#685)

README.adoc

@@ -119,6 +119,13 @@ $ dnf install pre-commit
 $ pre-commit install
 ----
 
+The second command will install the pre-commit script into your `./.git/hooks/pre-commit`.
+
+Hooks are configured in `.pre-commit-config.yaml`.
+The `git clang-format` hook enforces xref:docs/notes/code-conventions.md[code-conventions] for modified C code upon `git commit`.
+Every time a user attempts a commit, clang-format is run for the staged files and if an incorrectly formatted line is detected, the commit aborts.
+The changed lines are automatically formatted during this operation, so after reviewing the changes, the user can then repeat the commit.
+
 Read this https://www.redhat.com/sysadmin/git-hooks[git hooks article] on redhat.com (as well as documentation for pre-commit) to learn more.
 
 === Description of the individual test-only dependencies

docs/notes/code-conventions.md

@@ -19,20 +19,32 @@
 
 ## C conventions
 
-Use `clang-format` to apply the styles configured in the `.clang-format` file.
+Formatting conventions are automatically enforced by a pre-commit hook and a GitHub CI job.
+See README.adoc for instructions on enabling the pre-commit hook.
 
-    $ clang-format -i <your-file>
+### Usage of `git clang-format` (per-line formatting)
 
 Use the [`git-clang-format`](https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/git-clang-format)
 script to only reformat your outstanding modified source code lines in a git repository.
 The script is likely present in your Linux distribution packages, e.g. on Fedora 36,
 
     $ dnf install git-clang-format
 
-Reformat entire repository using the following command, then analyze how much has changed
+To see incorrectly formatted changed lines on the current branch (compared to origin/main branch), run
 
-    $ clang-format -i $(git ls-files -- '*.cpp' '*.hpp' '*.c' '*.h')
-    $ git diff -w --shortstat
+    $ git clang-format origin/main --diff
+
+Leave out the `--diff` to immediately apply the changes.
+
+### Formatting tips
+
+Parameter lists can be automatically formatted either as one item per line, or binpacked (as many items per line as will fit).
+If you want to enforce your own grouping, add an empty line comment before the newline you want preserved, e.g.
+
+```c
+qd_log(qd_log_source(QD_HTTP_LOG_SOURCE), QD_LOG_ERROR,  //
+       "Unable to create http listener: %s", qd_error_message());
+```
 
 To disable automatic formatting in a particular part of your file,
 bracket it with `clang-format on` and `off` commands:
@@ -41,6 +53,19 @@ bracket it with `clang-format on` and `off` commands:
     static void* do();
     // clang-format on
 
+### Usage of `clang-format` (whole-file formatting)
+
+Use `clang-format` to apply the styles configured in the `.clang-format` file.
+
+    $ clang-format -i <your-file>
+
+Reformat entire repository using the following command, then analyze how much has changed
+
+    $ clang-format -i $(git ls-files -- '*.cpp' '*.hpp' '*.c' '*.h')
+    $ git diff -w --shortstat
+
+### Format style definition file
+
 The options available in `.clang-format` file are explained in
 <https://clang.llvm.org/docs/ClangFormatStyleOptions.html> documentation page.