00dani/stow
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Fix old descriptions of Stow (#22)

Browse source 
De-emphasise the package management aspects, since these days
almost everyone prefers to use modern package managers such as
rpm / dpkg / Nix for (system-wide) package management.

Also include more popular modern use cases for Stow such as management
of dotfiles and software compiled in the user's $HOME directory.

Fixes #22: https://github.com/aspiers/stow/issues/22
This commit is contained in:
Adam Spiers 2016-11-21 14:56:26 +00:00
parent a70c60e888
commit 72ef83cebd
4 changed files with 112 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
README.md
View file

@ -4,19 +4,54 @@
README for GNU Stow README for GNU Stow
=================== ===================
This is GNU Stow, a symlink farm manager program which takes distinct This README describes GNU Stow. This is not the definitive
packages of software and/or data located in separate directories on documentation for Stow; for that, see the [info
the filesystem, and makes them appear to be installed in the same manual](https://www.gnu.org/software/stow/manual/).
place. For example, `/usr/local/bin` could contain symlinks to files
within `/usr/local/stow/emacs/bin`, `/usr/local/stow/perl/bin` etc., and Stow is a symlink farm manager program which takes distinct sets
of software and/or data located in separate directories on the
filesystem, and makes them all appear to be installed in a single
directory tree.
Originally Stow was born to address the need to administer, upgrade,
install, and remove files in independent software packages without
confusing them with other files sharing the same file system space.
For instance, many years ago it used to be common to compile programs
such as Perl and Emacs from source and install them in `/usr/local`.
By using Stow, `/usr/local/bin` could contain symlinks to files within
`/usr/local/stow/emacs/bin`, `/usr/local/stow/perl/bin` etc., and
likewise recursively for any other subdirectories such as `.../share`, likewise recursively for any other subdirectories such as `.../share`,
`.../man`, and so on. `.../man`, and so on.
This is particularly useful for keeping track of system-wide and While this is useful for keeping track of system-wide and per-user
per-user installations of software built from source, but can also installations of software built from source, in more recent times
facilitate a more controlled approach to management of configuration software packages are often managed by more sophisticated package
files in the user's home directory, especially when coupled with management software such as
version control systems. [`rpm`](https://en.wikipedia.org/wiki/Rpm_(software)),
[`dpkg`](https://en.wikipedia.org/wiki/Dpkg), and
[Nix](https://en.wikipedia.org/wiki/Nix_package_manager) / [GNU
Guix](https://en.wikipedia.org/wiki/GNU_Guix), or language-native
package managers such as Ruby's
[`gem`](https://en.wikipedia.org/wiki/RubyGems), Python's
[`pip`](https://en.wikipedia.org/wiki/Pip_(package_manager)),
Javascript's [`npm`](https://en.wikipedia.org/wiki/Npm_(software)),
and so on.
However Stow is still used not only for software package management,
but also for other purposes, such as facilitating [a more controlled
approach to management of configuration files in the user's home
directory](http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html),
especially when [coupled with version control
systems](http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html).
Stow was inspired by Carnegie Mellon's Depot program, but is
substantially simpler and safer. Whereas Depot required database files
to keep things in sync, Stow stores no extra state between runs, so
there's no danger (as there was in Depot) of mangling directories when
file hierarchies don't match the database. Also unlike Depot, Stow will
never delete any files, directories, or links that appear in a Stow
directory (e.g., `/usr/local/stow/emacs`), so it's always possible
to rebuild the target tree (e.g., `/usr/local`).
Stow is implemented as a combination of a Perl script providing a CLI Stow is implemented as a combination of a Perl script providing a CLI
interface, and a backend Perl module which does most of the work. interface, and a backend Perl module which does most of the work.

58
bin/stow.in
View file

@ -1,6 +1,6 @@
#!@PERL@ #!@PERL@
# GNU Stow - manage the installation of multiple software packages # GNU Stow - manage farms of symbolic links
# Copyright (C) 1993, 1994, 1995, 1996 by Bob Glickstein # Copyright (C) 1993, 1994, 1995, 1996 by Bob Glickstein
# Copyright (C) 2000, 2001 Guillaume Morin # Copyright (C) 2000, 2001 Guillaume Morin
# Copyright (C) 2007 Kahlil Hodgson # Copyright (C) 2007 Kahlil Hodgson
@ -21,7 +21,7 @@
=head1 NAME =head1 NAME
stow - software package installation manager stow - manage farms of symbolic links
=head1 SYNOPSIS =head1 SYNOPSIS
@ -29,33 +29,34 @@ stow [ options ] package ...
=head1 DESCRIPTION =head1 DESCRIPTION
This manual page describes GNU Stow @VERSION@, a program for managing This manual page describes GNU Stow @VERSION@. This is not the
the installation of software packages. This is not the definitive definitive documentation for Stow; for that, see the accompanying info
documentation for stow; for that, see the info manual. manual, e.g. by typing C<info stow>.
Stow is a tool for managing the installation of multiple software Stow is a symlink farm manager which takes distinct sets of software
packages in the same run-time directory tree. One historical and/or data located in separate directories on the filesystem, and
difficulty of this task has been the need to administer, upgrade, makes them all appear to be installed in a single directory tree.
install, and remove files in independent packages without confusing
them with other files sharing the same filesystem space. For instance,
it is common to install Perl and Emacs in F</usr/local>. When one
does so, one winds up (as of Perl 4.036 and Emacs 19.22) with the
following files in F</usr/local/man/man1>: F<a2p.1>; F<ctags.1>;
F<emacs.1>; F<etags.1>; F<h2ph.1>; F<perl.1>; and F<s2p.1>. Now
suppose it's time to uninstall Perl. Which man pages get removed?
Obviously F<perl.1> is one of them, but it should not be the
administrator's responsibility to memorize the ownership of individual
files by separate packages.
The approach used by Stow is to install each package into its own Originally Stow was born to address the need to administer, upgrade,
tree, then use symbolic links to make it appear as though the files install, and remove files in independent software packages without
are installed in the common tree. Administration can be performed in confusing them with other files sharing the same file system space.
the package's private tree in isolation from clutter from other For instance, many years ago it used to be common to compile programs
packages. Stow can then be used to update the symbolic links. The such as Perl and Emacs from source. By using Stow, F</usr/local/bin>
structure of each private tree should reflect the desired structure in could contain symlinks to files within F</usr/local/stow/emacs/bin>,
the common tree; i.e. (in the typical case) there should be a F<bin> F</usr/local/stow/perl/bin> etc., and likewise recursively for any
directory containing executables, a F<man/man1> directory containing other subdirectories such as F<.../share>, F<.../man>, and so on.
section 1 man pages, and so on.
While this is useful for keeping track of system-wide and per-user
installations of software built from source, in more recent times
software packages are often managed by more sophisticated package
management software such as rpm, dpkg, and Nix / GNU Guix, or
language-native package managers such as Ruby's gem, Python's pip,
Javascript's npm, and so on.
However Stow is still used not only for software package management,
but also for other purposes, such as facilitating a more controlled
approach to management of configuration files in the user's home
directory, especially when coupled with version control systems.
Stow was inspired by Carnegie Mellon's Depot program, but is Stow was inspired by Carnegie Mellon's Depot program, but is
substantially simpler and safer. Whereas Depot required database files substantially simpler and safer. Whereas Depot required database files
@ -66,6 +67,9 @@ will never delete any files, directories, or links that appear in a
Stow directory (e.g., F</usr/local/stow/emacs>), so it's always Stow directory (e.g., F</usr/local/stow/emacs>), so it's always
possible to rebuild the target tree (e.g., F</usr/local>). possible to rebuild the target tree (e.g., F</usr/local>).
Stow is implemented as a combination of a Perl script providing a CLI
interface, and a backend Perl module which does most of the work.
=head1 TERMINOLOGY =head1 TERMINOLOGY
A "package" is a related collection of files and directories that A "package" is a related collection of files and directories that

59
doc/stow.texi
View file

@ -15,8 +15,7 @@
@copying @copying
This manual describes GNU Stow version @value{VERSION} This manual describes GNU Stow version @value{VERSION}
(@value{UPDATED}), a program for managing the installation of software (@value{UPDATED}), a program for managing farms of symbolic links.
packages.
Software and documentation is copyrighted by the following: Software and documentation is copyrighted by the following:
@ -82,10 +81,9 @@ approved by the Free Software Foundation.
@ifinfo @ifinfo
This manual describes GNU Stow @value{VERSION} (@value{UPDATED}), a This manual describes GNU Stow @value{VERSION} (@value{UPDATED}), a
program for managing sets of symbolic links, in order to make groups symlink farm manager which takes distinct sets of software and/or data
of related files (such as distinct packages of software, or located in separate directories on the filesystem, and makes them
configuration files) in one place in the filesystem appear to be appear to be installed in a single directory tree.
located in another place.
@end ifinfo @end ifinfo
@end ifnottex @end ifnottex
@ -131,19 +129,20 @@ Advice on changing compilation and installation parameters
@node Introduction, Terminology, Top, Top @node Introduction, Terminology, Top, Top
@chapter Introduction @chapter Introduction
Stow is a tool for managing sets of symbolic links in order to GNU Stow is a symlink farm manager which takes distinct sets of
facilitate the installation of multiple software packages, or other software and/or data located in separate directories on the
groups of related files, such as configuration files, into a single filesystem, and makes them all appear to be installed in a single
directory tree. directory tree.
Originally Stow was born to address the need to administer, upgrade, Originally Stow was born to address the need to administer, upgrade,
install, and remove files in independent software packages without install, and remove files in independent software packages without
confusing them with other files sharing the same file system space. confusing them with other files sharing the same file system space.
For instance, it used to be common to compile Perl and Emacs from For instance, many years ago it used to be common to compile programs
source and install them in @file{/usr/local}. When one does so, one such as Perl and Emacs from source and install them in
winds up with the following files@footnote{As of Perl 4.036 and Emacs @file{/usr/local}. When one does so, one winds up with the following
19.22. These are now ancient releases but the example still holds files@footnote{As of Perl 4.036 and Emacs 19.22. These are now
valid.} in @file{/usr/local/man/man1}: ancient releases but the example still holds valid.} in
@file{/usr/local/man/man1}:
@example @example
a2p.1 a2p.1
@ -171,11 +170,20 @@ tree; i.e. (in the typical case) there should be a @file{bin} directory
containing executables, a @file{man/man1} directory containing section 1 containing executables, a @file{man/man1} directory containing section 1
man pages, and so on. man pages, and so on.
In more recent times, software packages are often managed by more While this is useful for keeping track of system-wide and per-user
sophisticated package management software such as installations of software built from source, in more recent times
software packages are often managed by more sophisticated package
management software such as
@uref{https://en.wikipedia.org/wiki/Rpm_(software), @command{rpm}}, @uref{https://en.wikipedia.org/wiki/Rpm_(software), @command{rpm}},
@uref{https://en.wikipedia.org/wiki/Dpkg, @command{dpkg}}, and @uref{https://en.wikipedia.org/wiki/Dpkg, @command{dpkg}}, and
@uref{https://en.wikipedia.org/wiki/Nix_package_manager, Nix}. @uref{https://en.wikipedia.org/wiki/Nix_package_manager, Nix} /
@uref{https://en.wikipedia.org/wiki/GNU_Guix, GNU Guix}, or
language-native package managers such as
@uref{https://en.wikipedia.org/wiki/RubyGems, Ruby's @command{gem}},
@uref{https://en.wikipedia.org/wiki/Pip_(package_manager), Python's
@command{pip}}, @uref{https://en.wikipedia.org/wiki/Npm_(software),
Javascript's @command{npm}}, and so on.
However Stow is still used not only for software package management, However Stow is still used not only for software package management,
but also for other purposes, such as facilitating a more controlled but also for other purposes, such as facilitating a more controlled
approach to management of configuration files in the user's home approach to management of configuration files in the user's home
@ -184,13 +192,16 @@ especially when coupled with version control
systems@footnote{@uref{http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html}}. systems@footnote{@uref{http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html}}.
Stow was inspired by Carnegie Mellon's Depot program, but is Stow was inspired by Carnegie Mellon's Depot program, but is
substantially simpler and safer. Whereas Depot required database files substantially simpler and safer. Whereas Depot required database
to keep things in sync, Stow stores no extra state between runs, so files to keep things in sync, Stow stores no extra state between runs,
there's no danger (as there was in Depot) of mangling directories when so there's no danger (as there was in Depot) of mangling directories
file hierarchies don't match the database. Also unlike Depot, Stow will when file hierarchies don't match the database. Also unlike Depot,
never delete any files, directories, or links that appear in a Stow Stow will never delete any files, directories, or links that appear in
directory (e.g., @file{/usr/local/stow/emacs}), so it's always possible a Stow directory (e.g., @file{/usr/local/stow/emacs}), so it's always
to rebuild the target tree (e.g., @file{/usr/local}). possible to rebuild the target tree (e.g., @file{/usr/local}).
Stow is implemented as a combination of a Perl script providing a CLI
interface, and a backend Perl module which does most of the work.
For information about the latest version of Stow, you can refer to For information about the latest version of Stow, you can refer to
@uref{http://www.gnu.org/software/stow/}. @uref{http://www.gnu.org/software/stow/}.

2
lib/Stow.pm.in
View file

@ -4,7 +4,7 @@ package Stow;
=head1 NAME =head1 NAME
Stow - manage the installation of multiple software packages Stow - manage farms of symbolic links
=head1 SYNOPSIS =head1 SYNOPSIS