Make a Useful Git Bug Report Without Leaking Your Repository

By the end, you will have a text report containing Git and machine details plus a structured account of the failure. You will also know when an optional diagnostics archive is safe to attach and when it is too revealing.

Allow about five minutes for a straightforward report, plus time to reproduce the problem and review the files. This guide describes the Git 2.43.0 installed on this machine. Run the commands as your ordinary user. No elevated privileges are needed.

Checkpoint 1: confirm the Git version and repository

Start in the repository where the problem occurred. Confirm that Git is the program you think it is, and that the current directory belongs to a repository.

git --version
git rev-parse --show-toplevel

On this machine the first command reports:

git version 2.43.0

The second command should print the repository's absolute top-level path. If it says that the directory is not a repository, change directory before collecting the report. The repository context helps Git include relevant state, but the report does not record your reproduction steps for you.

Checkpoint 2: write the basic report

Choose a private output directory so the new files do not get mixed into your working tree. The example uses a directory below /tmp, which is normally cleaned automatically, and tells Git not to create the optional archive.

report_dir=$(mktemp -d /tmp/git-bugreport.XXXXXX)
GIT_EDITOR=true git bugreport \
  --output-directory "$report_dir" \
  --suffix '%Y%m%d-%H%M%S' \
  --no-diagnose
printf 'Reports in %s:\n' "$report_dir"
find "$report_dir" -maxdepth 1 -type f -printf '%f\n'

Git creates a file named like git-bugreport-20260924-011256.txt. The suffix is a strftime(3) format, evaluated using the local time. Without --output-directory, the file is written to the current directory. Without --suffix, Git chooses its normal timestamped name.

GIT_EDITOR=true makes this example suitable for a terminal or script where no editor is configured. In an interactive session you can omit it if you want Git to open your editor. Git still writes the report before attempting that editor step, but an unset editor can leave a confusing error in the terminal.

Checkpoint 3: fill in the human part

Open the generated text file and answer the questions near the top. Describe one minimal reproduction rather than a general complaint. Include exact commands, the smallest useful input, what you expected, what happened, and any difference between those two outcomes.

report_file=$(find "$report_dir" -maxdepth 1 -name 'git-bugreport-*.txt' -print -quit)
sed -n '1,35p' "$report_file"

The report also contains automatic details such as git version --build-options, operating-system and machine strings, compiler and libc information, the shell path, the value of $SHELL, and enabled hooks. Read the whole file before sharing it. Repository paths, usernames, host details and hook names can identify an environment even when the report contains no source code.

Checkpoint 4: add diagnostics only when needed

The --diagnose option creates a separate ZIP archive alongside the text report. In Git 2.43.0, the default mode is stats. It gathers repository shape information such as packfile names and sizes, loose-object counts, available disk space and the repository root.

GIT_EDITOR=true git bugreport \
  --output-directory "$report_dir" \
  --suffix '%Y%m%d-%H%M%S-with-stats' \
  --diagnose=stats
find "$report_dir" -maxdepth 1 -type f -printf '%f\n'
unzip -l "$report_dir"/git-diagnostics-*.zip

Expected output includes one new git-bugreport-... text file and one git-diagnostics-...zip archive. The archive normally contains files such as diagnostics.log, packs-local.txt and objects-local.txt.

Privacy warning: do not use --diagnose=all casually. The all mode additionally copies parts of .git, including logs and objects, and can allow the repository contents to be reconstructed. Treat that archive like a copy of the repository. Use it only when a maintainer specifically asks for it, then inspect the ZIP and transfer it through an approved private channel.

Common traps and recovery

• Wrong directory: a report from a parent directory can describe the wrong repository or fail to launch. Return to the repository root and run git rev-parse --show-toplevel.
• Missing editor: set GIT_EDITOR=true for unattended collection, or set it to a trusted editor for interactive editing. Do not paste secrets into the report.
• Repeated runs: use a new output directory or a distinct suffix. Git does not overwrite a useful report by design when its generated name is unique.
• Unwanted files: reports are ordinary files. If you have not shared them, remove the temporary directory with rm -r -- "$report_dir". Check the path first; never substitute a broad directory such as /tmp itself.
• Unreadable configuration: Git may fail to launch if a relevant configuration file cannot be read. Record that failure separately and gather the version and system details manually rather than repeatedly retrying with elevated privileges.

If the bug is security-sensitive, do not post the report to a public issue tracker. Ask the project for its private security reporting route first. The report can expose environment details even after you remove the reproduction text.