git-bugreport
Generate Git bug reports
TLDR
Create a new bug report file in the current directory
Create a new bug report file in the specified directory, creating it if it does not exist
Create a new bug report file with the specified filename suffix in strftime format
SYNOPSIS
git bugreport [--format=format] [--output-directory=path] [--compress=format] [--include-description] [--diagnose-script=script] [--version] [--no-diagnose-script]
PARAMETERS
--format=
Specifies the output format for the bug report. Accepted values are tarball (default) or directory.
--output-directory=
Sets the destination directory where the bug report will be created. By default, a temporary directory is used.
--compress=
Determines the compression format when the output --format is tarball. Supported formats are gz (default), bz2, or xz.
--include-description
Prompts the user to enter a textual description of the bug, which is then included in the generated report.
--diagnose-script=
Runs an additional, user-provided diagnostic script and includes its output in the report. The script should be executable.
--no-diagnose-script
Prevents the execution of the default diagnostic scripts that git-bugreport normally runs to gather system and Git environment information.
--version
Displays the version of the git-bugreport command and exits.
-h, --help
Shows the command's usage information and exits.
DESCRIPTION
git-bugreport is a command-line utility designed to assist users in generating comprehensive bug reports for Git. When encountering an issue, providing sufficient diagnostic information is crucial for developers to understand and fix the problem. This command automates the collection of relevant data, ensuring that all necessary details are included without requiring manual compilation.
It gathers a wide array of information, including the Git version, operating system details, Git configuration settings (both global and repository-specific), and a snapshot of the current repository state (e.g., reflog, git status output, relevant parts of the commit history). Optionally, users can provide a textual description of the bug.
The collected data is typically packaged into a single tarball or a directory, which can then be easily shared with Git maintainers or developers. By streamlining the report generation process, git-bugreport significantly simplifies the task of reporting issues, helping to expedite troubleshooting and resolution.
CAVEATS
When sharing the generated bug report, users should be aware that it may contain potentially sensitive information such as Git configuration, reflog entries, and parts of the repository history. Review the contents before sharing. Additionally, using the --diagnose-script option allows arbitrary code execution, so ensure that any provided script is trusted.
INFORMATION GATHERED
The git-bugreport command collects a wide array of diagnostic information to help debug Git issues. This typically includes:
Git Version and Build Information: Details about the Git executable itself.
Operating System Information: Basic OS details (e.g., kernel version, distribution).
Environment Variables: Relevant environment variables like GIT_TRACE or PATH.
Git Configuration: System, global, and repository-specific Git configuration settings.
Repository Status: Output of git status, git branch -vv, and git remote -v.
Reflog: The complete reflog for the current repository.
Active Processes: A list of currently running Git processes.
Custom Script Output: Output from any script specified with --diagnose-script.
Bug Description: If --include-description is used, the user's description.
The collected data aims to provide a comprehensive snapshot of the user's environment and the repository's state at the time of the bug, crucial for replication and diagnosis.
HISTORY
git-bugreport was introduced in Git version 2.29.0, released in October 2020. Its primary purpose was to standardize and simplify the process of gathering comprehensive diagnostic data for Git bugs, addressing the common challenge of inadequate information in user-submitted bug reports. It evolved as a specialized tool to capture the necessary context (system, Git environment, and repository state) required by developers for effective troubleshooting.
SEE ALSO
git(1), git-version(1), git-config(1), git-fsck(1), git-reflog(1)