Reposition Stow according to its primary use case

[aspiers]

I stumbled across a video about Stow which led to finding several
others, as well as several blog posts etc., and was amazed to see the
overwhelming popularity of the dotfiles management use case.

It was also clear that the labelling "symlink farm manager" didn't
resonate well. So alter the documentation to double down on this use
case in which people clearly find a lot of value, whilst maintaining
the position that there are other use cases, and also not forgetting
the history of Stow's origins.

Summary by CodeRabbit

• Documentation
  • Reframed product description from “symlink farm manager” to a “dotfile organizer,” emphasizing symlink mirroring into a home (or target) directory.
  • Clarified usage for managing dotfiles and configuration files, while noting continued support for software installations.
  • Updated examples, terminology, and narrative to focus on dotfiles; added guidance on version control integration.
  • Refreshed manuals and help text for clearer workflows and paths.
  • No functional or API changes; behavior remains the same.

[coderabbitai]

Walkthrough

The changes rewrite project descriptions to center on dotfile/config management instead of software package “symlink farms.” Updates span README, manuals, inline docs, and metadata, with examples and terminology adjusted. No code, APIs, or control flow changed. A minor formatting tweak was added in AGENTS.md.

Changes

Cohort / File(s)	Summary of changes
Concept docs (dotfiles framing) AGENTS.md, README.md, doc/stow.texi	Reframed Stow as a dotfile/config organizer; updated overviews, examples, terminology, and historical narrative; added one blank line in AGENTS.md. No functional edits.
CLI/manpage text bin/stow.in	Updated NAME/DESCRIPTION and examples to dotfiles-centric language; retained commands/options unchanged.
Library POD/docs lib/Stow.pm.in	Adjusted NAME/DESCRIPTION docs to dotfiles-oriented wording; no code or API changes.
Project metadata META.json, META.yml	Changed abstract from “manage farms of symbolic links” to “organize dotfiles and configuration files.”

Sequence Diagram(s)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fix automake portability error and add basic AI agent config #132 — Also touches AGENTS.md; likely connected via documentation scope around agents/wording.

Poem

I hop through symlinks, neat and light,
From dotfiles burrows into night.
A tidy tree, my secret warren,
Home paths mapped, no cables foreign.
With gentle paws I place each link—
Organized burrows, quick as a wink. 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title clearly indicates that the PR reorients Stow’s focus based on its primary use case, which aligns with the extensive documentation updates emphasizing dotfile management. It is a concise, single-sentence description that matches the main changes without unnecessary detail. Teammates scanning the history can readily understand the intent of this update.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch new-narrative

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cab9789 and 4b92739.

📒 Files selected for processing (7)

• AGENTS.md (2 hunks)
• META.json (1 hunks)
• META.yml (1 hunks)
• README.md (2 hunks)
• bin/stow.in (3 hunks)
• doc/stow.texi (5 hunks)
• lib/Stow.pm.in (2 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

{bin/**/*.in,lib/**/*.in}

📄 CodeRabbit inference engine (AGENTS.md)

{bin/**/*.in,lib/**/*.in}: Edit only the .in source files (e.g., bin/stow.in, bin/chkstow.in, lib/Stow.pm.in, lib/Stow/Util.pm.in) and never the generated files
All program source files must end in .in and are preprocessed by Makefile before execution

Files:

• bin/stow.in
• lib/Stow.pm.in

bin/*.in

📄 CodeRabbit inference engine (AGENTS.md)

CLI entry points should be implemented in bin/stow.in and bin/chkstow.in (frontend scripts)

Files:

• bin/stow.in

lib/Stow.pm.in

📄 CodeRabbit inference engine (AGENTS.md)

Core stow/unstow logic and methods (plan_stow, plan_unstow, process_tasks, get_conflicts) belong in lib/Stow.pm.in

Files:

• lib/Stow.pm.in

🧠 Learnings (4)

📚 Learning: 2025-10-07T21:34:39.260Z

Learnt from: CR
PR: aspiers/stow#0
File: AGENTS.md:0-0
Timestamp: 2025-10-07T21:34:39.260Z
Learning: Applies to lib/Stow.pm.in : Core stow/unstow logic and methods (plan_stow, plan_unstow, process_tasks, get_conflicts) belong in lib/Stow.pm.in

Applied to files:

• bin/stow.in
• lib/Stow.pm.in
• README.md
• AGENTS.md

📚 Learning: 2025-10-07T21:34:39.261Z

Learnt from: CR
PR: aspiers/stow#0
File: AGENTS.md:0-0
Timestamp: 2025-10-07T21:34:39.261Z
Learning: Applies to lib/Stow/Util.pm.in : Utility functions (e.g., join_paths, parent, canon_path, adjust_dotfile) belong in lib/Stow/Util.pm.in

Applied to files:

• bin/stow.in

📚 Learning: 2025-10-07T21:34:39.261Z

Learnt from: CR
PR: aspiers/stow#0
File: AGENTS.md:0-0
Timestamp: 2025-10-07T21:34:39.261Z
Learning: Safe: Never delete files, directories, or links in stow directories; ensure target tree is always rebuildable

Applied to files:

• README.md

📚 Learning: 2025-10-07T21:34:39.260Z

Learnt from: CR
PR: aspiers/stow#0
File: AGENTS.md:0-0
Timestamp: 2025-10-07T21:34:39.260Z
Learning: Applies to {bin/**/*.in,lib/**/*.in} : All program source files must end in .in and are preprocessed by Makefile before execution

Applied to files:

• AGENTS.md

🔇 Additional comments (15)

META.json (1)

2-2: LGTM!

The abstract accurately reflects Stow's primary use case for organizing dotfiles and configuration files. This change aligns consistently with the broader documentation updates across the PR.

META.yml (1)

2-2: LGTM!

The abstract update matches META.json and accurately describes Stow's primary use case. The consistency across metadata files is appropriate.

AGENTS.md (2)

8-18: LGTM!

The updated overview clearly positions Stow as a dotfile organizer while maintaining flexibility for software package management. The examples using ~/dotfiles/vim and ~/dotfiles/zsh are practical and relatable for the primary use case.

---

32-33: LGTM!

The added blank line improves readability by providing visual separation before the numbered list.

lib/Stow.pm.in (2)

22-22: LGTM!

The NAME field now accurately reflects Stow's primary purpose of organizing dotfiles and configuration files.

---

36-45: LGTM!

The updated DESCRIPTION section effectively communicates Stow's primary dotfiles use case with clear examples (~/dotfiles/vim, ~/dotfiles/zsh), while acknowledging its capability for software package management. The explanation is well-balanced and informative.

bin/stow.in (3)

3-3: LGTM!

The header comment now accurately describes Stow's primary purpose.

---

26-26: LGTM!

The NAME field correctly reflects Stow's repositioned focus on dotfiles and configuration files.

---

38-58: LGTM!

The updated DESCRIPTION section effectively positions Stow for its primary dotfiles management use case while maintaining historical context. The emphasis on version control integration (git) is particularly relevant for modern dotfiles workflows. The explanation of how modern package managers have largely replaced Stow for software installation provides good context without diminishing Stow's value for its primary use case.

README.md (2)

11-13: LGTM!

The opening description clearly establishes Stow as a dotfile organizer using symlink tree mirroring, which accurately reflects its primary use case.

---

39-45: LGTM!

The updated section effectively positions dotfiles management as Stow's primary use case, with appropriate emphasis on version control integration. The acknowledgment that Stow can still be used for software package installations maintains flexibility without diluting the main message.

doc/stow.texi (4)

18-18: LGTM!

The version description now correctly identifies Stow as "a program for organizing dotfiles and configuration files."

---

64-64: LGTM!

The subtitle clearly communicates Stow's primary purpose.

---

85-87: LGTM!

The top-level description succinctly explains Stow's dotfiles organization approach using symlink tree mirroring.

---

132-199: LGTM!

The extensively rewritten Introduction section effectively repositions Stow around its primary dotfiles use case. The changes are particularly strong:

1. Practical examples: The ~/dotfiles/vim/.vimrc → ~/.vimrc examples are clear and relatable
2. Version control integration: Appropriately emphasizes git and version control workflows
3. Historical context: Maintains respect for Stow's origins while clearly indicating modern package managers have largely replaced it for software installation
4. Balanced perspective: Acknowledges Stow can still be used for directory-based software installations

The documentation now accurately reflects where users find the most value in Stow today.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}