[arecarn]

Adds --dotfiles: a package entry named dot-foo is stowed as .foo, like GNU stow. Builds on #16 by @menghuu.

• stow accepts the flag. Names that would resolve outside the destination (dot-, dot-., dot-.., dot-.hidden) are left as they are, as GNU stow does.
• unstow finds links by what they point at, so it removes them whether they are named dot-foo or .foo. It does not need the flag, and still accepts it.
• Folding after an unstow unlinks the links it found instead of looking them up again by name.
• The README documents the flag, and the changelog has an entry.

Closes #30.

[harkabeeparolus]

I love that you're tackling this problem! ☺️
I think there may be some correctness issues with this branch in its current state, though. I'll suggest some improvements shortly.

[harkabeeparolus]

Matching links by what they point at (follow-up idea)

The fixes I'm proposing all patch the same underlying thing. unstow finds a link by predicting its name from the package entry: dot-foo becomes .foo with --dotfiles and stays dot-foo without it. So a stow and an unstow have to agree on the flag, and each way they can disagree needs its own guard. The existing warning covers one direction and the new one covers the other, and the fold path had to stop re-deriving names because it crashed on a link whose name it could not predict. Some cases are still unguarded. A stow without the flag followed by a stow with it leaves two links to the same file, dot-bbb and .bbb, and neither form of unstow removes both. Unfolding another package's folded directory renames that package's links to whatever convention the current run is using.

One rule could cover all of these. Instead of predicting a single name, unstow could look at both candidate names for an entry, the literal one and the translated one, and unlink whichever is a symlink that resolves into the package entry. If a link points into the package, a stow made it, whatever it is called. clean already works this way, which is why the README can say it is unaffected by the flag.

With that rule, --dotfiles is no longer needed on unstow, though it could stay accepted for symmetry with stow and with GNU Stow. DotfilesMismatch and _is_linked_into go away, and so does the README's "pass the flag to unstow as well" caveat. The double-link case and the unfold renaming need no extra code, because the link still points into the package no matter what it ended up being called.

GNU Stow 2.4.1 requires the flag on stow -D and silently leaves links behind in both mismatch directions, exiting 0. So the warnings already put dploy ahead of Stow here, and matching by target would be another step in the same direction. Stow's own --compat mode walks the destination instead of the package for a related reason.

The cost is a larger change to _collect_actions. It would need a hook that returns one candidate for stow and two for unstow, and already unlinked would have to pick a name to print when neither candidate exists. The tests for the warnings would turn into tests that the links are removed.

I'd suggest landing the guard-based fixes here, since they are small and keep the design of this PR, and opening a follow-up issue for the target-based approach. I'm happy to prototype it if that would help.

[arecarn]

Thank you for the review and the follow-up PR.

Your fixes from #45 are in 488a13d. I also used your target-matching idea: unstow now removes links by what they point at, so it no longer needs --dotfiles, and the mismatch warnings are gone.

[arecarn]

Merged. Thank you @menghuu for the original --dotfiles work in #16. Your commit is the base of this change, and you are the author of the merged commit. Thank you also @harkabeeparolus for the review and the fixes in #45, which are included.