Skip to content

docs: fix configuration examples and WSL setup instructions - #493

Merged
deadc0de6 merged 2 commits into
deadc0de6:masterfrom
dajiaohuang:docs/repair-config-wsl-examples-20261016
Oct 20, 2026
Merged

deadc0de6 merged 2 commits into
deadc0de6:masterfrom
dajiaohuang:docs/repair-config-wsl-examples-20261016

Conversation

@dajiaohuang

Copy link
Copy Markdown
Contributor

Summary

Fix four existing documentation instructions/examples that fail when followed:

  • The imported other-host profile refers to f_gchi, but the example defines f_ghci. The former fails config loading with a missing-dotfile error.
  • The dynamic source-path example uses lists for profile variables; these must be mappings. The list form fails with 'CommentedSeq' object is not a mapping.
  • The suggested shell alias is missing its opening quote, resulting in a shell syntax error.
  • WSL runs Linux Python: python-magic-bin has no compatible Linux distribution. Point to the existing python-magic requirement plus the Linux libmagic library instead.

No runtime behavior changes.

Validation

On Ubuntu 24.04 under WSL, Python 3.12, using only synthetic files and isolated HOME/config/work/temp directories:

  • Reproduced the missing-key and list-shaped-variable errors through the CLI; verified the corrected configurations load.
  • Parsed the repaired YAML examples and checked their cross-file keys and both dynamic filename substitutions.
  • Checked the exact repaired alias with bash --noprofile --norc -n (without executing it).
  • Verified python-magic/libmagic classifies synthetic text; confirmed pip download --only-binary=:all: --no-deps python-magic-bin has no matching WSL distribution. No system package installation performed.
  • Exercised install/dry-run/prompt, compare, import/update/remove/uninstall, backup restoration, profile inheritance/overrides, templating and relative/absolute/child symlinks on synthetic files; directory-template update preserves the template.
  • Ran the project's scripts/check_links.py on all three changed pages: passed (19 URLs found, one ignored by the existing checker).
  • git diff --check passed.

Did not run the unrelated full Python/bash/platform test matrix or the CI-only remark internal-link checker; no links or runtime code changed.

Comment thread docs/installation.md Outdated
shell with the config file path; for example:
```
alias dotdrop=<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'
alias dotdrop='<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

alias dotdrop='<absolute-path-to-dotdrop.sh>' --cfg='<path-to-your-config.yaml>'

@deadc0de6

Copy link
Copy Markdown
Owner

Hello, thanks for your help, I added a comment on the quoting issue. Once fixed, I'll merge it.

Keep the launcher and --cfg paths quoted inside the alias expansion so paths containing spaces remain single arguments.

AI-assisted revision using OpenAI Codex.
@dajiaohuang

Copy link
Copy Markdown
Contributor Author

Updated in 0771bf7: both the launcher path and the config path are now quoted inside the alias expansion. The outer single quotes retain the inner double quotes when defining the alias.

With an isolated, self-authored launcher fixture and spaces in both paths, the previous example fails to locate the launcher; the updated alias invokes it and passes the complete --cfg=... value and the following command as separate arguments. Bash syntax and the one-line-only documentation diff were also checked. Earlier checks for the other documentation changes are unchanged and were not repeated.

No real dotfiles, hooks or shell profiles were executed or changed. I have not run the full platform matrix or checked CI for this revision.

@deadc0de6
deadc0de6 merged commit d5ac0b1 into deadc0de6:master Oct 20, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants