How to Report a Bug in Superfile: Complete Guide for GitHub Issues

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, the first-use modal explicitly prompts users to open issues for bug reports (lines 110-112):

"      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 (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, which controls the SetRootLoggerToStdout function. When reproducing your bug, run Superfile with debug logging enabled:

# 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:

# 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 <<EOF
**Describe the bug**
A panic occurs when opening a directory containing >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.
• 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}