Report a Bash Bug Safely with bashbug

You will finish with a prepared Bash bug report that contains the local build details, a reproducible description and an explicit recipient check. The report is not sent until you confirm it, so you can safely inspect or abandon an accidental invocation.

Allow about fifteen minutes for a small report, longer if reproducing the fault needs investigation. You need Bash, the bashbug command and an editor. This guide uses the installed GNU bashbug 5.2.21-release from package bash 5.2.21-2ubuntu4. It does not need sudo, and it does not change Bash, system configuration or services.

1. Check the installed command

Start with read-only checks. This avoids writing a report before you know which program and release you are using:

$ command -v bashbug
/usr/bin/bashbug
$ bashbug --version
GNU bashbug, version 5.2.21-release
$ dpkg-query -W -f='${Package} ${Version}\n' bash
bash 5.2.21-2ubuntu4

The version matters when the problem may already be fixed upstream. Include it in your report rather than describing the shell only as "Bash". The installed script also records machine, operating-system, compiler and uname information in the template.

Checkpoint: if command -v finds nothing, install the distribution's Bash package through your normal package-management process, then repeat these checks. Do not copy a script from an unrelated host into /usr/bin.

2. Decide where the report will go

The positional argument is a comma-separated list of email addresses. For this installed release, the default address is [email protected]. You can make the destination explicit when your project or support process requires it:

$ bashbug '[email protected]'

Do not use a real address as a trial value unless you are ready to create a report. The command will open the editor after building the template. A report can contain system and build details, so check the address as carefully as you would check an external email recipient.

The local manpage shipped with this machine is dated 11 December 2007 and describes GNU Bash 3.1. It says that the default report is sent to both GNU developers and Debian Bash maintainers. The installed 5.2.21 script is the authoritative behaviour here and uses [email protected] for this release. Treat old manpage text as a useful interface summary, not proof of the current recipient list.

3. Prepare the report in your editor

Set an editor for this invocation if the normal editor choice is not the one you want:

$ EDITOR="/usr/bin/nano" bashbug '[email protected]'

EDITOR is used when set. The documented DEFEDITOR variable can provide the fallback editor when EDITOR is unset. Keep the value to an editor executable path or a deliberately configured command. The script invokes it with the temporary report file as its argument.

The template has these useful sections:

• a subject line, which must be replaced with a short, descriptive subject;
• automatically generated configuration information, which should not be edited;
• a detailed description of the fault;
• a repeat-by sequence that another person can follow; and
• an optional fix section if you know one.

Describe the smallest command sequence that still fails. Include the working directory, relevant shell options, input files or a reduced script, and the output and exit status. Remove passwords, tokens, private paths and confidential input before saving. A reproducible report is more useful than a long account of everything you tried.

Checkpoint: before leaving the editor, confirm that the subject is no longer the template's bracketed placeholder and that the repeat-by section can be followed on a clean shell.

4. Understand the safety prompts

There are two important guards after editing. If you leave the default subject unchanged, bashbug refuses to continue and asks whether to abandon the report. Answer y to give up, or n to return to the editor.

If you quit without changing the temporary file, the command prints:

File not changed, no bug report submitted.

This is the safest response to an accidental launch: quit without saving. The temporary directory is removed when the command exits. If the editor exits unsuccessfully, the script offers the same choice to give up or re-enter the editor.

5. Confirm before sending

After a changed report passes the subject check, the command asks for confirmation. It displays the destination, then waits for an answer similar to:

Send bug report to [email protected]? [y/n]

Type n if the address, wording or attached system details are not right. The command exits without submitting the report. There is no need for elevated privileges at this point. Type y only after you have checked the complete message and are happy for the mail system to process it.

Sending is an external and potentially irreversible action. The confirmation is not a preview of how a remote list will redistribute the message, so do not put secrets or personal data in the report. If mail delivery fails, the installed script appends the report to $HOME/dead.bashbug and prints the address to which it should be sent manually. Protect that file because it may contain the same machine and build information.

6. Check the result without repeating the report

For an abandoned report, verify only the exit status from the shell you used:

$ printf 'bashbug status: %s\n' "$?"
bashbug status: 0

A zero status after answering n, or after quitting without saving, means the local command completed its cancellation path. It does not mean that a report was sent. The visible confirmation prompt and the mail system's delivery result are separate from the exit status.

If delivery failed, inspect the recovery file without printing it into a shared terminal:

$ test -s "$HOME/dead.bashbug" && printf '%s\n' 'A failed bashbug report is waiting in $HOME/dead.bashbug'
A failed bashbug report is waiting in $HOME/dead.bashbug

Do not delete that file until you have either sent a reviewed copy through an approved channel or decided that the report is no longer needed. If it contains sensitive data, restrict access before retaining it:

$ chmod 600 "$HOME/dead.bashbug"

This changes only the file's permissions. To remove a report you have deliberately decided not to retain, use rm -- "$HOME/dead.bashbug" after checking the exact path. That deletion is irreversible unless another copy exists.

7. Avoid the common traps

• Do not treat --version as a full Bash diagnostic. It identifies bashbug; the generated template carries the Bash release and build information.
• Do not assume an unchanged default subject will be accepted. Replace it with the failing behaviour and, if useful, the smallest reproducer.
• Do not confuse a successful local exit with successful delivery. Check the confirmation choice and investigate $HOME/dead.bashbug when delivery fails.
• Do not pass a comma-separated address list copied from untrusted input. Review every recipient before invoking the editor.
• Do not edit the automatically generated configuration block unless a maintainer specifically asks for a correction; record extra context in the description.