Placing a .stow file in a directory tells Stow that this directory
should be considered a Stow directory. This is already
well-documented.
There was an undocumented and slightly broken feature where placing a
.nonstow file in a directory was treated in exactly the same way. The
intention was for .nonstow to cause Stow to skip stowing into and
unstowing from that directory and any of its descendants. However, it
also caused Stow to consider symlinks into any of those directories as
owned by Stow, even though that was clearly not the intention. So
separate treatment of .stow and .nonstow markers, so that while both
provide protection against Stow stowing and unstowing, only .stow
affects the symlink ownership logic in find_stowed_path() and
marked_stow_dir().
Probably no one uses the undocumented .nonstow feature, so it may make
sense to remove this in future.
Previously join_paths() was incorrectly handling absolute paths, for
example join_paths('a/b', '/c/d') would return 'a/b/c/d' rather than
'/c/d'. This was a problem when following a symlink in
find_stowed_path(), because if the symlink was not owned by Stow and
pointed to an absolute path, find_stowed_path() might accidentally
deem the link owned by Stow, if c/d was a valid path relative to the
current directory.
t/cli.t calls scripts which run with the first perl found in the
user's PATH (usually the system perl), not with the perl used for the
build, as reported here:
https://rt.cpan.org/Ticket/Display.html?id=129944
Thanks to Slaven Rezic for spotting this and reporting it!
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
.stowrc can be obtained from $HOME and/or the current working
directory; however only the $HOME case was tested before, because
during tests Stow was being run from $HOME.
So switch $TEST_DIR to an absolute path, create a new run_from/
subdirectory, and chdir to that before invoking any Stow code. This
allows us to test the behaviour of .stowrc in $HOME and run_from/
separately.
Add a new expand_tilde() function that performs tilde expansion of
strings, and corresponding unit tests:
* A ~ at the beginning of a path is expanded to the user's home
directory.
* Literal '~' can be provided with '\~'
Combine this with expand_environment() in a new expand_filepath()
function which applies all (both) required expansion functions to a
string, and use that in get_config_file_options() to expand .stowrc
options.
Add more tests to check that tilde expanded in correct places, i.e.:
* expanded for --target and --dir
* not expanded for --ignore, --defer, or --override
Update documentation on stowrc files according to this functionality
change.
Fixes#14: https://github.com/aspiers/stow/issues/14
Expand environment variables used in stowrc, as requested in
https://savannah.gnu.org/bugs/?41826
This is achieved by creating a new function expand_environment() that
replaces any substring of the form '$VAR' or '${VAR}' with contents of
environment variable $VAR. Literal '$' can be given by '\$'.
N.B. The function is only applied to the --target and --dir options,
and only for options specified in .stowrc; cli options are left
untouched.
Undefined variables are expanded to the empty string, as they would be
in normal shell parameter expansion.
Unit tests added accordingly:
- Test expand_environment():
* Expand $HOME
* Expand ${HOME}
* Expand ${WITH SPACE}
* Expand '\$HOME'. Expected is '$HOME'
* Expand ${UNDEFINED}. Expected is ''.
- Test that it's applied to the correct options.
- Test that CLI options are not expanded.
Why:
* Want to add feature to stowrc parsing.
* Missing regression test for conflicting cli and stowrc options.
This change addresses the need by:
* Add missing regression tests to rc_options.t
* Two types of tests for the two types of options possible.
* For scalar options such as --target, cli arguments should overwrite
stowrc arguments.
* For options that result in a list, such as --ignore, the arguments
from cli and stowrc files should be merged.
Why:
* Planning on developing a new feature for parsing of stowrc files.
* Need a test harness that performs initialization and clean up
* Initialization: Create directory structure that allows creation of
stowrc files without worrying about squashing existing files.
* Clean up: Remove all files created during testing.
This change addresses the need by:
* Add intialization and cleanup harness in t/rc_options.t
* Define the location to write stowrc files to in $RC_FILE
* Ensures that location $RC_FILE does not already exist.
* Calls the init_test_dirs to bootstrap directory tree.
* After all tests are run, removes $RC_FILE and the testing
directory tree.
* Add basic test of stowrc parsing to t/rc_options.t
* Provides a template of how to create and test a stowrc file.
* Newly created t/rc_options.t file added to MANIFEST
Why:
* Want to add a new feature to parsing of stowrc files.
* Need ability to write .stowrc files for testing without risk of
squashing existing files.
This change addresses the need by:
* Reusing logic in init_test_dirs
* init_test_dirs already creates new directory structure and overwrites
$HOME to point into /tmp.
* This commit changes init_test_dirs to point $HOME at the newly created
directory structure ($OUT_DIR) instead of /tmp.
* Grants ability to write .stowrc to $HOME without fear.
* Pointing $HOME at $OUT_DIR instead of /tmp also makes cleanup easier.
* Remove $OUT_DIR vs remove specific files in /tmp.
Unlike the other tests, this actually treats stow(1) as a black box
script, running it directly rather than require-ing it as a library.
This allows us to check things like the exit codes returned.
- The `sanitize_path_options` functions remove all trailing
and leading spaces. So any valid directory like ` 123`,
`123 ` can not be used
- Also if there are two directories ` 123` and `123`, and if
user pick the ` 123` as option to `-d` or `-t`, then stow pick
directory `123` as the argument instead of ` 123` as user want.
```
STOW_DIR=. stow -n -v3 -t \ 123 456
stow dir is /tmp/test
stow dir path relative to target 123 is ..
cwd now 123
cwd restored to /tmp/test
cwd now 123
Planning stow of package 456...
Stowing contents of ../456 (cwd=/tmp/test/123)
Planning stow of package 456... done
cwd restored to /tmp/test
WARNING: in simulation mode so not modifying filesystem.
```
- This commit remove the check in `sanitize_path_options` function,
and now stow can work with those directories. There have been a check
for valid directory, so we are safe.
This is more in keeping with the UNIX convention of no output on success,
and is also the way Stow v1.x behaved. Thanks to Adam Sampson for the suggestion.
I'm guessing it was added due to a misunderstanding of how shell
quoting works. When you invoke
stow --ignore=".#.*" ...
the shell strips out the quotes before the Perl process ever sees them.
I can't imagine any sensible scenario in which you would need to invoke
stow --ignore='"foo"'
but if the user has a filename containing quotes at the beginning and
end, they can now choose to ignore it (prior to this patch, they couldn't).
