Git ini files formatter

[eirnym]

Summary 💡

I'd like to see git file formatter.

Motivation 🔦

It's easy to indent it incorrectly or in non-normalized way which could obscure mistakes. Also git config format is not a simple ini file, and supports lines like "section.key= value" (e.g. filter.lfs.required=true (here I can be mistaken).

A simple formatter would satisfy basics to avoid such problems.

The gix-config module tries to read recursively, which breaks possible implementation of this feature in a third-party crate. I would like not to fork the crate to keep support consistent. If there would be a feature in this module to read "flat", I could publish the formatter

What do you think?

[Byron]

I took a look and couldn't find an existing git config file formatter.

That was a bit of a surprise, but then again I also never really wanted one, given that these files are usually fine as they are, and not edited very much.

However, I think it's totally fair for one to exist and gix-config could be providing a facility to do it. The way this would work is that it would have to process the white space around events so that when it writes them back, ordinarily, it will write them with sanitized white space.

[eirnym]

Also, which is also an important feature I expect from a formatter, it should not interpret includes. I have a nicely divided config for common and local configuration which I don't want to join

Thus, exposing a low-level interface for gix-config which just reads a file and able write this file back (or just return a string or expose a structure internals) would a be the perfect solution from my standpoint.

[ameyypawar]

I had a dig through gix-config to see how this could fit, and it seems to land quite naturally on the parser layer. Wanted to float the shape before writing anything.

The parse::Events API already exposes the full event stream (section headers, keys, values, comments, and whitespace as separate events), and parsing at that level never touches include/includeIf — those only get resolved when you build a File. So a formatter built there is flat by construction, which I think covers what Eir Nym (@eirnym) was after without needing a separate flat-read path.

Rough API:

gix_config::parse::format::normalize(input: &[u8], opts: &Options) -> Result<BString, parse::Error>

It would re-emit values, comments and section headers verbatim and only rewrite the whitespace and separator events. The default policy I had in mind, all fairly conservative:

• a single space either side of =
• one tab to indent keys under a section
• strip trailing whitespace
• ensure a single trailing newline
• leave blank lines as they are (opt-in to collapse runs of them)

with an Options so any of that can be overridden.

A couple of things I'd want your steer on before starting:

• happy with it living at parse::format, or would you prefer a File method / a different name?
• are those defaults sensible — particularly the tab indent and leaving blank lines untouched?

The one fiddly part is line continuations (\), but the parser folds the continued line's whitespace into the value itself, so as long as I only touch the standalone whitespace events those values stay intact — I'll cover it with a test regardless.

If the shape sounds right I'll put up a PR.

[eirnym]

My preferences are:

• leave it in parse::format as it wouldn't be a very often called by a programmer
• I vote for 2 spaces by default instead of a tab character (it can be rendered in anything in between 1 to 8 spaces and each editor and user has their preferences)
• add an ability to control which newlines to use
• add ability to control final newline (I prefer to have one in most cases)

Spaces vs tabs, newlines and final empty line could be controlled by user's editor config by a formatter app.

[93578237]

Would be cool to have an option to disable any indentation (no space/tabs)

[eirnym]

PS:

I'm willing to create a CLI tool when API is ready.

[ameyypawar]

Sounds good, I can go with parse::format, 2-space default indentation (configurable, including a no-indent option and newline + final-newline both configurable via Options.

also I'll get the library API (normalize + Options) and tests up so you can build on it.

happy with this shape and placement before I open the PR??

[eirnym]

I'm happy with this