# How to Report a Bug in Superfile: Complete Guide for GitHub Issues > Report Superfile bugs effectively on GitHub. Learn how to check for duplicates and submit debug logs with spf --debug or spf --debug-info to ensure faster resolution. - Repository: [Yorukot/superfile](https://github.com/yorukot/superfile) - Tags: how-to-guide - Published: 2026-07-29 --- **Report bugs in Superfile by opening a new issue on GitHub after checking for duplicates, and include debug logs using `spf --debug` or `spf --debug-info` to help maintainers reproduce the issue.** Superfile is a modern terminal file manager written in Go. When you encounter unexpected behavior or crashes, reporting a bug through the official channels helps improve the tool for everyone. This guide explains exactly how to report a bug in Superfile using the GitHub issue tracker and what diagnostic information to include. ## Where to Report Bugs in Superfile The application itself directs users to the issue tracker. In [`src/internal/model_render.go`](https://github.com/yorukot/superfile/blob/main/src/internal/model_render.go), the first-use modal explicitly prompts users to open issues for bug reports (lines 110-112): ```go " If you have any questions, please feel free to ask at:\n"+ " https://github.com/yorukot/superfile\n"+ " Of course, you can always open a new issue to share your idea \n"+ " or report a bug!") ``` The official repository is `yorukot/superfile`, and all bug reports should be submitted at https://github.com/yorukot/superfile/issues. ## Step-by-Step Bug Reporting Workflow According to [`website/src/content/docs/contribute/how-to-contribute.md`](https://github.com/yorukot/superfile/blob/main/website/src/content/docs/contribute/how-to-contribute.md) (lines 23-28), follow this process when you report a bug in Superfile: 1. **Search existing issues** – Verify the problem hasn't already been reported in open or closed issues. 2. **Create a new issue** – Open a new GitHub issue with a clear description, steps to reproduce, expected vs. actual behavior, and environment details. 3. **Attach debug logs** – When possible, include logs generated with the debug flags to help maintainers triage the bug. ### Check for Duplicate Issues Before submitting, search the repository's issue tracker to avoid duplicates. This saves time for both reporters and maintainers. ### Gathering Debug Information Superfile provides built-in debugging capabilities through [`src/pkg/utils/log_utils.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/utils/log_utils.go), which controls the `SetRootLoggerToStdout` function. When reproducing your bug, run Superfile with debug logging enabled: ```bash # Enable debug output spf --debug # Or print version and debug information spf --debug-info ``` Capture this output to attach to your issue. ## Creating Issues Using the GitHub CLI You can expedite the reporting process using the official GitHub CLI (`gh`). After installing and authenticating `gh`, create a detailed bug report from your terminal: ```bash # Install GitHub CLI brew install gh # macOS sudo apt-get install gh # Debian/Ubuntu # Authenticate (one-time setup) gh auth login # Create a new issue with detailed template gh issue create \ --title "Crash when opening large directory" \ --body "$(cat <10,000 files. **Steps to reproduce** 1. Run \`spf /path/to/large/dir\` 2. Observe the crash. **Environment** - OS: macOS 14.2 - Superfile version: $(spf --version) - Go version: $(go version) **Debug logs** \`\`\` $(spf --debug-info) \`\`\` EOF )" ``` ## Key Information to Include When you report a bug in Superfile, include these elements to ensure efficient resolution: - **Clear description** – What happened versus what you expected - **Reproduction steps** – Minimal steps to trigger the issue - **Environment details** – Operating system, Superfile version, and Go version - **Debug logs** – Output from `spf --debug` or `spf --debug-info` - **Screenshots** – If applicable, visual evidence of UI glitches ## Summary - **Report bugs** through the GitHub issue tracker at `yorukot/superfile`. - **Check existing issues** first to avoid duplicates, as documented in [`how-to-contribute.md`](https://github.com/yorukot/superfile/blob/main/how-to-contribute.md). - **Enable debugging** using `spf --debug` or `spf --debug-info` before reproducing the issue. - **Provide complete context** including environment details and logs to speed up triage. - **Use the GitHub CLI** (`gh issue create`) to submit detailed reports from the command line. ## Frequently Asked Questions ### Where is the Superfile issue tracker located? The official issue tracker is hosted on GitHub at https://github.com/yorukot/superfile/issues. The application itself references this location in [`src/internal/model_render.go`](https://github.com/yorukot/superfile/blob/main/src/internal/model_render.go) to remind users where to report bugs. ### How do I enable debug logging in Superfile? Run Superfile with the `--debug` flag to enable verbose logging, or use `--debug-info` to print version and system information. These flags are handled in [`src/pkg/utils/log_utils.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/utils/log_utils.go) and help provide maintainers with the diagnostic data needed to reproduce your bug. ### Should I search existing issues before reporting a new bug? Yes. The contribution guidelines in [`website/src/content/docs/contribute/how-to-contribute.md`](https://github.com/yorukot/superfile/blob/main/website/src/content/docs/contribute/how-to-contribute.md) explicitly instruct users to check for existing open or closed issues before creating a new one. This prevents duplicate reports and helps you find existing workarounds. ### Can I report bugs without using the GitHub web interface? Yes. You can use the GitHub CLI (`gh`) to create issues directly from your terminal. Install `gh`, authenticate with `gh auth login`, and use `gh issue create` to submit your bug report with a pre-filled template including debug logs.