README.md

   1 [![Build Status](https://travis-ci.org/aspiers/stow.svg)](https://travis-ci.org/aspiers/stow)
   2 [![Coverage Status](https://coveralls.io/repos/aspiers/stow/badge.svg?branch=master&service=github)](https://coveralls.io/github/aspiers/stow?branch=master)
   3
   4 README for GNU Stow
   5 ===================
   6
   7 This README describes GNU Stow.  This is not the definitive
   8 documentation for Stow; for that, see the [info
   9 manual](https://www.gnu.org/software/stow/manual/).
  10
  11 Stow is a symlink farm manager program which takes distinct sets
  12 of software and/or data located in separate directories on the
  13 filesystem, and makes them all appear to be installed in a single
  14 directory tree.
  15
  16 Originally Stow was born to address the need to administer, upgrade,
  17 install, and remove files in independent software packages without
  18 confusing them with other files sharing the same file system space.
  19 For instance, many years ago it used to be common to compile programs
  20 such as Perl and Emacs from source and install them in `/usr/local`.
  21 By using Stow, `/usr/local/bin` could contain symlinks to files within
  22 `/usr/local/stow/emacs/bin`, `/usr/local/stow/perl/bin` etc., and
  23 likewise recursively for any other subdirectories such as `.../share`,
  24 `.../man`, and so on.
  25
  26 While this is useful for keeping track of system-wide and per-user
  27 installations of software built from source, in more recent times
  28 software packages are often managed by more sophisticated package
  29 management software such as
  30 [`rpm`](https://en.wikipedia.org/wiki/Rpm_(software)),
  31 [`dpkg`](https://en.wikipedia.org/wiki/Dpkg), and
  32 [Nix](https://en.wikipedia.org/wiki/Nix_package_manager) / [GNU
  33 Guix](https://en.wikipedia.org/wiki/GNU_Guix), or language-native
  34 package managers such as Ruby's
  35 [`gem`](https://en.wikipedia.org/wiki/RubyGems), Python's
  36 [`pip`](https://en.wikipedia.org/wiki/Pip_(package_manager)),
  37 Javascript's [`npm`](https://en.wikipedia.org/wiki/Npm_(software)),
  38 and so on.
  39
  40 However Stow is still used not only for software package management,
  41 but also for other purposes, such as facilitating [a more controlled
  42 approach to management of configuration files in the user's home
  43 directory](http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html),
  44 especially when [coupled with version control
  45 systems](http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html).
  46
  47 Stow was inspired by Carnegie Mellon's Depot program, but is
  48 substantially simpler and safer.  Whereas Depot required database files
  49 to keep things in sync, Stow stores no extra state between runs, so
  50 there's no danger (as there was in Depot) of mangling directories when
  51 file hierarchies don't match the database.  Also unlike Depot, Stow will
  52 never delete any files, directories, or links that appear in a Stow
  53 directory (e.g., `/usr/local/stow/emacs`), so it's always possible
  54 to rebuild the target tree (e.g., `/usr/local`).
  55
  56 Stow is implemented as a combination of a Perl script providing a CLI
  57 interface, and a backend Perl module which does most of the work.
  58
  59 You can get the latest information about Stow from the home page:
  60
  61     http://www.gnu.org/software/stow/
  62
  63 License
  64 -------
  65
  66 Stow is free software, licensed under the GNU General Public License,
  67 which can be found in the file [`COPYING`](COPYING).
  68
  69 Copying and distribution of this file, with or without modification,
  70 are permitted in any medium without royalty provided the copyright
  71 notice and this notice are preserved.  This file is offered as-is,
  72 without any warranty.
  73
  74 Installation
  75 ------------
  76
  77 See [`INSTALL.md`](INSTALL.md) for installation instructions.
  78
  79 Feedback
  80 --------
  81
  82 Please do send comments, questions, and constructive criticism.  The
  83 mailing lists and any other communication channels are detailed on the
  84 above home page.
  85
  86 Brief history and authorship
  87 ----------------------------
  88
  89 Stow was inspired by Carnegie Mellon's "Depot" program, but is
  90 substantially simpler.  Whereas Depot requires database files to keep
  91 things in sync, Stow stores no extra state between runs, so there's no
  92 danger (as there is in Depot) of mangling directories when file
  93 hierarchies don't match the database.  Also unlike Depot, Stow will
  94 never delete any files, directories, or links that appear in a Stow
  95 directory (e.g., `/usr/local/stow/emacs`), so it's always possible to
  96 rebuild the target tree (e.g., `/usr/local`).
  97
  98 For a high-level overview of the contributions of the main developers
  99 over the years, see [the `AUTHORS` file](AUTHORS).
 100
 101 For a more detailed history, please see the `ChangeLog` file.