[Stow-devel] Feature suggestion: .stow-rename

[Danielle McLean]

Although Stow's main use is the installation and control of separate
software packages, usually in /usr/local, it's also popular as a way
of managing dotfiles in your home directory, as discussed in
http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html

However, under standard Stow behaviour, this use case means that your
packages must contain only hidden files, like this (where ~/dotfiles
is the stow directory):

~/dotfiles
├── vim
│   ├── .config
│   ├── .gvimrc
│   ├── .ideavimrc
│   └── .vimrc
└── zsh
    ├── .config
    └── .zshenv

Typically it is significantly preferable for your package contents to
be visible, and to that end I suggest an extension to Stow: the
.stow-rename file. A file called .stow-rename may be placed in the
root directory of each package - it is a text file in the format:

stow_name => target_name
stow_name_2 => target_name_2

(This format was chosen as it closely resembles a Perl hash - which is
also what's used to store the rename information in my implementation.
c: )

If a .stow-rename file exists, then Stow performs a two-way mapping of
the paths within the package directory and the paths within the target
directory. In particular, the symbolic link to the file "stow_name"
will instead be given the name "target_name" when it is created in the
target directory. If stow_name is a directory, then the directory
created by tree unfolding is also renamed to "target_name"
accordingly.

This capability can then be used to create clean, visible dotfiles
packages like so:

$ tree ~/dotfiles
~/dotfiles
├── vim
│   ├── .stow-rename
│   ├── config
│   │   └── vim
│   │       ├── ftplugin
│   │       │   ├── crontab.vim
│   │       │   └── html.vim
│   │       └── vimrc
│   ├── gvimrc
│   ├── ideavimrc
│   └── vimrc
└── zsh
    ├── .stow-rename
    ├── config
    └── zshenv

$ cat ~/dotfiles/vim/.stow-rename
config => .config
gvimrc => .gvimrc
ideavimrc => .ideavimrc
vimrc => .vimrc

$ readlink ~/.config/vim
../dotfiles/vim/config/vim

I have implemented this feature in my own copy of Stow, which may be
found at https://github.com/00dani/dot-stow , and there are additional
examples of its use in all of my dot-* repos:
https://github.com/00dani?tab=repositories&q=dot-

A possible extension to this feature would be allowing
$ENVIRONMENT_VARIABLES to appear in the .stow-rename file. This would
enable true XDG support for individual packages:

config => $XDG_CONFIG_HOME

However even with only static names I think the feature has merit, and
I would recommend it be considered for addition to Stow upstream.
Thoughts?