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

[Adam Spiers]

Hi Danielle,

On Sun, Oct 09, 2016 at 05:36:09PM -0400, Danielle McLean wrote:
> 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

Indeed - actually, I *only* use Stow for managing files in my $HOME :-)
Stow's home page even links directly to a mail explaining this:

  https://www.gnu.org/software/stow/
  http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html

although I also use Stow for managing *software* in my $HOME, not just
dotfiles.  This is useful for developing and testing software from the
source tree, because it bypasses the need to repackage a test version
with the distribution's underlying package manager just for testing.

Thanks for the link though!  That's a really nice blog post, and I've
added a link to it from Stow's home page.

> 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

Funnily enough, this never really bothered me personally, but I can
certainly appreciate that it might annoy others.  That's why I merged
this nice new --dotfiles feature only 5 days ago :-)

  https://github.com/aspiers/stow/pull/17

(Yes, I know that I need to make a new official release which provides
this and several other things which are currently only available via
git master ...)

> 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?

Interesting idea - thanks a lot for sharing!  I'm certainly open to
discussing this further.  My immediate thoughts are:

- When focusing specifically on the dotfiles case, where the goal is
  to "unhide" the files by removing the dot, I think that the existing
  --dotfiles implementation is nicer because it requires less work of
  the user.  I don't like that the user would have to add a new entry
  to .stow-rename every time they add a new file - this doesn't sound
  user-friendly to me.  However, if more flexibility is required in
  the way that the unhidden files are named, I'm all ears for input
  what kind of flexibility is required and how we could implement
  that.

- Regarding the use case of mapping paths for other reasons such as
  following freedesktop.org (formerly known as XDG[0]) path
  conventions, so far I have personally been mirroring the path
  hierarchies in my own repositories, e.g.

    
https://github.com/aspiers/desktop-config/tree/master/.local/share/applications

  so that when I stow this repository, stuff goes straight into my
  ~/.local/share/applications.  This works fine.

  I can understand that there might be a desire to keep the hierarchy
  within the repository "cleaner", e.g. in this example having a
  top-level "applications/" directory which would get remapped and
  stowed as ~/.local/share/applications, but I am concerned that this
  is straying into design bloat territory.  It would be a first step
  towards transitioning Stow from being a simple symlink farm manager
  towards a full-blown package manager, and I'm not sure that makes
  sense, because it could open up many cans of worms, e.g. versioning,
  dependency tracking and so on.

  Stow's value is in its simplicity, much of which comes from this
  core principle of a 1-to-1 mapping between sub-paths in the package
  directories and sub-paths in the target directory (modulo
  folding).  If you need something more sophisticated then maybe a
  better solution would be to look at Nix[1], or evaluate the possibility
  of making something like rpm or dpkg work non-root.

  That said, this is just my initial reaction on the subject, and I'm
  open to being persuaded to think otherwise.

Cheers,
Adam

[0] https://en.wikipedia.org/wiki/Freedesktop.org
[1] https://nixos.org/nix/