Re: [PATCH] Allow git-config to append a comment

"Ralph Seichter via GitGitGadget" <gitgitgadget@gmail.com> writes:

Thanks for a patch.

Make sure your title will mix well in "git shortlog --no-merges" output from recent commits by other contributors. See Documentation/SubmittingPatches[[describe-changes]]. Perhaps

    Subject: [PATCH] config: add --comment option to add a comment

If you are illustrating a sample input, please also explain what output it produces. What do the resulting lines in the config file look like after you run this command?

I find the overall idea somewhat incomplete. Perhaps stepping back a bit and thinking through the _whole_ use case of "comment" in the configuration files is in order, before thinking about an easier way to add one. Why are you adding "# comment" to your config file? Who reads these comments, with what tool, and for what purpose? What will they do after they learn something from what their former selves wrote as comments?

Let's imagine we had this in our global configuration file in the beginning:

    $ cat ~/.gitconfig
	...
    [safe]
	directory = /home/bob/otherrepo.git
	...

and then we run this:

    $ git config --global --comment 'the reason why I added ~alice/
    is because ...' --add safe.directory /home/alice/somerepo.git
    $ git config --global --add safe.directory /home/charlie/somerepo.git

which may modify the configuration file with the new entry with a comment. The part about safe.directory might now read like so:

    [safe]
	directory = /home/bob/otherrepo.git
        # the reason why I added ~alice/
        # is because ...
	directory = /home/alice/somerepo.git
	directory = /home/charlie/somerepo.git

Now how do we find out about this comment? "git config -l" would not give us that. Are we expected to look at it in our editor or pager?

    $ vi ~/.gitconfig
    $ less ~/.gitconfig

Why are we interested in looking at these comments in the first place [*]?

    Side note: I do not ask "why are we interested in leaving
    these comments in the file"---it goes without saying that
    it is because we want to be able to later read them.

Presumably, we are trying to remind ourselves why we added a particular variable=value. By learning that, what are we going to do next? Perhaps once the reason to mark /home/alice/somerepo.git as a safe.directory disappears, we would want to remove this entry?

But then, after running

    $ less ~/.gitconfig

and then learning that we no longer need /home/alice/somerepo.git marked as a safe.directory, how would we remove it from the configuration file, and what happens to the comment?

    $ git config --global --unset safe.directory /home/alice/somerepo.git

may remove the value, but it would not remove the comment, and you'll be left with something like this:

    [safe]
	directory = /home/bob/otherrepo.git
        # the reason why I added ~alice/
        # is because ...
	directory = /home/charlie/somerepo.git

The remaining comment looks as if it talks about "charlie", but it simply is stale.

Should it have removed the comment, then? I actually do not think so. A comment before a particular variable definition may not be the result of the use of this new "config --comment" option, but perhaps the user added it manually. Or even worse, the comment may not even be about an individual entry. Imagine

    [section]
	# definitions for per-user stuff begin here
	var = /home/alice
	# these two directories are actually charlie's
	var = /home/bob
	var = /home/charlie

	# definitions for per-project stuff
	var = /project/a
	var = /project/b

Can we come up with a code that reliably decides when to remove the first comment we see above? The answer given by human might be "when all the entries about /home/alice, /home/bob, and /home/charlie get removed", but can we implement that in code without interpreting the natural language? I doubt it. We may even be better off to keep the comment to remind ourselves where to add the per-user stuff in the section when we hire a new user the next time.

With the new "--comment" thing might be able to add comments without using an editor, but the user would need to view the configuration file with a pager or an editor bypassing Git to make use of what was recorded in there. And it is likely that these comments will need to be edited or removed using an editor because "git config" command would not be usable for maintaining them. For that matter, if you made a typo in your "--comment" option from the command line, you would have to resort to your editor to fix that typo.

The above is an illustration of what I want to see the author, who comes up with this "wouldn't it be wonderful to teach git-config to add comment?" idea, thinks through. The first patch might be to just add a comment when a variable=value is added, but we want to see the vision of how the whole end-user experience should look like, in which this first small piece will fit.

Identify the whole life cycle of the result of using the feature, what the end-user experience of using the result of using the feature would look like, etc. In this case, "the result of using the feature" is the comments that are initially placed next to a newly defined variable-value pair, and at least to me, the end-user experience to manage the life cycle of these comments is not all that improved from the status quo, which is that you need your pager and editor to view them, edit them, typofix them, and remove them.

I am somewhat negative on the idea to make the initial addition of the comment vastly different from all other uses of the comment by introducing this "--comment" option. If we have a vision, if not design and/or code, to help managing other parts of the lifecycle, not just adding in the beginning, it might be a different story, but I cannot quite see it.

And the amount of the change required for that tiny bit of "improvement" (if we can call it, which is dubious) does not seem worth it.

Thanks.