Libguestfs - Dec 2021 - [libnbd PATCH] maint: Suggest better diff output for API.ml

Git diff is able to customize the regex used to locate "function
headers", or the text to output on @@ lines of a patch to make it
easier to determine which portion of a file the patch touches.  This
is done by coupling .gitattributes contents with the user running the
right 'git config' command.  We don't have a bootstrap script, so we
don't have an automated place to forcefully ensure the right setup for
new contributors, but we can at least document the steps a developer
can do to make our lives easier.

For the API.ml file, not only do we want to highlight typical
top-level OCaml 'let' statements, we also want to highlight the start
of each of our API definitions.

Thanks: Laszlo Ersek <lersek at redhat.com>
---
 .gitattributes | 3 +++
 README         | 4 ++++
 2 files changed, 7 insertions(+)
 create mode 100644 .gitattributes

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 00000000..cf630ae9
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,3 @@
+# Use the following one-time config to get nicer API diffs:
+#    git config diff.api.xfuncname '^(let .*=|  "[^"]*",
\{$)'
+API.ml diff=api
diff --git a/README b/README
index 6502e7fc..8955f817 100644
--- a/README
+++ b/README
@@ -168,6 +168,10 @@ When testing use:
     make check
     make check-valgrind

+Use the following one-time setup for nicer diffs:
+
+    git config diff.api.xfuncname '^(let .*=|  "[^"]*",
\{$)'
+
 For development ideas, see the TODO file.

 The upstream git repository is:
-- 
2.33.1

On Fri, Dec 03, 2021 at 08:35:18AM -0600, Eric Blake
wrote:
> Git diff is able to customize the regex used to locate "function
> headers", or the text to output on @@ lines of a patch to make it
> easier to determine which portion of a file the patch touches.  This
> is done by coupling .gitattributes contents with the user running the
> right 'git config' command.  We don't have a bootstrap script,
so we
> don't have an automated place to forcefully ensure the right setup for
> new contributors, but we can at least document the steps a developer
> can do to make our lives easier.
> 
> For the API.ml file, not only do we want to highlight typical
> top-level OCaml 'let' statements, we also want to highlight the
start
> of each of our API definitions.
> 
> Thanks: Laszlo Ersek <lersek at redhat.com>
> ---
>  .gitattributes | 3 +++
>  README         | 4 ++++
Hmm. Should .gitattributes be included or excluded from a tarball?
It's odd to have the tarball mention a file that does not exist if you
aren't using git, but then again, the file has no use outside of git
development.  If we do want it in the tarball, it should probably
include a copyright blurb.  For comparison, .gitignore has no
copyright blurb, but IS included in our tarball (see
Makefile.am:EXTRA_DIST).

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

On 12/03/21 15:35, Eric Blake wrote:
> Git diff is able to customize the regex used to locate "function
> headers", or the text to output on @@ lines of a patch to make it
> easier to determine which portion of a file the patch touches.  This
> is done by coupling .gitattributes contents with the user running the
> right 'git config' command.  We don't have a bootstrap script,
so we
> don't have an automated place to forcefully ensure the right setup for
> new contributors, but we can at least document the steps a developer
> can do to make our lives easier.
> 
> For the API.ml file, not only do we want to highlight typical
> top-level OCaml 'let' statements, we also want to highlight the
start
> of each of our API definitions.
> 
> Thanks: Laszlo Ersek <lersek at redhat.com>
> ---
>  .gitattributes | 3 +++
>  README         | 4 ++++
>  2 files changed, 7 insertions(+)
>  create mode 100644 .gitattributes
> 
> diff --git a/.gitattributes b/.gitattributes
> new file mode 100644
> index 00000000..cf630ae9
> --- /dev/null
> +++ b/.gitattributes
> @@ -0,0 +1,3 @@
> +# Use the following one-time config to get nicer API diffs:
> +#    git config diff.api.xfuncname '^(let .*=| 
"[^"]*", \{$)'
> +API.ml diff=api
> diff --git a/README b/README
> index 6502e7fc..8955f817 100644
> --- a/README
> +++ b/README
> @@ -168,6 +168,10 @@ When testing use:
>      make check
>      make check-valgrind
> 
> +Use the following one-time setup for nicer diffs:
> +
> +    git config diff.api.xfuncname '^(let .*=|  "[^"]*",
\{$)'
> +
>  For development ideas, see the TODO file.
> 
>  The upstream git repository is:
> 
Acked-by: Laszlo Ersek <lersek at redhat.com>

Thanks!
Laszlo