The Feature

Git has an autocorrect feature. It is not very popular and for good reason. By default, Git suggests the closest command when you try to run a command that doesn’t exist. For example, if you run git sttus, git will suggest running git status. However if you configure the help.autocorrect setting, Git can also “autocorrect” (as in run the command for you). The feature seems useful till you realize that command will be run without any user action. You can configure how long it waits before running the command but not for it to wait for user action.

This is the default git behavior:

$ git stats
git: 'stats' is not a git command. See 'git --help'.

The most similar command is
        status

If help.autocorrect is set to 10:

$ git stats
WARNING: You called a Git command named 'stats', which does not exist.
Continuing in 1.0 seconds, assuming that you meant 'status'.
On branch master
...<rest of the output>

Git waited 1 second and then ran the command. The assumption with the setting is that you will set the duration to be long enough that you are able to see the suggestion and kill the process if you don’t like the command its going to run.

Even with the configurable time delay, this feels like a risk. Sometimes you look away after running a command. Sometimes it can take longer to read and parse unexpected output from a command. You don’t want this delay to result in unexpected commands being run. Ideally you would want git to prompt you for confirmation before taking an action.

The Fix

TL;DR: You will soon be able to set help.autocorrect to prompt!

Prompting user for a confirmation seemed so obvious that I figured it must have been discussed previously. I found the Git Community documentation that linked to the IRC channel and the mailing list. I first went to the #git-devel IRC channel but unfortunately the channel was pretty quiet. Then I went to the mailing list and searched for related keywords. Since “autocorrect” setting is not discussed a lot, I quickly found a patch from 2010 that implemented this exact feature! With this patch, when help.autocorrect is set to prompt, the user is asked for confirmation before running the suggested command.

The patch looked great and it even got a review but then nothing seems to have happened. I was even able to find some historical IRC logs from 2010 discussing this feature and the patch idea. However, there was nothing explaining what went wrong or why the patch didn’t move forward.

So I decided to reach out to the patch author: David Barr. David responded saying nothing was wrong with the patch, it just got lost without follow up. So I got David’s permission to try to get a similar patch merged in now.

The Process

The existing code had some minor updates since the original patch had been created. In particular, a new “never” config had been added for this setting. Even with this, I only had to make minor changes to the original patch for the changes to work. The existing documentation for the help.autocorrect setting didn’t seem to be in the best shape. It seemed like sentences were just added on as new nuances were added to this setting. So I decided to also update the documentation to have a better structure and explain the various configurations it supports.

Honestly since I had an existing patch to work off from, generating a final patch was relatively easily. I was more worried about how to send patches on mailing lists. It’s not something I had done previously. Mailing list workflows always felt intimidating because if you make a mistake, you are annoying a whole bunch of people by publishing your mistake to their inboxes.

Fortunately, there is some excellent documentation to help. Git has a very detailed My First Contribution guide. It covers the whole workflow from cloning the git repo and making your changes to all the way sharing your patch and iterating on it over the mailing list. There is also a more “advanced” document focused just on Submitting Patches. There is also a Mentoring Google Group dedicated to helping people contribute to Git.

Submitting Patches via GitGitGadget

“My First Contribution” guide mentions GitGitGadget which is a wonderful bridge between GitHub PR and the mailing lists. It allows you to share your patch with the mailing list by creating a PR on GitHub.

This section of the guide has more detailed documentation on how to use GitGitGadget but here was my workflow:

  • Create a PR at gitgadget/git
  • Wait some time for someone to come by and permission me to use this workflow. I tried proactively finding someone on the IRC channel but didn’t get a response. This turned out to be a good thing because by the next day I was permissioned but I had also gotten some feedback on my PR. So I was able to iterate on my patch before even sending out to the mailing list.
  • Confirm all the CI is passing and make any fixes needed if not (can take 30-40 mins)
  • Subscribe to the mailing list. This was recommended to be able to respond to any feedback. You want to respond to every comment you get, even if its just to agree on the comments.
  • Add a comment to the PR saying “/submit” which will send the patch to the mailing list and it will use the top PR comment/summary as the “intro” to the email.
  • Wait for feedback. Took 2 days for me.
  • Respond to the feedback via email.
  • Repeat for new version of the changes:
    • Amend existing commits
    • Force push to the same branch to update the PR
    • Wait for CI to pass
    • Update top PR comment/summary to explain what has changed since the last version
    • Add a “/submit” comment again. This will publish a new version of your patch being shared on the mailing list.

Working with the Mailing List

How to subscribe?

You can subscribe to the Git mailing list by emailing “subscribe git” as the body to majordomo@vger.kernel.org. There is a confirmation step after that but after this you will start getting LOTS of emails.

How to manage/filter emails in GMail?

To handle the emails, I created a filter that effectively removed the mailing list emails from my inbox. Below are the steps for creating the filter.

Search for “list:(<git.vger.kernel.org>)” in the top GMail search bar. Click the “Show Search options” button in the search bar and click “Create Filter”. Here you can decide what actions to take for the emails from the mailing list. I chose “Skip the Inbox” and “Also apply filter to matching conversations” so the rest of my inbox remains clean. Then I also applied a new lable so I can look at the mailing list emails easily whenever I want to.

How to respond to an email?

Start by hitting reply-all to the email you want to respond to. Reply-all is important so you respond to the whole mailing list and not just the individual privately. Then make sure the email is sent in plain-text mode (and not HTML which is the default).

For the actual response, you don’t want to “top post” which is how most of us normally use email. You instead want to “bottom post”. This basically means that you trim the email you are responding to only have the important context. Then you want to add your response below that. If there are multiple points you are responding to, you can interleave your comments and the original email as well.

Timeline

  • Aug 7, 2021: Learned about help.autocorrect setting
  • Aug 7, 2021: Found the patch from 2010
  • Aug 7-9, 2021: Discussed with David Barr
  • Aug 9, 2021: Create PR
  • Aug 10, 2021: Submit patch to the mailing list
  • Aug 12, 2021: Recieved some comments
  • Aug 13-14, 2021: Respond and push v2 of the patch
  • Aug 15, 2021: Merge into the “seen” branch
  • Sep 10, 2021: Merge into the “next” branch
  • Sep 10, 2021: Merge into master branch
  • Nov 15, 2021: Expected git v2.34 release