### Install Stow with Custom Run-time Prefix

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Install Stow with a specific run-time prefix, for example, to install into '/usr/local/stow/stow' but run out of '/usr/local'.

```shell
make install prefix=/usr/local/stow/stow
```

--------------------------------

### Install Stow via Autotools

Source: https://github.com/aspiers/stow/blob/master/GEMINI.md

Install Stow using the Autotools build system. This method also installs documentation in multiple formats and allows specifying an installation prefix.

```bash
./configure --prefix=/usr/local
make install
```

--------------------------------

### Complete Dotfiles Management Example

Source: https://context7.com/aspiers/stow/llms.txt

A comprehensive example demonstrating the workflow for managing dotfiles using GNU Stow and Git.

```APIDOC
## Complete Dotfiles Management Example

### Description
This section outlines a full workflow for managing dotfiles using GNU Stow and Git, covering initial setup, configuration, and updates across multiple machines.

### Initial Setup

1.  **Create dotfiles repository:**
    ```bash
    mkdir -p ~/dotfiles
    cd ~/dotfiles
    git init
    ```

2.  **Create package directories:** Mirror your home directory structure for each application's configuration.
    ```bash
    mkdir -p ~/dotfiles/vim ~/dotfiles/zsh ~/dotfiles/git ~/dotfiles/tmux
    ```

3.  **Move existing configurations into packages:**
    ```bash
    mv ~/.vimrc vim/.vimrc
    mv ~/.vim vim/.vim
    mv ~/.zshrc zsh/.zshrc
    mv ~/.gitconfig git/.gitconfig
    mv ~/.tmux.conf tmux/.tmux.conf
    ```
    Alternatively, use the `--adopt` option after creating empty package directories:
    ```bash
    cd ~/dotfiles
    stow --adopt vim zsh git tmux
    ```

4.  **Create `.stowrc` for convenience:**
    ```bash
    cat > ~/dotfiles/.stowrc << 'EOF'
    --dir=~/dotfiles
    --target=~
    --dotfiles
    --ignore='README.*'
    --ignore='\.git.*'
    EOF
    ```

### Stow Operations

1.  **Stow all packages:**
    ```bash
    cd ~/dotfiles
    stow vim zsh git tmux
    ```

2.  **Add to version control:**
    ```bash
    git add -A
    git commit -m "Initial dotfiles setup"
    git remote add origin git@github.com:user/dotfiles.git
    git push -u origin main
    ```

### New Machine Setup

1.  **Clone the repository:**
    ```bash
    git clone git@github.com:user/dotfiles.git ~/dotfiles
    ```

2.  **Stow packages:**
    ```bash
    cd ~/dotfiles
    stow vim zsh git tmux
    ```

### Updating Configurations

1.  **Edit configuration files:** Make changes directly in your home directory (e.g., `~/.vimrc`). Stow will automatically update the symlinks if the source files are within a stowed package.

2.  **Commit and push changes:**
    ```bash
    cd ~/dotfiles
    git add -A
    git commit -m "Update vim config"
    git push
    ```

3.  **On other machines, pull and restow:**
    ```bash
    cd ~/dotfiles
    git pull
    stow -R vim  # Restow to pick up changes/removals
    ```

### Key Concepts

*   **Symbolic Link Farm Manager:** Stow creates symbolic links from a central directory (`stow` directory) to their target locations, preserving the original directory structure.
*   **Dotfiles Management:** Ideal for organizing configuration files (`.bashrc`, `.vimrc`, etc.) that are typically hidden in the home directory.
*   **Cross-Machine Synchronization:** Easily maintain consistent configurations across multiple computers by versioning your dotfiles with Git.
*   **Per-Application Configuration:** Keep configurations for different applications separate within their respective Stow packages.
*   **Version Control Integration:** The Stow directory can be a Git repository, allowing for easy tracking of configuration changes.
*   **Tree Folding:** Minimizes the number of symlinks created by linking directories instead of individual files where possible.
*   **`--adopt` Option:** Simplifies the initial setup by importing existing configuration files into Stow packages.
*   **`.stow` Marker Files:** Allow multiple Stow directories to coexist in a single target directory.
*   **Ignore Lists:** Provide fine-grained control over which files and directories are stowed.
```

--------------------------------

### Install Stow via Autotools

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

Install Stow using the Autotools build system. This method allows specifying the installation prefix and typically installs documentation in multiple formats.

```bash
# Via Autotools (installs docs in multiple formats)
./configure --prefix=/usr/local
make install
```

--------------------------------

### Build PDF Manual

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Build the PDF version of the manual if you have LaTeX and texinfo installed.

```shell
make pdf
```

--------------------------------

### Install Stow via Autotools

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Install Stow using the Autotools build system after configuration and make.

```shell
make install
```

--------------------------------

### Install Stow via Module::Build

Source: https://github.com/aspiers/stow/blob/master/GEMINI.md

Install Stow using the CPAN-style Module::Build system. This involves configuring, building, and then installing the package.

```bash
./configure && make
perl Build.PL
./Build install
```

--------------------------------

### Install Stow via Module::Build

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

Install Stow using the CPAN-style Module::Build system. This involves configuring, building, and then installing the package.

```bash
# Via Module::Build (CPAN-style)
./configure && make
perl Build.PL
./Build install
```

--------------------------------

### Install Stow via Module::Build

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Install Stow using the Module::Build system after running 'perl Build.PL'.

```shell
./Build install
```

--------------------------------

### Configure and Build Stow with Autotools

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Standard procedure to configure and build Stow using Autotools before installation.

```shell
./configure && make
```

--------------------------------

### Configure Stow with Autotools

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Configure Stow for your system using the Autotools build system. Use --prefix to specify an installation path.

```shell
./configure
```

--------------------------------

### Configure Stow with Custom Installation Prefix

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Specify a custom installation prefix other than /usr/local when configuring Stow with Autotools.

```shell
./configure --prefix=PATH
```

--------------------------------

### Perl Module API: Stow

Source: https://context7.com/aspiers/stow/llms.txt

Example of creating and using a Stow instance in Perl.

```APIDOC
## Perl Module API: Stow

### Description
This section demonstrates how to use the `Stow` Perl module to manage dotfiles and configurations.

### Create a new Stow instance
```perl
my $stow = Stow->new(
    dir      => '/home/user/dotfiles',  # stow directory (required)
    target   => '/home/user',           # target directory (required)
    verbose  => 2,                       # verbosity level 0-5
    simulate => 0,                       # dry-run mode
    dotfiles => 1,                       # handle dot- prefix
    adopt    => 0,                       # adopt existing files
    'no-folding' => 0,                   # disable tree folding
    ignore   => [qr/\.git/, qr/~$/],    # ignore patterns
    override => [qr/^bin/],              # override patterns
    defer    => [qr/^man/],              # defer patterns
);
```

### Plan stow operations
```perl
# Plan stow operations (doesn't execute yet)
$stow->plan_stow('vim', 'zsh', 'git');
```

### Plan unstow operations
```perl
# Plan unstow operations
$stow->plan_unstow('old-config');
```

### Check for conflicts
```perl
# Check for conflicts before executing
my %conflicts = $stow->get_conflicts();
if (%conflicts) {
    for my $action (keys %conflicts) {
        for my $pkg (keys %{$conflicts{$action}}) {
            print "Conflicts for $action $pkg:\n";
            print "  - $_
" for @{$conflicts{$action}{$pkg}};
        }
    }
    die "Conflicts detected, aborting\n";
}
```

### Execute planned operations
```perl
# Execute all planned operations
$stow->process_tasks();
```

### Get list of planned tasks
```perl
# Get list of planned tasks
my @tasks = $stow->get_tasks();
for my $task (@tasks) {
    print "$task->{action} $task->{type}: $task->{path}\n";
    print "  -> $task->{source}\n" if $task->{source};
}
```
```

--------------------------------

### Stow a package

Source: https://context7.com/aspiers/stow/llms.txt

Use this command to install packages by creating symlinks from the stow directory to the target directory. Specify the package name to stow.

```bash
cd ~/dotfiles
stow vim
```

```bash
stow vim zsh git tmux
```

```bash
stow -d ~/dotfiles -t ~ vim
```

```bash
export STOW_DIR=~/dotfiles
stow vim zsh
```

```bash
stow -S vim -S zsh
```

--------------------------------

### Get List of Planned Tasks (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Retrieve a list of all tasks that have been planned for execution, including their action, type, and paths.

```perl
my @tasks = $stow->get_tasks();
for my $task (@tasks) {
    print "$task->{action} $task->{type}: $task->{path}\n";
    print "  -> $task->{source}\n" if $task->{source};
}
```

--------------------------------

### Get Canonical Absolute Path (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Resolve symbolic links and normalize the path to get its absolute, canonical form.

```perl
my $canon = canon_path('~/dotfiles');
# Result: /home/user/dotfiles
```

--------------------------------

### Get Parent Directory Path (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Extract the parent directory path from a given file or directory path.

```perl
my $parent_dir = parent('/home/user/dotfiles/vim/.vimrc');
# Result: /home/user/dotfiles/vim
```

--------------------------------

### Configure Stow with Autotools and Custom Perl Module Directory

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Configure Stow when the Perl module installation directory is not in @INC. This ensures the stow executable can locate Perl modules.

```shell
eval `perl -V:siteprefix`
./configure --prefix=$siteprefix && make
```

--------------------------------

### Generate Stow Test Coverage Report

Source: https://github.com/aspiers/stow/blob/master/CONTRIBUTING.md

Generate a test coverage report for Stow using Devel::Cover. Ensure Devel::Cover is installed before running this command. The report will be generated in HTML format.

```shell
make coverage
```

--------------------------------

### Initialize Dotfiles Repository (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

Set up a new directory for managing dotfiles, initialize it as a git repository, and create package directories.

```bash
mkdir -p ~/dotfiles
cd ~/dotfiles
git init

# Create package directories mirroring home directory structure
mkdir -p vim zsh git tmux
```

--------------------------------

### Configure and Build Stow

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

Standard commands to configure the build for your system and then build all targets. 'make' must be run after editing any `.in` files.

```bash
./configure    # Configure for your system
make           # Build all targets (required after editing .in files)
make watch     # Auto-rebuild on changes (recommended during development)
```

--------------------------------

### Clone and Stow on New Machine (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

Clone the dotfiles repository on a new machine and then use Stow to link the configurations to the home directory.

```bash
git clone git@github.com:user/dotfiles.git ~/dotfiles
cd ~/dotfiles
stow vim zsh git tmux
```

--------------------------------

### Build Stow with Module::Build

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Initiate the build process for Stow using Module::Build.

```shell
perl Build.PL
```

--------------------------------

### Run All Tests with Prove

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

Utilize the 'prove' command to run individual test files or the entire test suite. This is a convenient way to manage test execution.

```bash
# Run with prove
prove t/stow.t
prove          # Run all tests
```

--------------------------------

### Create Stow Configuration File (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

Create a `.stowrc` file in the stow directory to define default options, such as the stow directory, target directory, and ignore patterns.

```bash
cat > ~/dotfiles/.stowrc << 'EOF'
--dir=~/dotfiles
--target=~
--dotfiles
--ignore='README.*'
--ignore='\.git.*'
EOF
```

--------------------------------

### Generate Build Files from Git

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Run this command in the source directory to generate configure and Makefile when building from a git repository.

```shell
autoreconf -iv
```

--------------------------------

### Run All Stow Tests with Prove

Source: https://github.com/aspiers/stow/blob/master/GEMINI.md

Utilize the 'prove' command to run tests. You can run a specific test file or all tests in the suite.

```bash
prove t/stow.t
prove          # Run all tests
```

--------------------------------

### Commit Dotfiles to Version Control (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

Add all dotfiles and stow configurations to git, commit them, and set up a remote repository for pushing.

```bash
git add -A
git commit -m "Initial dotfiles setup"
git remote add origin git@github.com:user/dotfiles.git
git push -u origin main
```

--------------------------------

### Adopt Existing Files with Stow (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

Use Stow's `--adopt` option to automatically move existing configuration files into their designated package directories within the stow directory.

```bash
# Or use --adopt to automate (after creating empty package dirs)
mkdir -p ~/dotfiles/{vim,zsh,git,tmux}
cd ~/dotfiles
stow --adopt vim zsh git tmux
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

Execute the complete test suite for Stow. This can be done using 'make check' or 'make test'.

```bash
# Run full test suite
make check
# or
make test
```

--------------------------------

### Working with .in files

Source: https://github.com/aspiers/stow/blob/master/CLAUDE.md

When editing source files, modify the '.in' files (e.g., bin/stow.in, lib/Stow.pm.in) and then run 'make' or 'make watch' to regenerate the actual source files before testing.

```bash
1. Edit `bin/stow.in`, `lib/Stow.pm.in`, etc. (NOT the generated
   versions)
2. Run `make` or `make watch`
3. Test the generated files in `bin/` and `lib/`
```

--------------------------------

### Create and Configure Stow Instance (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Instantiate Stow with various options to control its behavior, such as directory paths, verbosity, and file handling. Use this for programmatic management of dotfiles.

```perl
my $stow = Stow->new(
    dir      => '/home/user/dotfiles',  # stow directory (required)
    target   => '/home/user',           # target directory (required)
    verbose  => 2,                       # verbosity level 0-5
    simulate => 0,                       # dry-run mode
    dotfiles => 1,                       # handle dot- prefix
    adopt    => 0,                       # adopt existing files
    'no-folding' => 0,                   # disable tree folding
    ignore   => [qr/\.git/, qr/~$/],    # ignore patterns
    override => [qr/^bin/],              # override patterns
    defer    => [qr/^man/],              # defer patterns
);
```

--------------------------------

### Automatically Rebuild Stow Source Files

Source: https://github.com/aspiers/stow/blob/master/CONTRIBUTING.md

Run this command to automatically execute 'make' in an infinite loop every second. This is useful for testing modifications to source files, ensuring the pre-processed versions are always up-to-date.

```shell
make watch
```

--------------------------------

### Run Individual Test with Debug Verbosity

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

To run a specific test file, set the PERL5LIB environment variable and then execute the test script with Perl. Use TEST_VERBOSE for debug output.

```bash
# Run individual test (must set PERL5LIB first)
export PERL5LIB=t:bin:lib
perl t/stow.t

# Run with debug verbosity
TEST_VERBOSE=4 perl t/stow.t
```

--------------------------------

### Update and Commit Dotfiles Changes (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

After editing configuration files, stage and commit the changes to version control.

```bash
cd ~/dotfiles
git add -A
git commit -m "Update vim config"
git push
```

--------------------------------

### Configure Defaults with .stowrc Resource Files

Source: https://context7.com/aspiers/stow/llms.txt

Resource files like .stowrc can be used to configure default options for stow. These files can be placed globally (~/.stowrc) or per-directory for specific stow operations.

```bash
# ~/.stowrc - Global defaults for all stow operations
--dotfiles
--ignore='.*~'
--ignore='\.swp$'
--ignore='\.DS_Store'
--ignore='\.git'
--verbose=1
```

```bash
# ~/dotfiles/.stowrc - Directory-specific defaults
--dir=~/dotfiles
--target=~
--dotfiles
```

```bash
# Support for environment variables and tilde expansion
--target=$HOME
--dir=~/dotfiles
```

```bash
# Escaped special characters
--target="$HOME/dir with spaces"
--ignore=\$backup\$
```

```bash
# Example complete .stowrc for dotfiles management
# ~/.stowrc:
--dir=~/dotfiles
--target=~ 
--dotfiles
--ignore='README.*'
--ignore='LICENSE.*'
--ignore='\.git.*'
--ignore='.*\.md$'
```

--------------------------------

### Run Full Stow Test Suite

Source: https://github.com/aspiers/stow/blob/master/GEMINI.md

Execute the complete test suite for Stow. This can be done using either 'make check' or 'make test'.

```bash
make check
# or
make test
```

--------------------------------

### Configure Stow with Program Prefix

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Add an extra prefix to program names during configuration.

```shell
./configure --program-prefix=PREFIX
```

--------------------------------

### Run Individual Stow Test

Source: https://github.com/aspiers/stow/blob/master/CLAUDE.md

To run a specific test file, set the PERL5LIB environment variable to include the necessary directories (t, bin, lib) and then execute the test file with Perl. This is useful for debugging specific test cases.

```bash
# Run individual test (must set PERL5LIB first)
export PERL5LIB=t:bin:lib
perl t/stow.t
```

--------------------------------

### Run Stow Test Suite

Source: https://github.com/aspiers/stow/blob/master/CONTRIBUTING.md

Execute the entire test suite for GNU Stow. Ensure you are in the root of the repository tree before running.

```shell
make check
```

--------------------------------

### Run Individual Stow Test

Source: https://github.com/aspiers/stow/blob/master/GEMINI.md

To run a specific test file, ensure PERL5LIB is set correctly to include necessary directories, then execute the test file with Perl. This is useful for debugging specific test cases.

```bash
export PERL5LIB=t:bin:lib
perl t/stow.t
```

--------------------------------

### Adopt existing files into stow package

Source: https://context7.com/aspiers/stow/llms.txt

Use the --adopt option to bring existing files in the target directory under Stow management. The existing file is moved into the package directory, and a symlink is created.

```bash
mkdir -p ~/dotfiles/bash
stow --adopt bash
```

```bash
cd ~/dotfiles
stow --adopt bash
git diff
git add -A && git commit
```

```bash
stow -n -v --adopt bash
```

--------------------------------

### Run All Stow Tests with Prove

Source: https://github.com/aspiers/stow/blob/master/CONTRIBUTING.md

Execute the entire Stow test suite using the 'prove' test runner. Note that 'prove' may interfere with the TEST_VERBOSE variable.

```shell
prove
```

--------------------------------

### User-Wide Ignore Lists with .stow-global-ignore

Source: https://context7.com/aspiers/stow/llms.txt

The .stow-global-ignore file provides user-wide default ignore patterns that are applied to all packages unless a package-local .stow-local-ignore file exists.

```bash
# ~/.stow-global-ignore
# Applied to all packages without .stow-local-ignore

# Version control systems
RCS
.+,v
CVS
\.#.+
\.cvsignore
\.svn
_darcs
\.hg
\.git
\.gitignore
\.gitmodules

# Editor files
.+~
#.*#
\.swp$

# OS-specific files
\.DS_Store
Thumbs\.db

# Common documentation that shouldn't be stowed
^/README.*
^/LICENSE.*
^/COPYING
^/CHANGELOG.*
```

--------------------------------

### Move Existing Configs into Stow Packages (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

Manually move existing configuration files from the home directory into their respective package directories within the stow directory.

```bash
mv ~/.vimrc vim/.vimrc
mv ~/.vim vim/.vim
mv ~/.zshrc zsh/.zshrc
mv ~/.gitconfig git/.gitconfig
mv ~/.tmux.conf tmux/.tmux.conf
```

--------------------------------

### Generate Test Coverage Report

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

Generate a test coverage report using 'make coverage'. This requires the Devel::Cover Perl module and will open an HTML report.

```bash
# Test coverage
make coverage  # Requires Devel::Cover
# Opens HTML report at cover_db/coverage.html
```

--------------------------------

### Generate Test Coverage Report

Source: https://github.com/aspiers/stow/blob/master/GEMINI.md

Generate a test coverage report using 'make coverage'. This requires the Devel::Cover Perl module and will open an HTML report.

```bash
make coverage  # Requires Devel::Cover
# Opens HTML report at cover_db/coverage.html
```

--------------------------------

### Set Perl Search Path for Testing

Source: https://github.com/aspiers/stow/blob/master/CONTRIBUTING.md

Configure Perl's search path to include necessary directories for running tests. This command should be executed from the root of the repository tree.

```shell
export PERL5LIB=t:bin:lib
```

--------------------------------

### Working with .in files for Stow Development

Source: https://github.com/aspiers/stow/blob/master/GEMINI.md

When modifying Stow's source code, always edit the '.in' files (e.g., bin/stow.in, lib/Stow.pm.in) and then run 'make' or 'make watch' to regenerate the actual source files before testing.

```bash
# 1. Edit bin/stow.in, lib/Stow.pm.in, etc. (NOT the generated versions)
# 2. Run `make` or `make watch`
# 3. Test the generated files in bin/ and lib/
```

--------------------------------

### Simulate stow operation

Source: https://context7.com/aspiers/stow/llms.txt

Use the -n and -v flags to simulate stowing a package without making any changes. This shows which symlinks would be created or modified.

```bash
stow -n -v vim
```

--------------------------------

### Run Stow Tests with Prove

Source: https://github.com/aspiers/stow/blob/master/CONTRIBUTING.md

Utilize the 'prove' test runner to execute Stow tests. This alternative runner offers additional features compared to direct Perl execution.

```shell
prove t/stow.t
```

--------------------------------

### Configure Stow with Program Suffix

Source: https://github.com/aspiers/stow/blob/master/INSTALL.md

Add an extra suffix to program names during configuration.

```shell
./configure --program-suffix=SUFFIX
```

--------------------------------

### Stow dotfiles with prefix handling

Source: https://context7.com/aspiers/stow/llms.txt

Use the --dotfiles option to enable special handling for files prefixed with 'dot-' in the package directory, allowing them to be symlinked as dotfiles in the target directory.

```bash
stow --dotfiles bash
```

```bash
stow --dotfiles emacs
```

--------------------------------

### Join Path Components (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Combine multiple path components into a single, properly formatted path string.

```perl
my $full_path = join_paths('/home/user', 'dotfiles', 'vim');
# Result: /home/user/dotfiles/vim
```

--------------------------------

### Run Individual Stow Test File with Verbosity

Source: https://github.com/aspiers/stow/blob/master/CONTRIBUTING.md

Execute a specific test file with increased verbosity using the TEST_VERBOSE environment variable. Higher values provide more detailed output.

```shell
TEST_VERBOSE=4 perl t/chkstow.t
```

--------------------------------

### Stow All Packages (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

Apply stow to all specified package directories, creating symlinks in the target directory.

```bash
cd ~/dotfiles
stow vim zsh git tmux
```

--------------------------------

### Save and Restore Current Working Directory (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Temporarily change the current working directory and then restore it to its original location using saved path information.

```perl
use POSIX qw(getcwd);
my $cwd = getcwd();
chdir('/some/other/dir');
# ... do work ...
restore_cwd($cwd);
```

--------------------------------

### Combine unstow and stow operations

Source: https://context7.com/aspiers/stow/llms.txt

Use -D and -S flags together to first remove old symlinks and then create new ones, useful for upgrading packages.

```bash
stow -D emacs-24 -S emacs-25
```

--------------------------------

### Run Individual Stow Test File

Source: https://github.com/aspiers/stow/blob/master/CONTRIBUTING.md

Execute a specific test file within the Stow test suite. Ensure the PERL5LIB environment variable is set correctly beforehand.

```shell
perl t/chkstow.t
```

--------------------------------

### Pull Updates and Restow (Bash)

Source: https://context7.com/aspiers/stow/llms.txt

On other machines, pull the latest changes from the remote repository and then restow the affected packages to apply updates.

```bash
cd ~/dotfiles
git pull
stow -R vim  # Restow to pick up changes/removals
```

--------------------------------

### Edit and Regenerate Source Files

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

When modifying Stow's source code, always edit the `.in` files (e.g., `bin/stow.in`, `lib/Stow.pm.in`) and then run `make` or `make watch` to generate the executable versions before testing.

```bash
1. Edit `bin/stow.in`, `lib/Stow.pm.in`, etc. (NOT the generated versions)
2. Run `make` or `make watch`
3. Test the generated files in `bin/` and `lib/`
```

--------------------------------

### Run a Single Test from a Specific Subtest

Source: https://github.com/aspiers/stow/blob/master/AGENTS.md

To isolate and run a single test case, particularly from a specific subtest within a larger test file, set PERL5LIB and use TEST_VERBOSE with the Perl interpreter.

```bash
export PERL5LIB=t:bin:lib
TEST_VERBOSE=4 perl t/stow.t
```

--------------------------------

### Managing Multiple Stow Directories

Source: https://context7.com/aspiers/stow/llms.txt

Stow supports multiple stow directories that can coexist, allowing for better organization and collaboration. Use .stow marker files to designate directories as stow directories and .nonstow to protect specific directories.

```bash
# Create multiple stow directories that can coexist
mkdir -p /usr/local/stow
mkdir -p /usr/local/stow-perl
mkdir -p /usr/local/stow-local

# Mark each as a stow directory
touch /usr/local/stow/.stow
touch /usr/local/stow-perl/.stow
touch /usr/local/stow-local/.stow

# Stow from different directories
cd /usr/local/stow && stow emacs
cd /usr/local/stow-perl && stow perl-5.34
cd /usr/local/stow-local && stow my-scripts

# Protect directories from stow with .nonstow marker
touch /usr/local/important-dir/.nonstow

# Each stow directory can have its own .stowrc
# /usr/local/stow-perl/.stowrc:
--dir=/usr/local/stow-perl
--target=/usr/local
--override=bin
--override=man
```

--------------------------------

### Control Stow Behavior with --defer and --override

Source: https://context7.com/aspiers/stow/llms.txt

Use --defer to prevent overwriting existing symlinks and --override to force overwrites. These options control how stow handles files that are already stowed to different packages.

```bash
# Defer to existing symlinks (don't overwrite if already stowed elsewhere)
stow --defer='man' --defer='info' mypackage
# Skips man/ and info/ if already stowed from another package
```

```bash
# Override existing symlinks (force overwrite)
stow --override='bin' --override='man' mypackage
# Replaces existing symlinks in bin/ and man/
```

```bash
# Combined pattern with regex
stow --defer='man|info' mypackage
```

```bash
# Use case: Perl modules with shared man pages
stow --override='man' --override='bin' cpan-module
```

```bash
# Set in .stowrc for specific stow directory
# ~/dotfiles/perl-extras/.stowrc:
# --override=bin
# --override=man
# --ignore='perllocal.pod'
# --ignore='\.packlist'
```

--------------------------------

### Dry-run unstow operation

Source: https://context7.com/aspiers/stow/llms.txt

Simulate unstowing a package using -n and -v flags to see which symlinks would be removed without actually deleting them.

```bash
stow -n -v -D vim
```

--------------------------------

### Restow a package

Source: https://context7.com/aspiers/stow/llms.txt

Use the -R flag to restow a package, which first unstows and then stows it again. This is helpful for cleaning up obsolete symlinks after updating package contents.

```bash
stow -R vim
```

```bash
stow -R vim zsh git
```

```bash
stow -R vim -D old-config -S new-config
```

```bash
stow -v -R vim
```

--------------------------------

### Perl Module API: Stow::Util

Source: https://context7.com/aspiers/stow/llms.txt

Utility functions for custom scripts using Stow.

```APIDOC
## Perl Module API: Stow::Util

### Description
Utility functions used by Stow that can be imported for custom scripts.

### Usage
```perl
use Stow::Util qw(
    debug set_debug_level error
    join_paths parent canon_path restore_cwd
    adjust_dotfile unadjust_dotfile
);
```

### Functions

#### `set_debug_level(level)`
Sets the debug verbosity level (0-5).

```perl
# Set debug verbosity level (0-5)
set_debug_level(3);
```

#### `debug(level, message)` or `debug(level, indent, message)`
Outputs debug messages (only shown if `level` is greater than or equal to the set debug level).

```perl
# Output debug messages
debug(1, "Operation performed");       # level 1 message
debug(3, 2, "Detailed trace info");    # level 3, indented 2 levels
```

#### `error(message, ...)`
Outputs a formatted error message and terminates the script.

```perl
# Error handling
error("Cannot find package: %s", $package_name);
```

#### `join_paths(path1, path2, ...)`
Joins multiple path components into a single path.

```perl
# Path manipulation
my $full_path = join_paths('/home/user', 'dotfiles', 'vim');
# Result: /home/user/dotfiles/vim
```

#### `parent(path)`
Returns the parent directory of a given path.

```perl
my $parent_dir = parent('/home/user/dotfiles/vim/.vimrc');
# Result: /home/user/dotfiles/vim
```

#### `canon_path(path)`
Returns the canonical absolute path, resolving symlinks.

```perl
# Get canonical absolute path (resolves symlinks)
my $canon = canon_path('~/dotfiles');
# Result: /home/user/dotfiles
```

#### `adjust_dotfile(filename)`
Converts a filename by prepending a dot (e.g., `dot-bashrc` to `.bashrc`).

```perl
# Dotfile name conversion
my $target_name = adjust_dotfile('dot-bashrc');
# Result: .bashrc
```

#### `unadjust_dotfile(filename)`
Converts a filename by removing the leading dot (e.g., `.bashrc` to `dot-bashrc`).

```perl
my $pkg_name = unadjust_dotfile('.bashrc');
# Result: dot-bashrc
```

#### `restore_cwd(original_cwd)`
Restores the current working directory to a previously saved path.

```perl
# Save and restore current working directory
use POSIX qw(getcwd);
my $cwd = getcwd();
chdir('/some/other/dir');
# ... do work ...
restore_cwd($cwd);
```
```

--------------------------------

### Import and Use Stow::Util Functions (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Import specific utility functions from the Stow::Util module for use in custom scripts, such as path manipulation and debugging.

```perl
use Stow::Util qw(
    debug set_debug_level error
    join_paths parent canon_path restore_cwd
    adjust_dotfile unadjust_dotfile
);
```

--------------------------------

### Package-Specific Ignore Lists with .stow-local-ignore

Source: https://context7.com/aspiers/stow/llms.txt

The .stow-local-ignore file allows you to specify package-specific ignore patterns using Perl regular expressions. This file should be placed within the package directory.

```bash
# ~/dotfiles/vim/.stow-local-ignore
# Perl regex patterns, one per line

# Ignore README files
^/README.*

# Ignore license files
^/LICENSE.*
^/COPYING

# Ignore all git-related files
\.git
\.gitignore
\.gitmodules

# Ignore backup and temp files
.+~
\.swp$
#.*#

# Ignore build artifacts
^/Makefile
^/configure
\.o$

# Ignore test directories
^/test
^/t/

# Comments are supported
# Blank lines are ignored
```

--------------------------------

### Execute Planned Stow Tasks (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Process all operations that have been planned using `plan_stow` or `plan_unstow`.

```perl
$stow->process_tasks();
```

--------------------------------

### Check for Conflicts (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Retrieve a hash of detected conflicts before processing tasks. This helps prevent unintended overwrites or issues.

```perl
my %conflicts = $stow->get_conflicts();
if (%conflicts) {
    for my $action (keys %conflicts) {
        for my $pkg (keys %{$conflicts{$action}}) {
            print "Conflicts for $action $pkg:\n";
            print "  - $_\n" for @{$conflicts{$action}{$pkg}};
        }
    }
    die "Conflicts detected, aborting\n";
}
```

--------------------------------

### Plan Stow Operations (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Plan stow or unstow operations for specified packages without executing them immediately. This allows for pre-execution checks.

```perl
$stow->plan_stow('vim', 'zsh', 'git');
```

```perl
$stow->plan_unstow('old-config');
```

--------------------------------

### Output Debug Messages (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Generate debug messages with specified levels and indentation. Messages are only displayed if the message level meets or exceeds the set debug level.

```perl
debug(1, "Operation performed");       # level 1 message
```

```perl
debug(3, 2, "Detailed trace info");    # level 3, indented 2 levels
```

--------------------------------

### Handle Errors with Stow::Util (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Use the `error` function from Stow::Util to output formatted error messages and terminate the script.

```perl
error("Cannot find package: %s", $package_name);
```

--------------------------------

### Run Stow Tests with Debug Verbosity

Source: https://github.com/aspiers/stow/blob/master/GEMINI.md

Increase the verbosity of test output by setting TEST_VERBOSE to a higher level (e.g., 4) when running individual tests. This provides more detailed information for debugging.

```bash
TEST_VERBOSE=4 perl t/stow.t
```

--------------------------------

### Adjust Dotfile Name (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Convert a filename prefixed with 'dot-' into a standard dotfile name (e.g., 'dot-bashrc' to '.bashrc').

```perl
my $target_name = adjust_dotfile('dot-bashrc');
# Result: .bashrc
```

--------------------------------

### Unstow (remove symlinks) a package

Source: https://context7.com/aspiers/stow/llms.txt

Use the -D flag to remove symlinks for a package from the target directory. This is useful for uninstalling configurations managed by Stow.

```bash
stow -D vim
```

```bash
stow -D vim zsh git
```

--------------------------------

### Run Stow Tests with Debug Verbosity

Source: https://github.com/aspiers/stow/blob/master/CLAUDE.md

Increase the verbosity of test output by setting TEST_VERBOSE to a higher level (e.g., 4) when running individual tests with Perl. This provides more detailed information during test execution.

```bash
# Run with debug verbosity
TEST_VERBOSE=4 perl t/stow.t
```

--------------------------------

### Check Stow Integrity with chkstow

Source: https://context7.com/aspiers/stow/llms.txt

The chkstow utility checks the integrity of the stow target directory. It can identify broken symlinks, alien files, and list all stowed packages.

```bash
# Check for broken/bogus symlinks (default mode)
chkstow -b
chkstow --badlinks
# Output:
# Bogus link: /usr/local/bin/oldcommand
```

```bash
# Check for alien files (non-symlinks that shouldn't be there)
chkstow -a
chkstow --aliens
# Output:
# Unstowed file: /usr/local/bin/manually-installed
```

```bash
# List all stowed packages
chkstow -l
chkstow --list
# Output:
# emacs
# git
# perl
# vim
```

```bash
# Specify different target directory
chkstow -t /usr/local -l
chkstow --target=/home/user -b
```

```bash
# Using STOW_DIR environment variable
export STOW_DIR=/usr/local/stow
chkstow --list
```

--------------------------------

### Disable Tree Folding with --no-folding

Source: https://context7.com/aspiers/stow/llms.txt

Use the --no-folding option to disable tree folding, which creates individual symlinks for each file instead of a single directory symlink. This is useful when multiple packages need to add files to the same directories.

```bash
# Normal behavior (with folding):
# If ~/dotfiles/vim/.vim/ is stowed, creates:
#   ~/.vim -> dotfiles/vim/.vim

# With --no-folding:
stow --no-folding vim
# Creates individual symlinks for each file:
#   ~/.vim/colors/mytheme.vim -> ../../dotfiles/vim/.vim/colors/mytheme.vim
#   ~/.vim/plugin/myplugin.vim -> ../../dotfiles/vim/.vim/plugin/myplugin.vim

# Useful when you want other packages to add files to same directories
# without requiring tree unfolding later
stow --no-folding vim
stow --no-folding vim-plugins   # Adds more files to ~/.vim/
```

--------------------------------

### Perl Module API for Programmatic Stow Operations

Source: https://context7.com/aspiers/stow/llms.txt

The Stow Perl module provides a programmatic interface for performing stow operations. This allows for custom scripting and integration with other Perl-based tools.

```perl
use Stow;

```

--------------------------------

### Set Stow Debug Level (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Configure the verbosity level for debug messages in Stow. Higher levels provide more detailed output.

```perl
set_debug_level(3);
```

--------------------------------

### Verbose stow output

Source: https://context7.com/aspiers/stow/llms.txt

Control the verbosity of the stow command using the -v or --verbose options. Higher numbers indicate more detailed output.

```bash
stow -v vim
```

```bash
stow --verbose=3 vim
```

--------------------------------

### Ignore files during stow operation

Source: https://context7.com/aspiers/stow/llms.txt

Use the --ignore option with a Perl regular expression to exclude specific files or patterns from being symlinked by Stow.

```bash
stow --ignore='\.orig$' --ignore='\.bak$' vim
```

```bash
stow --ignore='\.md$' vim
```

```bash
stow --ignore='.*~' --ignore='\.swp$' vim
```

```bash
stow --ignore='\.git' --ignore='\.DS_Store' --ignore='Thumbs\.db' vim
```

--------------------------------

### Unadjust Dotfile Name (Perl)

Source: https://context7.com/aspiers/stow/llms.txt

Convert a standard dotfile name back into the 'dot-' prefixed format used by Stow (e.g., '.bashrc' to 'dot-bashrc').

```perl
my $pkg_name = unadjust_dotfile('.bashrc');
# Result: dot-bashrc
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.