Question

I am trying to use the mailmap.file config option for git. The path is however not shell expanded, meaning I can’t write $HOME/.mailmap or ~/.mailmap. This is quite annoying if you are synchronizing your dotfiles with something like homesick and are using the same .gitconfig for Windows, OS X and Linux.

I can’t find any bugtracker for git, and I don’t want to spam the git mailinglist with something like that. How should I report this bug/minor annoyance?

Answer 1

TLDR; as mentioned in the Git mailing list:

1. Run git bugreport
2. Edit the file by filling out the blanks and removing irrelevant stuff
   (follow the instructions)
3. Post the report as an inline plaintext email to [e-mail] (again: plaintext, not HTML)

---

As mentioned in code google git-core (and by Charles Bailey in the comments, which points to git-scm community page):

Questions or comments for the Git community can be sent to the mailing list by using the email address [e-mail]. Bug reports should be sent to this mailing list.

(mailing list archive here)

Update Q2 2020, you now have an actual git bugreport command (see at the end below)

Update 2015: the latest reference remains the Git community page, which, as smoothgrips points out in the comments, mentions:

You do not need to subscribe: you will be Cc’d in replies.
Please keep the Cc list intact when replying (use "Reply to all").
Greylisting may delay your first post for a few hours.

Note that the mail server will reject HTML messages with a "failed permanently" message, so use plain text.

The community page also points out to "How to Report Bugs Effectively"…

If you want to contribute a patch, go now to rtyley/submitgit, which helps you to follow the patch submission process:

If you create a pull request on github.com/git/git/, submitGit can send it to the mailing list for you, correctly formatting the patches.
The discussion stays where it is—on the list—but at least that initial step is a little easier.

Update 2015: Git For Windows now lives on GitHub (github.com/git-for-windows), and produces very recent releases: 2.4.2+.
Msysgit is phased out, using msys2 64-bits, and resulting in git-for-windows.github.io instead of the old and now obsolete msysgit.github.io.

The GitHub mirror repo image git/git is there, but not use for issues or pull request, unfortunately.

---

Update 2019: submitGit has an alternative: GitGitGadget (gitgitgadget.github.io), mentioned in Git 2.22 (Q2 2019)

See commit c3a7dd7 (12 Mar 2019) by Jeff King (peff).
^{(Merged by Junio C Hamano — gitster — in commit 2d33728, 09 Apr 2019)}

point pull requesters to GitGitGadget

In the contributing guide and PR template seen by people who open pull requests on GitHub, we mention the submitGit tool, which gives an alternative to figuring out the mailing list.
These days we also have the similar GitGitGadget tool, and we should make it clear that this is also an option.

We could continue to mention both tools, but it’s probably better to pick one in order to avoid overwhelming the user with choice.
After all, one of the purposes here is to reduce friction for first-time or
infrequent contributors.

And there are a few reasons to prefer GGG:

1. submitGit seems to still have a few rough edges. E.g., it doesn’t munge timestamps to help threaded mail readers handled out-of-order
   delivery.
2. Subjectively, GGG seems to be more commonly used on the list these days, especially by list regulars.
3. GGG seems to be under more active development (likely related to point 2).

So let’s actually swap out submitGit for GGG.
While we’re there, let’s put another link to the GGG page in the PR template, because that’s where users who are learning about it for the first time will want to go.
to read more.

---

With Git 2.25 (Q1 2020), there is a tutorial on object enumeration, which provides a good example on how to contribute/test/report a bug.

See commit e0479fa (11 Oct 2019) by Emily Shaffer (nasamuffin).
^{(Merged by Junio C Hamano — gitster — in commit 15d9f3d, 10 Nov 2019)}

documentation: add tutorial for object walking

^{Signed-off-by: Emily Shaffer
Helped-by: Eric Sunshine}

Existing documentation on object walks seems to be primarily intended as a reference for those already familiar with the procedure.
This tutorial attempts to give an entry-level guide to a couple of bare-bones object walks so that new Git contributors can learn the concepts without having to wade through options parsing or special casing.

The target audience is a Git contributor who is just getting started with the concept of object walking.
The goal is to prepare this contributor to be able to understand and modify existing commands which perform revision walks more easily, although it will also prepare contributors to create new commands which perform walks.

The tutorial covers a basic overview of the structs involved during object walk, setting up a basic commit walk, setting up a basic all-object walk, and adding some configuration changes to both walk types.
It intentionally does not cover how to create new commands or search for options from the command line or gitconfigs.

There is an associated patchset at https://github.com/nasamuffin/git/tree/revwalk that contains a reference implementation of the code generated by this tutorial.

Note: that tutorial has been amended in Git 2.27 (Q2 2020):

See commit e3f53ce (28 Mar 2020) by Johannes Schindelin (dscho).
^{(Merged by Junio C Hamano — gitster — in commit 7780604, 22 Apr 2020)}

MyFirstObjectWalk: remove unnecessary conditional statement

^{Signed-off-by: Johannes Schindelin
Reviewed-by: Emily Shaffer}

In the given example, commit cannot be NULL (because this is the loop condition: if it was NULL, the loop body would not be entered at all). It took this developer a moment or two to see that this is therefore dead code.

Let’s remove it, to avoid puzzling future readers.

---

With Git 2.25 (Q1 2020), GitGitGadget is documented.

See commit 3c8d754, commit 3ada78d, commit 4ed5562 (31 Oct 2019) by Emily Shaffer (nasamuffin).
^{(Merged by Junio C Hamano — gitster — in commit f089ddd, 01 Dec 2019)}

myfirstcontrib: hint to find gitgitgadget allower

^{Signed-off-by: Emily Shaffer}

GitGitGadget, a handy tool for converting pull requests against Git into Git-mailing-list-friendly-patch-emails, requires as anti-spam that all new users be "/allow"ed by an existing user once before it will do anything for that new user.

While this tutorial explained that mechanism, it did not give much hint on how to go about finding someone to allow your new pull request.
So, teach our new GitGitGadget user where to look for someone who can add their name to the list.

The advice in this patch is based on the advice proposed for GitGitGadget: gitgitgadget/gitgitgadget PR 138

---

With Git 2.25 (Q1 2020), there are documentation updates for the mailing list archiving and nntp service.

See commit 3eae30e, commit 46c6749 (27 Nov 2019) by Jeff King (peff).
^{(Merged by Junio C Hamano — gitster — in commit 3b3d9ea, 06 Dec 2019)}

doc: replace public-inbox links with lore.kernel.org

^{Signed-off-by: Jeff King}

Since we’re now recommending lore.kernel.org (and because the public-inbox.org domain might eventually go away), let’s update our internal references to use it, too.
That future-proofs our references, and sets the example we want people to follow.

See "This list is now also archived on lore.kernel.org/git"

doc: replace MARC links with lore.kernel.org

^{Signed-off-by: Denton Liu}

Since we’re now recommending lore.kernel.org, replace marc.info links with lore.kernel.org.

Although MARC has been around for a long time, nothing lasts forever (see Gmane).
Since MARC uses opaque message identifiers, switching to lore.kernel.org should be a strict improvement since, even if lore.kernel.org goes down, the Message-ID will allow future readers to look up the referenced messages on any other archive.

We leave behind one reference to MARC in the README.md since it’s a perfectly fine mail archive for personal reading, just not for linking messages for the future.

And:

RelNotes: replace Gmane with real Message-IDs

^{Signed-off-by: Denton Liu}

The only references to Gmane that remain are in RelNotes.
Although these are definitely not in active use, they might be of historical interest for future readers so let’s ensure that mail references are more robust.

Replace links to Gmane with links to lore.kernel.org (which is our new preferred mailing list archive and has the Message-ID in the URL) and bare Gmane ID references with Message-IDs.

The Message-IDs were found by searching for "gmane:<id>" on https://public-inbox.org/git/ and taking the resulting message.

And regarding lkml.org:

doc: replace LKML link with lore.kernel.org

^{Signed-off-by: Denton Liu}

Since we’re now recommending lore.kernel.org, replace LKML link with lore.kernel.org.

Although LKML has been around for a long time, nothing lasts forever (see Gmane).
Since LKML uses opaque message identifiers, switching to lore.kernel.org should be a strict improvement since, even if lore.kernel.org goes down, the Message-ID will allow future readers to look up the referenced messages on any other archive.

---

With Git 2.26 (Q1 2020), there is more documentation for new contributors.

See commit a2dc434 (14 Feb 2020), and commit 4bb4fd4 (24 Jan 2020) by Emily Shaffer (nasamuffin).
^{(Merged by Junio C Hamano — gitster — in commit 325eb66, 25 Feb 2020)}

MyFirstContribution: add avenues for getting help

^{Signed-off-by: Emily Shaffer}

With https://lore.kernel.org/git/[e-mail]/ we now have a mentoring mailing list, to which we should direct new contributors who have questions.

Mention #git-devel, which is targeted for Git contributors; asking for help with getting a first contribution together is on-topic for that channel. Also mention some of the conventions in case folks are unfamiliar with IRC.

Because the mentoring list and #git-devel are both a subset of Git contributors, finally list the main Git list and mention some of the posting conventions.

And:

MyFirstContribution: rephrase contact info

^{Signed-off-by: Emily Shaffer
Reviewed-by: Jonathan Nieder}

Make an effort not to discourage new users from mailing questions to [e-mail], and explain the purpose of the mentoring list in contrast to the main list.

---

With Git 2.27 (Q2 2020), before reporting a bug, read the (new) FAQ.

See commit 2149b67 (30 Mar 2020) by brian m. carlson (bk2204).
^{(Merged by Junio C Hamano — gitster — in commit 06aaafb, 22 Apr 2020)}

docs: add a FAQ

^{Signed-off-by: brian m. carlson}

Git is an enormously flexible and powerful piece of software.

However, it can be intimidating for many users and there are a set of common questions that users often ask.

While we already have some new user documentation, it’s worth adding a FAQ to address common questions that users often have.

Even though some of this is addressed elsewhere in the documentation, experience has shown that it is difficult for users to find, so a centralized location is helpful.

Add such a FAQ and fill it with some common questions and answers. While there are few entries now, we can expand it in the future to cover more things as we find new questions that users have.

The FAQ also addresses common configuration questions that apply not only to Git as an independent piece of software but also the ecosystem of CI tools and hosting providers that people use, since these are the source of common questions.

---

With Git 2.27 (Q2 2020), you can use the "bugreport" tool.

See commit 8f0e984 (27 Apr 2020), and commit 69bcbbc, commit 1411914, commit 617d571, commit 238b439, commit 709df95 (16 Apr 2020) by Emily Shaffer (nasamuffin).
^{(Merged by Junio C Hamano — gitster — in commit dd094c2, 01 May 2020)}

bugreport: add tool to generate debugging info

^{Signed-off-by: Emily Shaffer}

Teach Git how to prompt the user for a good bug report: reproduction steps, expected behavior, and actual behavior. Later, Git can learn how to collect some diagnostic information from the repository.

If users can send us a well-written bug report which contains diagnostic information we would otherwise need to ask the user for, we can reduce the number of question-and-answer round trips between the reporter and the Git contributor.

Users may also wish to send a report like this to their local "Git expert" if they have put their repository into a state they are confused by.

The git bugreport documentation includes:

git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]

DESCRIPTION

Captures information about the user’s machine, Git client, and repository state, as well as a form requesting information about the behavior the user observed, into a single text file which the user can then share, for example to the Git mailing list, in order to report an observed bug.

The following information is requested from the user:

• Reproduction steps
• Expected behavior
• Actual behavior

---

With Git 2.27 (Q2 2020), "git bugreport" learned to report enabled hooks in the repository.

See commit 788a776 (08 May 2020) by Emily Shaffer (nasamuffin).
^{(Merged by Junio C Hamano — gitster — in commit 3583730, 14 May 2020)}

bugreport: collect list of populated hooks

^{Signed-off-by: Emily Shaffer}

Occasionally a failure a user is seeing may be related to a specific hook which is being run, perhaps without the user realizing.
While the contents of hooks can be sensitive – containing user data or process information specific to the user’s organization – simply knowing that a hook is being run at a certain stage can help us to understand whether something is going wrong.

Without a definitive list of hook names within the code, we compile our own list from the documentation. This is likely prone to bitrot, but designing a single source of truth for acceptable hooks is too much overhead for this small change to the bugreport tool.

---

With Git 2.28 (Q3 2020), "git bugreport" learns to report what shell is in use.

See commit 4a4804e, commit 39f4919 (12 May 2020) by Emily Shaffer (nasamuffin).
^{(Merged by Junio C Hamano — gitster — in commit ce095ec, 09 Jun 2020)}

help: add shell-path to --build-options

^{Signed-off-by: Emily Shaffer}

It may be useful to know which shell Git was built to try to point to, in the event that shell-based Git commands are failing.
$SHELL_PATH is set during the build and used to launch the manpage viewer, as well as by git-compat-util.h, and it’s used during tests.
‘git version --build-options‘ is encouraged for use in bug reports, so it makes sense to include this information there.

And:

bugreport: include user interactive shell

^{Signed-off-by: Emily Shaffer}

It’s possible a user may complain about the way that Git interacts with their interactive shell, e.g. autocompletion or shell prompt. In that case, it’s useful for us to know which shell they’re using interactively.

---

Expectation for the original contributor after responding to a review comment to use the explanation in a patch update has been described with Git 2.30 (Q1 2021).

See commit a6d8d11 (20 Nov 2020) by Junio C Hamano (gitster).
^{(Merged by Junio C Hamano — gitster — in commit b94b1f9, 30 Nov 2020)}

MyFirstContribition: answering questions is not the end of the story

^{Reviewed-by: Emily Shaffer}

A review exchange may begin with a reviewer asking "what did you mean by this phrase in your log message (or here in the doc)?", the author answering what was meant, and then the reviewer saying "ah, that is what you meant—then the flow of the logic makes sense".

But that is not the happy end of the story.
New contributors often forget that the material that has been reviewed in the above exchange is still unclear in the same way to the next person who reads it, until it gets updated.

While we are in the vicinity, rephrase the verb "request" used to refer to comments by reviewers to "suggest"—this matches the contrast between "original" and "suggested" that appears later in the same paragraph, and more importantly makes it clearer that it is not like authors are to please reviewers’ wishes but rather reviewers are merely helping authors to polish their commits.
made the change suggested, feel the original is better, or that the comment

MyFirstContribution now includes in its man page:

Reviewers may ask you about what you wrote in the patchset, either in
the proposed commit log message or in the changes themselves. You
should answer these questions in your response messages, but often the
reason why reviewers asked these questions to understand what you meant
to write is because your patchset needed clarification to be understood.

Do not be satisfied by just answering their questions in your response
and hear them say that they now understand what you wanted to say.
Update your patches to clarify the points reviewers had trouble with,
and prepare your v2; the words you used to explain your v1 to answer
reviewers’ questions may be useful thing to use. Your goal is to make
your v2 clear enough so that it becomes unnecessary for you to give the
same explanation to the next person who reads it.

---

With Git 2.30 (Q1 2021), the use of non-reentrant localtime() has been removed.

See commit 4f6460d (30 Nov 2020) by Taylor Blau (ttaylorr).
^{(Merged by Junio C Hamano — gitster — in commit bb48056, 08 Dec 2020)}

builtin/bugreport.c: use thread-safe localtime_r()

^{Signed-off-by: Taylor Blau}

To generate its filename, the ‘git bugreport‘^(man) builtin asks the system for the current time with ‘localtime()‘.
Since this uses a shared buffer, it is not thread-safe.

Even though ‘git bugreport‘^(man) is not multi-threaded, using localtime() can trigger some static analysis tools to complain, and a quick

$ git grep -oh 'localtime\(_.\)\?' -- **/*.c | sort | uniq -c  

shows that the only usage of the thread-unsafe ‘localtime’ is in a piece of documentation.

So, convert this instance to use the thread-safe version for consistency, and to appease some analysis tools.