Bryan Beverly
4d2a8ef686
* Add man page generation for trufflehog Add a hidden --generate-man-page flag that uses an enhanced Kingpin template to produce a standards-compliant roff man page. The man page includes auto-generated OPTIONS and COMMANDS sections (synced with the CLI definitions), plus hand-maintained EXAMPLES, EXIT STATUS, ENVIRONMENT, FILES, BUGS, and SEE ALSO sections. The DESCRIPTION and EXAMPLES sections call out the interactive TUI that launches when trufflehog is run without a command in a terminal. To keep the generated output deterministic, the --concurrency flag is defined with a static "N" placeholder; the runtime.NumCPU() default is applied at runtime instead of at flag-definition time. The usage line also uses the lowercase binary name. Distribution: - Makefile `man` target to regenerate locally - GoReleaser before hook to regenerate at release time with the correct version injected via ldflags - Release archives explicitly include LICENSE, README.md, and docs/man/trufflehog.1 - Homebrew formula installs the man page to man1 The Makefile `test-release` target is also updated to GoReleaser v2 flag syntax (--skip=publish,sign), which is needed for the snapshot release to succeed locally without cosign installed. Made-with: Cursor * Add man page maintenance guardrails Add a CI job that regenerates the man page on every PR and fails if the checked-in copy at docs/man/trufflehog.1 is out of date with the current CLI definitions. Document the regeneration workflow in CONTRIBUTING.md so contributors know to run `make man` and commit the result when changing flags or subcommands. Made-with: Cursor
2.6 KiB
Contribution guidelines
Please create an issue to collect feedback prior to feature additions. If possible try to keep PRs scoped to one feature, and add tests for new features. We use the fork-based contribution model described by GitHub's documentation. (In short: Fork the TruffleHog repo and open a PR back from your fork into our default branch.)
When showing interest in a bug, enhancement, PR, or issue, please use the thumbs up/thumbs down emoji on the original message rather than adding comments expressing the same.
Contributors need to sign our CLA before we are able to accept contributions.
Resources
How things work
It can be a bit daunting diving into the code and wrapping your head around the project from a high level. The following two docs help give that high level overview:
Adding new secret detectors
We have published some documentation and tooling to get started on adding new secret detectors. Let's improve detection together!
Logging in TruffleHog
Use fields over format strings. For structured logging, fields allow us to better filter and search through logs than embedding data in the message.
Differentiate logs coming from dependencies. This can be done with a "dep" field that gets passed to the library. Sometimes it’s not possible to do this.
Limit log levels to info (indicate normal or expected operation) and error (functionality is impeded and should be checked by an engineer)
Choose an appropriate verbosity level
0. — logs we always want to see
1. — logs we could possibly want to turn off
2. — logs that are useful for debugging
3. — frequently called logs that may produce a lot of output
4. — extremely verbose logs or logs containing sensitive information
5. — ultimate verbosity
Example: Logger().V(2).Info("skipping file: extension is ignored", "ext", mimeExt)
Either log an error or return it. Doing one or the other will help defer logging for when there is more context for it and prevent duplicate “bubbling up” logs.
Log contextual information. Every log emitted should contain this context via fields to easily filter and search.
Updating the man page
If you add, remove, or rename CLI flags or subcommands, regenerate the man page with make man and commit the updated docs/man/trufflehog.1. CI will fail if the checked-in man page is stale.