245dc83849
As previously noted, the old comment style was difficult to edit. It's also not idiomatic Perl style, so reformat as pod. This exposes more of the inner workings of Stow as documentation, but that shouldn't be a problem. As part of this change, remove outdated and sometimes misleading information about if/when each function throws an exception.
652 lines
22 KiB
Text
652 lines
22 KiB
Text
News file for Stow.
|
|
|
|
* Changes in version 2.3.2
|
|
|
|
*** Eliminated a spurious warning on unstowing
|
|
|
|
2.3.1 introduced a benign but annoying warning when unstowing
|
|
in certain circumstances. It looked like:
|
|
|
|
BUG in find_stowed_path? Absolute/relative mismatch between Stow dir X and path Y
|
|
|
|
This was caused by erroneous logic, and has now been fixed.
|
|
|
|
*** Improved debug output
|
|
|
|
Extra output resulting from use of the -v / --verbose flag
|
|
now appears in a more logical and understandable way.
|
|
|
|
*** Janitorial tasks
|
|
|
|
Users are not substantially affected by these changes.
|
|
|
|
***** Added some more information from the web page to the README
|
|
|
|
***** Made some improvements to the documentation
|
|
|
|
***** Improve readability of source code
|
|
|
|
Quite a few extra details have been added in comments to clarify
|
|
how the code works. Some variable names have also been
|
|
improved. The comments of many Stow class methods have been
|
|
converted into Perl POD format.
|
|
|
|
***** Added a =CONTRIBUTING.md= file
|
|
|
|
***** Add a =watch= target to =Makefile=
|
|
|
|
=make watch= provides easy continual pre-processing during
|
|
development, which reduces the risk of debugging the wrong code.
|
|
|
|
***** Removed texinfo.tex from the distribution
|
|
|
|
This eliminates existing and future bit-rot.
|
|
|
|
***** Updated aclocal.m4 from 1.15.1 to 1.16.5
|
|
|
|
This mostly just updates copyright notices to 2021, and URLs to https.
|
|
|
|
***** Replace broken gmane links with links to lists.gnu.org
|
|
|
|
[[https://lars.ingebrigtsen.no/2020/01/06/whatever-happened-to-news-gmane-org/][gmane has been dead for quite a while.]]
|
|
|
|
***** Improve support for navigating / editing source via emacs
|
|
|
|
******* Support source navigation in emacs via [[https://github.com/jacktasia/dumb-jump][dumb-jump]].
|
|
|
|
******* Configure cperl-mode to match existing coding style.
|
|
|
|
*** Various maintainer tweaks
|
|
|
|
Further improved the release process and its documentation in
|
|
various minor ways.
|
|
|
|
* Changes in version 2.3.1
|
|
|
|
*** Remove dependencies on Hash::Merge and Clone::Choose
|
|
|
|
stow 2.3.0 added external runtime dependencies on Hash::Merge and
|
|
Clone::Choose. Historically stow hasn't had runtime dependencies
|
|
other than Perl itself, which is a useful property if you're
|
|
managing the installation of Perl using stow; the bootstrapping
|
|
instructions in stow's manual would need updating to describe how
|
|
to install these two modules (and any dependencies they have now
|
|
or in the future) as well.
|
|
|
|
However, Hash::Merge is much more general than stow actually
|
|
needs, so replace the merge() call with a few lines of equivalent
|
|
code -- this avoids the external dependencies, and is clearer than
|
|
the merge() call.
|
|
|
|
Many thanks to Adam Sampson for this patch!
|
|
|
|
https://lists.gnu.org/archive/html/bug-stow/2019-06/msg00001.html
|
|
|
|
*** Fix an issue with the test suite
|
|
|
|
t/cli.t was not testing with the right Perl executable, as
|
|
reported here:
|
|
|
|
https://rt.cpan.org/Ticket/Display.html?id=129944
|
|
|
|
Thanks to Slaven Rezic for spotting this and reporting it!
|
|
|
|
*** Various maintainer tweaks
|
|
|
|
Improved the release process and its documentation in various
|
|
minor ways.
|
|
|
|
* Changes in version 2.3.0
|
|
|
|
*** New features / changes in behaviour
|
|
|
|
***** New --dotfiles option
|
|
|
|
Enable special handling for "dotfiles" (files or folders whose name
|
|
begins with a period) in the package directory. If this option is
|
|
enabled, Stow will add a preprocessing step for each file or folder
|
|
whose name begins with "dot-", and replace the "dot-" prefix in the
|
|
name by a period ("."). This is useful when Stow is used to manage
|
|
collections of dotfiles, to avoid having a package directory full
|
|
of hidden files.
|
|
|
|
For example, suppose we have a package containing two files,
|
|
stow/dot-bashrc and stow/dot-emacs.d/init.el. With this option,
|
|
Stow will create symlinks from .bashrc to stow/dot-bashrc and from
|
|
.emacs.d/init.el to stow/dot-emacs.d/init.el. Any other files,
|
|
whose name does not begin with "dot-", will be processed as usual.
|
|
|
|
Thanks to Joris Vankerschaver for this feature!
|
|
|
|
***** Shell-like expansion in .stowrc files
|
|
|
|
For options within .stowrc files which describe file paths, "~" can
|
|
be included to expand to the current value of $HOME, and
|
|
environment variables can be referenced e.g. via "$FOO" or
|
|
"${FOO}". To prevent expansion, escape with a backslash.
|
|
|
|
Thanks a lot to Charles LeDoux for his diligent work on this
|
|
feature!
|
|
|
|
***** chkstow now honours the $STOW_DIR environment variable
|
|
|
|
The stow script already honoured the $STOW_DIR environment
|
|
variable. Now chkstow does too, for consistency.
|
|
|
|
***** Stow now has a non-zero exit code if option parsing failed
|
|
|
|
Thanks to Brice Waegeneire for reporting this.
|
|
|
|
*** License upgraded from GPL version 2 to version 3
|
|
|
|
Copyright and license notices were also added to the headers of
|
|
various files in accordance with GNU guidelines.
|
|
|
|
*** Documentation fixes and enhancements
|
|
|
|
***** Remove dependency on unmaintained texi2html
|
|
|
|
The dependency on the ancient and unmaintained texi2html for
|
|
building the single-page HTML version of the manual has been
|
|
removed, since it was difficult to get running on most distros
|
|
other than openSUSE.
|
|
|
|
Instead use the more modern "makeinfo --html --no-split" approach.
|
|
Rules have been kept for posterity in the Makefile for the old
|
|
approach and also an "in-between" approach based on texi2any;
|
|
however these are not triggered by default. Run
|
|
|
|
make manual-single-html-all
|
|
|
|
to compare the three versions.
|
|
|
|
***** Fixed naming of man page
|
|
|
|
The title of the generated man page was previously ending up as
|
|
something like:
|
|
|
|
IO::FILE=IO(0XA719C0)(1)
|
|
|
|
Thanks to @Corin-EU on GitHub highlighting this and proposing a
|
|
fix.
|
|
|
|
***** Convert README and INSTALL to Markdown
|
|
|
|
They are now named README.md and INSTALL.md, and render nicely
|
|
when viewed via git hosting services which support Markdown.
|
|
|
|
***** Update documentation to reflect more modern use cases
|
|
|
|
The README.md, stow(8) man page, and info manual have been updated
|
|
to de-emphasise the package management use, since these days almost
|
|
everyone prefers to use modern package managers such as rpm / dpkg
|
|
/ Nix for (system-wide) package management.
|
|
|
|
To compensate, more popular modern use cases for Stow have been
|
|
added, such as management of dotfiles and software compiled in the
|
|
user's $HOME directory.
|
|
|
|
***** Miscellaneous documentation fixes
|
|
|
|
- Various typos were fixed.
|
|
|
|
- The documentation for --verbose was updated to indicate that
|
|
verbosity levels now go up to 5.
|
|
|
|
- Erroneous glob examples in the --ignore documentation were fixed.
|
|
|
|
- The abbreviation "regex" was removed from the info manual for
|
|
consistency.
|
|
|
|
- INSTALL.md now also documents how to build directly from git.
|
|
|
|
*** Fixes for bugs, tests, and other technical debt
|
|
|
|
***** Add Docker files for convenient testing across multiple Perl versions
|
|
|
|
This is the first release which has been tested across 5 different
|
|
versions of Perl prior to release! The versions are:
|
|
|
|
perl-5.22.2
|
|
perl-5.20.3
|
|
perl-5.18.4
|
|
perl-5.16.3
|
|
perl-5.14.4
|
|
|
|
Thanks to Charles LeDoux for this!
|
|
|
|
***** Set up continuous testing via Travis CI
|
|
|
|
This means that the test suite will be automatically run on any
|
|
pull requests submitted to GitHub, as well as "make distcheck"
|
|
and "./Build distcheck".
|
|
|
|
***** Add Coveralls integration with GitHub
|
|
|
|
This means that test coverage analysis will be automatically be run
|
|
on any pull requests submitted to GitHub.
|
|
|
|
***** Miscellaneous improvements to the test suite
|
|
|
|
These include proper testing of the distinct impact of ~/.stowrc
|
|
and .stowrc in the directory from which Stow is invoked.
|
|
|
|
***** Fix for test suite on Cygwin
|
|
|
|
Thanks to Lucas Theisen for this fix!
|
|
|
|
***** aclocal.m4 was updated using aclocal 1.15.1.
|
|
|
|
***** Miscellaneous fixes to the build and distribution process
|
|
|
|
***** Improve handling of directories with unusual names
|
|
|
|
Various fixes for corner cases where directories are named "0"
|
|
or begin with a space character, or where STOW_DIR is empty.
|
|
|
|
Thanks to Cuong Manh Le for highlighting some of the issues and
|
|
proposing fixes!
|
|
|
|
* Changes in version 2.2.2
|
|
|
|
*** @VERSION@ substitution was set up for the Stow::Util module.
|
|
|
|
* Changes in version 2.2.1
|
|
|
|
Version 2.2.1 was not released since it was rejected by pause.perl.org
|
|
due to Stow::Util missing $VERSION.
|
|
|
|
*** Small improvements to documentation
|
|
|
|
***** The README has been revamped.
|
|
|
|
***** Some index points have been added to the manual.
|
|
|
|
***** Some typos were fixed.
|
|
|
|
***** @VERSION@ substitution was fixed in the stow(8) man page.
|
|
|
|
*** Fix Perl warnings
|
|
|
|
Stow no longer emits "v-string in use/require non-portable" and
|
|
"Possible precedence issue with control flow operator" warnings
|
|
with newer Perl versions. See https://savannah.gnu.org/bugs/?36478
|
|
and http://lists.gnu.org/archive/html/bug-stow/2014-06/msg00000.html
|
|
for full details.
|
|
|
|
*** Fix "Undefined subroutine &main::error" error
|
|
|
|
See https://rt.cpan.org/Public/Bug/Display.html?id=75349 for details.
|
|
|
|
*** Failed system calls now include error description
|
|
|
|
This should make errors easier to understand.
|
|
|
|
*** Default ignore list now ignores top-level README.*, LICENSE.*, and COPYING
|
|
|
|
These files are by definition specific to a given package, so if
|
|
they exist in the top-level directory, they should not be stowed.
|
|
|
|
*** Correctly handle the stow/target directories as non-canonical paths
|
|
|
|
Fix the case discovered by Hiroyuki Iwatsuki where stowing fails if
|
|
the stow / target directories are non-canonical paths. For
|
|
example, on FreeBSD /home is a symlink pointing to 'usr/home', so
|
|
running with the stow directory as /home/user/local/stow and the
|
|
target directory as /home/user/local previously resulted in the
|
|
stow directory path being calculated as
|
|
../../../usr/home/user/local/stow relative to the target.
|
|
|
|
See https://lists.gnu.org/archive/html/bug-stow/2013-04/msg00000.html for details.
|
|
|
|
*** Fix stowing of relative links when --no-folding is used.
|
|
|
|
With a tree like this:
|
|
|
|
.
|
|
|-- stow
|
|
| `-- pkg
|
|
| `-- lib
|
|
| |-- itk-current -> itk4.0.0
|
|
| `-- itk4.0.0
|
|
| `-- libitk4.0.0.so
|
|
`-- target
|
|
`-- lib
|
|
|-- itk4.0.0 -> ../../stow/pkg/lib/itk4.0.0
|
|
`-- libfoo-1.2.3.so
|
|
|
|
stowing pkg with the --no-folding option resulted in itk-current
|
|
being "unpacked":
|
|
|
|
.
|
|
`-- target
|
|
`-- lib
|
|
|-- itk-current
|
|
| `-- libitk4.0.0.so -> ../../../stow/pkg/lib/itk-current/libitk4.0.0.so
|
|
|-- itk4.0.0
|
|
| `-- libitk4.0.0.so -> ../../../stow/pkg/lib/itk4.0.0/libitk4.0.0.so
|
|
`-- libfoo-1.2.3.so
|
|
|
|
This commit fixes it so that it gets stowed as a symlink:
|
|
|
|
.
|
|
`-- target
|
|
`-- lib
|
|
...
|
|
|-- itk-current -> ../../stow/pkg/lib/itk-current
|
|
...
|
|
|
|
Thanks to Gabriele Balducci for reporting this problem:
|
|
|
|
https://lists.gnu.org/archive/html/help-stow/2014-09/msg00000.html
|
|
|
|
*** Internal code cleanups
|
|
|
|
***** aclocal was updated.
|
|
|
|
***** automake files were removed.
|
|
|
|
***** Trailing whitespace was removed.
|
|
|
|
***** Comments were added.
|
|
|
|
***** Debug messages were improved.
|
|
|
|
* Changes in version 2.2.0
|
|
|
|
*** New --no-folding option
|
|
|
|
Disables folding of newly stowed directories when stowing, and
|
|
refolding of newly foldable directories when unstowing.
|
|
|
|
*** Remove -a option (--adopt still available)
|
|
|
|
As --adopt is the only option which allows stow to modify files, it
|
|
is considered potentially dangerous (especially for stow package
|
|
directories which are not managed by a version control system).
|
|
Therefore it seems prudent to require a bit more effort from the
|
|
user to enable this option, minimising the change of enabling it
|
|
via a typo.
|
|
|
|
*** Improve error message when stow package is not found.
|
|
|
|
The error message displayed a path to the missing stow package
|
|
which was relative to the target directory rather than the cwd,
|
|
which was confusing for the user.
|
|
|
|
*** Test suite improvements
|
|
|
|
The test suite has been tightened up slightly.
|
|
|
|
*** Documentation improvements
|
|
|
|
Various fixes and cosmetic improvements have been made in the manual.
|
|
|
|
*** Remove "There are no outstanding operations to perform" warning.
|
|
|
|
* Changes in version 2.1.3
|
|
|
|
*** New --adopt / -a option
|
|
|
|
This allows plain files in the target to be "adopted" into the
|
|
package being stowed. See the manual has more details.
|
|
|
|
*** ./configure now checks for Perl modules required by the test suite.
|
|
|
|
* Changes in version 2.1.2
|
|
|
|
Many thanks to Stefano Lattarini for help with numerous autoconf and
|
|
automake issues which are addressed in this release.
|
|
|
|
*** Significantly improve the handling of --with-pmdir.
|
|
|
|
***** Calculation of the default value for --with-pmdir is now done safely in Perl.
|
|
|
|
Previously non-POSIX-compliant shells could cause issues.
|
|
|
|
***** The output of ./configure and make are now much more helpful.
|
|
|
|
***** The Makefile will now check whether pmdir is in Perl's built-in @INC.
|
|
|
|
If not, it will insert a
|
|
|
|
use lib "...";
|
|
|
|
line into the generated stow script to ensure that it can always
|
|
locate the Perl modules without needing to manually set PERL5LIB.
|
|
|
|
***** Updated INSTALL and HOWTO-RELEASE accordingly.
|
|
|
|
*** ./configure now aborts if Perl isn't found.
|
|
|
|
*** Ensured the ChangeLog is up-to-date when making a new distribution.
|
|
|
|
*** Fixed bug with `make clean' removing files which the user may not be able to rebuild.
|
|
|
|
* Changes in version 2.1.1
|
|
|
|
*** Fixed bug where ./configure --with-pmdir=X was ineffectual.
|
|
|
|
*** Calculated the correct default value for pmdir based on the local Perl installation.
|
|
|
|
*** Fixed some automake issues (thanks to Stefano Lattarini for spotting these!)
|
|
|
|
*** Improved various bits of documentation.
|
|
|
|
* Changes in version 2.1.0
|
|
|
|
*** Major refactoring of code into separate Stow and Stow::Util Perl modules.
|
|
|
|
*** Added support for ignore list files.
|
|
|
|
*** Added support for CPAN-style installation and distribution via Module::Build.
|
|
|
|
*** Introduced `make test' target and significantly tightened up test suite.
|
|
|
|
*** Very large number of code and documentation fixes (over 80 commits since version 2.0.1).
|
|
|
|
*** The '--conflicts' option has been removed.
|
|
|
|
Stow will always show conflicts if they are found during the scanning
|
|
phase.
|
|
|
|
*** Improved debugging output.
|
|
|
|
*** Converted man page to POD format.
|
|
|
|
*** Include PDF, and both split- and single-page HTML versions of manual in the distribution.
|
|
|
|
*** Fixed code style consistency issues.
|
|
|
|
*** Running configure from outside the source tree now works.
|
|
|
|
*** `make distcheck' now works.
|
|
|
|
* Changes in version 2.0.1
|
|
|
|
*** Defer operations until all potential conflicts have been assessed.
|
|
|
|
We do this by traversing the installation image(s) and recording the
|
|
actions that need to be performed. Redundant actions are factored out,
|
|
e.g., we don't want to create a link that we will later remove in order to
|
|
create a directory. Benefits of this approach:
|
|
|
|
1. Get to see _all_ the conflicts that are blocking an installation:
|
|
you don't have to deal with them one at a time.
|
|
2. No operations are be performed if _any_ conflicts are detected:
|
|
a failed stow will not leave you with a partially installed
|
|
package.
|
|
3. Minimises the set of operations that need to be performed.
|
|
4. Operations are executed as a batch which is much faster
|
|
This can be an advantage when upgrading packages on a live system
|
|
where you want to minimise the amount of time when the package is
|
|
unavailable.
|
|
|
|
*** The above fixes the false conflict problem mentioned in the info file.
|
|
|
|
*** It also fixes the two bugs mentioned in the man page.
|
|
|
|
*** Multiple stow directories will now cooperate in folding/unfolding.
|
|
|
|
*** Conflict messages are more uniform and informative.
|
|
|
|
*** Verbosity and tracing is more extensive and uniform.
|
|
|
|
*** Implemented option parsing via Getopt::Long.
|
|
|
|
*** Default command line arguments set via '.stowrc' and '~/.stowrc' files.
|
|
|
|
Contents of these files are parsed as though they occurred first on
|
|
the command line.
|
|
|
|
*** Support multiple actions per invocation.
|
|
|
|
In order for this to work, we had to add a new (optional) command line arg
|
|
(-S) to specify packages to stow. For example, to update an installation
|
|
of emacs you can now do
|
|
|
|
stow -D emacs-21.3 -S emacs-21.4a
|
|
|
|
which will replace emacs-21.3 with emacs-21.4a.
|
|
You can mix and match any number of actions, e.g.,
|
|
|
|
stow -S p1 p2 -D p3 p4 -S p5 -R p6
|
|
|
|
will unstow p3, p4 and p6, then stow p1, p2, p5 and p6.
|
|
|
|
*** New (repeatable) command line arg: --ignore='<regex>'
|
|
|
|
This suppresses operating on a file matching the regex (suffix),
|
|
e.g.
|
|
|
|
--ignore='~' --ignore='\.#.*'
|
|
|
|
will ignore emacs and CVS backup files (suitable for ~/.stowrc file).
|
|
|
|
(I opted for Perl regular expressions because they are more
|
|
powerful and easier to implement).
|
|
|
|
*** New (repeatable) command line arg: --defer='<regex>'
|
|
|
|
This defers stowing a file matching the regex (prefix) if that file
|
|
is already stowed to a different package, e.g.,
|
|
|
|
--defer='man' --defer='info'
|
|
|
|
will cause stow to skip over pre-existing man and info pages.
|
|
|
|
Equivalently, you could use --defer='man|info' since the argument
|
|
is just a Perl regex.
|
|
|
|
*** New (repeatable) command line arg: --override='<regex>'
|
|
|
|
This forces a file matching the regex (prefix) to be stowed even if
|
|
the file is already stowed to a different package, e.g.
|
|
|
|
--override='man' --override='info'
|
|
|
|
will unstow any pre-existing man and info pages that would conflict
|
|
with the file we are trying to stow.
|
|
|
|
Equivalently, you could use --override='man|info' since the
|
|
argument is just a Perl regex.
|
|
|
|
*** The above gives the ability to manage packages with common content.
|
|
|
|
For example, man pages that are shared by a number of CPAN
|
|
packages. Using multiple stow directories and .stowrc files can
|
|
also simplify things. In our setup we use the standard
|
|
/usr/local/stow directory for packages to be installed in
|
|
/usr/local. Since we install a large number of extra Perl packages
|
|
(currently about 300) we use an additional stow directory:
|
|
/usr/local/stow/perl-5.8.8-extras. Both stow directories contain a
|
|
'.stow' file so that they collaborate appropriately. I then use
|
|
the following .stowrc file in /usr/local/stow/perl-5.8.8-extras
|
|
|
|
--dir=/usr/local/stow/perl-5.8.8-extras
|
|
--target=/usr/local
|
|
--override=bin
|
|
--override=man
|
|
--ignore='perllocal\.pod'
|
|
--ignore='\.packlist'
|
|
--ignore='\.bs'
|
|
|
|
When I stow packages from there, they automatically override any
|
|
man pages and binaries that may already have been stowed by another
|
|
package or by the core perl-5.8.8 installation. For example, if
|
|
you want to upgrade the Test-Simple package, you need to override
|
|
all the man pages that would have been installed by the core
|
|
package. If you are upgrading CPAN, you will also have to override
|
|
the pre-existing cpan executable.
|
|
|
|
*** By default, search less aggressively for invalid symlinks when unstowing.
|
|
|
|
That is, we only search for bad symlinks in the directories
|
|
explicitly mentioned in the installation image, and do not dig down
|
|
into other subdirs. Digging down into other directories can be
|
|
very time consuming if you have a really big tree (like with a
|
|
couple of Oracle installations lying around). In general the old
|
|
behaviour is only necessary when you have really stuffed up your
|
|
installation by deleting a directory that has already been stowed.
|
|
Doing that on a live system is somewhat crazy and hopefully rare.
|
|
We provide an option '-p|--compat' to enable the old behaviour for
|
|
those needing to patch up mistakes.
|
|
|
|
*** New chkstow utility for checking the integrity of the target directory.
|
|
|
|
*** Implement a test suite and support code.
|
|
|
|
This was built before implementing any of the extra features so I
|
|
could more easily check for equivalent functionality. The initial
|
|
code base had to be refactored substantially to allow for testing.
|
|
The test suite is not exhaustive, but it should provide enough to
|
|
check for regressions.
|
|
|
|
* Changes in version 1.3.3
|
|
|
|
*** Now requires Perl 5.005 or later
|
|
|
|
*** Initially empty directories are not removed anymore
|
|
|
|
*** Removed buggy fastcwd (we use POSIX::getcwd instead)
|
|
|
|
*** Fixed bug when the common Parent of Target dir and Stow dir was "/"
|
|
|
|
*** Fixed bug when handling directories named "0"
|
|
|
|
*** Stow now only warns the user if a directory is unreadable during unstowing.
|
|
|
|
* Changes in version 1.3:
|
|
|
|
*** Added --restow option.
|
|
|
|
*** Fixed handling of slashes in package names.
|
|
|
|
*** Expanded configure-time search for Perl binary.
|
|
|
|
* Changes in version 1.2:
|
|
|
|
*** Dependency on `pwd' removed.
|
|
|
|
*** Perl 4 compatibility fixes.
|
|
|
|
*** Manual expanded even more.
|
|
|
|
* Changes in version 1.1:
|
|
|
|
*** Long and short options now accepted.
|
|
|
|
*** Manual expanded.
|
|
|
|
*** `make clean' removes stow (which is generated from stow.in).
|
|
|
|
* Initial public release (v1.0) of Stow.
|
|
|
|
* emacs local variables
|
|
Local Variables:
|
|
mode: org
|
|
org-export-with-toc: nil
|
|
org-export-with-author: nil
|
|
org-toc-odd-levels-only: t
|
|
org-blank-before-new-entry: ((heading . auto) (plain-list-item . auto))
|
|
End:
|