Skip to content

docs(config): show platform-specific config.pkl paths for macOS and Linux#800

Closed
fukuchancat wants to merge 3 commits intojdx:mainfrom
fukuchancat:docs/fix-config-path-macos
Closed

docs(config): show platform-specific config.pkl paths for macOS and Linux#800
fukuchancat wants to merge 3 commits intojdx:mainfrom
fukuchancat:docs/fix-config-path-macos

Conversation

@fukuchancat
Copy link
Copy Markdown
Contributor

@fukuchancat fukuchancat commented Apr 3, 2026

Hi! 🍣

I noticed the docs consistently refer to ~/.config/hk/config.pkl as the global config path, but hk uses dirs::config_dir() which resolves to ~/Library/Application Support/ on macOS, not ~/.config/.

This means macOS users following the docs will put their config in a location hk never reads.

This PR updates all references in docs/configuration.md to show both paths:

  • ~/.config/hk/config.pkl (Linux)
  • ~/Library/Application Support/hk/config.pkl (macOS)

@greptile-apps
Copy link
Copy Markdown

greptile-apps Bot commented Apr 3, 2026 •
edited
Loading

Greptile Summary

This PR correctly fixes a cross-platform documentation bug: hk uses dirs::config_dir() which resolves to ~/Library/Application Support/ on macOS rather than ~/.config/, meaning macOS users following the old docs would place their config in a location hk never reads. All six changed files now show both the Linux (~/.config/hk/config.pkl) and macOS (~/Library/Application Support/hk/config.pkl) paths, including the user-visible --hkrc help text in src/cli/mod.rs.

  • All locations flagged in the prior review (CLI help, commands.json, settings.toml, hk.usage.kdl) have been updated
  • docs/configuration.md section heading was renamed to ### User Configuration (config.pkl), but two internal anchor links still use #user-configuration-config-pkl — GFM strips the dot from config.pkl, making the generated anchor #user-configuration-configpkl (no hyphen), so both links will be broken in rendered docs

Confidence Score: 4/5

Safe to merge after fixing the broken internal anchor links in docs/configuration.md

The core documentation fix is correct and complete across all six files. One P1 issue remains: the renamed section heading generates anchor #user-configuration-configpkl but two links in the same file reference #user-configuration-config-pkl, producing dead navigation links in the rendered docs.

docs/configuration.md — internal anchor links at lines 194 and 202 need to match the anchor generated by the renamed section heading

Important Files Changed

Filename Overview
docs/configuration.md Correctly shows platform-specific paths for macOS and Linux, but introduces broken internal anchor links due to GFM dot-removal in heading anchors
src/cli/mod.rs Updated deprecation doc comment on --hkrc flag to include both Linux and macOS paths; correct and user-visible fix
docs/cli/commands.json Updated CLI reference JSON help strings with both platform paths; also adds ./ prefix to hk.local.pkl
hk.usage.kdl Updated --hkrc flag help text in KDL usage definition with platform-specific paths
settings.toml Updated three doc strings (hkrc, skip_hooks, skip_steps) to include both Linux and macOS config paths
src/output.rs Updated doc-comment example string in deprecated_at! macro; purely cosmetic/documentation change

Reviews (3): Last reviewed commit: "docs(config): deduplicate platform-speci..." | Re-trigger Greptile

greptile-apps[bot]
greptile-apps Bot reviewed Apr 3, 2026
View reviewed changes
Comment thread docs/configuration.md Outdated
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Apr 3, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the documentation in docs/configuration.md to include platform-specific configuration paths for both Linux and macOS. The review feedback suggests simplifying the tables by using references to the main hkrc section instead of repeating long, platform-specific paths in every row, which improves readability and reduces visual clutter.

Comment thread docs/configuration.md Outdated
Comment thread docs/configuration.md Outdated
@fukuchancat fukuchancat mentioned this pull request Apr 3, 2026
Merged
jdx pushed a commit that referenced this pull request Apr 4, 2026
@fukuchancat
fix(config): use XDG_CONFIG_HOME for config path instead of dirs::con…
efa25df 
…fig_dir() (#801)

Hello 🍣

I opened #800 to fix the docs showing `~/.config/hk/config.pkl` as the
global config path, which doesn't match the actual path on macOS
(`~/Library/Application Support/hk/config.pkl` via
`dirs::config_dir()`).

Another option would be to align with mise's approach — use
`$XDG_CONFIG_HOME` (defaulting to `~/.config`) on all platforms instead
of `dirs::config_dir()`. This way `~/.config/hk/config.pkl` works
everywhere and the docs are already correct.

Not sure which approach makes more sense for hk — happy to defer to your
judgment!
@jdx
Copy link
Copy Markdown
Owner

jdx commented Apr 4, 2026

Closing in favor of #801, which was merged. That PR aligned the code to always use ~/.config/hk/ (via XDG_CONFIG_HOME) on all platforms, so the docs are now correct as-is. Thanks for both PRs!

This comment was generated by Claude Code.

@jdx jdx closed this Apr 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@greptile-apps greptile-apps[bot] greptile-apps[bot] left review comments

+1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@fukuchancat @jdx