What would be a suitable git diff hunk header for Scheme?

[Atharva Raykar]

Hi Schemers,

If you have used git, you would have noticed the diff hunks have
this format:

@@ -k,l +n,m @@ TEXT ---> this is the hunk header
+ something added
- something removed
...

With most other languages, git provides built-in diff drivers,
so if you used the diff driver for python you would get the
enclosing function or class name in the location of TEXT
above. Similarly other language drivers have important forms
shown alongside the hunk header to make the give the diff a
useful landmark.

I have been working on a patch to introduce a driver for scheme[1]
as well, but I needed some opinions from more seasoned schemers.

For now I am only taking the following forms for the hunk headers:

- `define`
- `define-syntax`
- `define-*` (any other define form that may have been introduced via macro)

Is there any other form that would make a useful landmark for hunk headers
that I should include, that will work well across most Scheme implementations?

Regards
Atharva

[1] https://public-inbox.org/git/3def82fd-71a7-3ad9...@kdbg.org/T/#m85a1cbe58b1494d0dc43601bae446563b791fa9e

[Göran Weinholt]

Atharva Raykar <rayka...@gmail.com> writes:

[...]

> For now I am only taking the following forms for the hunk headers:
>
> - `define`
> - `define-syntax`
> - `define-*` (any other define form that may have been introduced via macro)
>
> Is there any other form that would make a useful landmark for hunk
> headers that I should include, that will work well across most Scheme
> implementations?

Perhaps `library` would be nice to have (`define-library` would already
be covered by the above).

--
Göran Weinholt | https://weinholt.se/
Debian developer | 73 de SA6CJK

[Atharva Raykar]

On Tuesday, March 30, 2021 at 1:12:24 PM UTC+5:30, Göran Weinholt wrote:
> Atharva Raykar <rayka...@gmail.com> writes:
>
> [...]
> > For now I am only taking the following forms for the hunk headers:
> >
> > - `define`
> > - `define-syntax`
> > - `define-*` (any other define form that may have been introduced via macro)
> >
> > Is there any other form that would make a useful landmark for hunk
> > headers that I should include, that will work well across most Scheme
> > implementations?
> Perhaps `library` would be nice to have (`define-library` would already
> be covered by the above).

Just to be clear, in the case where a change within a `define` that is inside a
`library`, would you prefer the hunk header showing the `library` line or the
`define` line in which the change was made?

Thanks.

[Göran Weinholt]

I believe that showing the `define` would be preferable.

I've tried to think of anything else to match on, but nothing comes to
mind. Will there be an opportunity for the community to try out these
changes before they are included in git?

[Atharva Raykar]

On Tuesday, March 30, 2021 at 7:28:50 PM UTC+5:30, Göran Weinholt wrote:
> Atharva Raykar <rayka...@gmail.com> writes:
>
> > On Tuesday, March 30, 2021 at 1:12:24 PM UTC+5:30, Göran Weinholt wrote:
> >> Atharva Raykar <rayka...@gmail.com> writes:
> >>
> >> [...]
> >> > For now I am only taking the following forms for the hunk headers:
> >> >
> >> > - `define`
> >> > - `define-syntax`
> >> > - `define-*` (any other define form that may have been introduced via macro)
> >> >
> >> > Is there any other form that would make a useful landmark for hunk
> >> > headers that I should include, that will work well across most Scheme
> >> > implementations?
> >> Perhaps `library` would be nice to have (`define-library` would already
> >> be covered by the above).
> >
> > Just to be clear, in the case where a change within a `define` that is inside a
> > `library`, would you prefer the hunk header showing the `library` line or the
> > `define` line in which the change was made?
> I believe that showing the `define` would be preferable.
>
> I've tried to think of anything else to match on, but nothing comes to
> mind. Will there be an opportunity for the community to try out these
> changes before they are included in git?

Here is a way to test the same functionality, without needing a
patched version of git:

1. In your repository's `.git/config` file add the following:

[diff "scheme"]
xfuncname = "^[\t ]*(\\(define[-* \t].*)$"
wordRegex = "([^][)(}{[ \t])+"

2. Add another file in the top level of your project called `.gitattributes` with
these contents:

*.scm diff=scheme

And now if you run `git diff` over your scheme files, you should see hunk headers
show up for your project. You can tweak the xfuncname regex to try out more
constructs if it seems fit to do so.

Another thing this would add is `git diff --word-diff` will show a diff for each
individual word, and it's a little more language aware than the default word diff,
as it will ignore parentheses.

I also have my own fork of git, which will have this feature here, before it gets
added in: https://github.com/tfidfwastaken/git

I have not pushed all the changes yet, but either way I believe the first method
would be easier to do than trying to build my version of git from source just to
test this out.

--
Atharva

[Göran Weinholt]

Will this diff driver be default for *.scm? There are other file
extensions that should be added in that case, such as *.sls, *.sps,
*.sld and maybe some more. Here's a list, although not all are
applicable: <https://registry.scheme.org/#filename-extension>

> And now if you run `git diff` over your scheme files, you should see hunk headers
> show up for your project. You can tweak the xfuncname regex to try out more
> constructs if it seems fit to do so.

Adding `library` gave good results; I feel that it makes the context
clearer for changes at the top of libraries.

[Atharva Raykar]

This won't be an issue, because the patch will not hardcode the `.gitattribute` values.
So even after scheme's driver is added, it's still on the user to add the .gitattribute
file and specify which file types and directories should use the diff driver.

The documentation for this is here: https://git-scm.com/docs/gitattributes#_defining_a_custom_hunk_header

So in the builtin patterns, scheme will be added as well.

> > And now if you run `git diff` over your scheme files, you should see hunk headers
> > show up for your project. You can tweak the xfuncname regex to try out more
> > constructs if it seems fit to do so.
> Adding `library` gave good results; I feel that it makes the context
> clearer for changes at the top of libraries.

Thanks for letting me know. I will add that to the diff driver as well.

--
Atharva

[Atharva Raykar]

As of Git v2.32.0, adding diff=scheme in a .gitattributes file will make Git be smarter with the diff output for Scheme (with all of its variants) code. You can get function context around diff hunks, along with better word-diff output that is aware of Scheme keywords.

Thanks to Göran Weinholt for giving feedback on this feature before it was merged.