Ditch obsolete --conflicts option and update misleading documentation.

This commit is contained in:
Adam Spiers 2011-11-24 20:47:39 +00:00
parent 00d4e68445
commit 55d3f05cf2
3 changed files with 30 additions and 68 deletions

View file

@ -131,20 +131,7 @@ C<-D>).
=item --no =item --no
Do not perform any operations that modify the filesystem; merely show Do not perform any operations that modify the filesystem; merely show
what would happen. Since no actual operations are performed, C<stow what would happen.
-n> could report conflicts when none would actually take place (see
"Conflicts" in the info manual); but it won't fail to report
conflicts that B<would> take place.
=item -c
=item --conflicts
Do not exit immediately when a conflict is encountered. This option
implies C<-n>, and is used to search for all conflicts that might
arise from an actual Stow operation. As with C<-n>, however, false
conflicts might be reported (see the "Conflicts" section in the info
manual).
=item -d DIR =item -d DIR
@ -429,16 +416,19 @@ sub main {
# --verbose: tell me what you are planning to do # --verbose: tell me what you are planning to do
# --simulate: don't execute planned operations # --simulate: don't execute planned operations
# --conflicts: just list any detected conflicts
if (scalar @conflicts) { if (scalar @conflicts) {
warn "WARNING: conflicts detected.\n"; warn "WARNING: conflicts detected:\n";
if ($options->{conflicts}) { warn $_ foreach @conflicts;
warn $_ foreach @conflicts;
}
warn "WARNING: all operations aborted.\n"; warn "WARNING: all operations aborted.\n";
exit 1;
} }
else { else {
if ($options->{simulate}) {
warn "WARNING: in simulation mode so not modifying filesystem.\n";
return;
}
$stow->process_tasks(); $stow->process_tasks();
} }
} }
@ -464,7 +454,7 @@ sub process_options {
Getopt::Long::config('no_ignore_case', 'bundling', 'permute'); Getopt::Long::config('no_ignore_case', 'bundling', 'permute');
GetOptions( GetOptions(
\%options, \%options,
'verbose|v:+', 'help|h', 'simulate|n|no', 'conflicts|c', 'verbose|v:+', 'help|h', 'simulate|n|no',
'version|V', 'compat|p', 'dir|d=s', 'target|t=s', 'version|V', 'compat|p', 'dir|d=s', 'target|t=s',
# clean and pre-compile any regex's at parse time # clean and pre-compile any regex's at parse time
@ -608,7 +598,6 @@ SYNOPSIS:
OPTIONS: OPTIONS:
-n, --no Do not actually make any filesystem changes -n, --no Do not actually make any filesystem changes
-c, --conflicts Scan for and print any conflicts, implies -n
-d DIR, --dir=DIR Set stow dir to DIR (default is current dir) -d DIR, --dir=DIR Set stow dir to DIR (default is current dir)
-t DIR, --target=DIR Set target to DIR (default is parent of stow dir) -t DIR, --target=DIR Set target to DIR (default is parent of stow dir)
-v, --verbose[=N] Increase verbosity (levels are 0,1,2,3; -v, --verbose[=N] Increase verbosity (levels are 0,1,2,3;

View file

@ -107,7 +107,6 @@ the installation of software packages.
* Installing Packages:: Using Stow to install. * Installing Packages:: Using Stow to install.
* Deleting Packages:: Using Stow to uninstall. * Deleting Packages:: Using Stow to uninstall.
* Conflicts:: When Stow can't stow. * Conflicts:: When Stow can't stow.
* Deferred Operation:: Using two passes to stow.
* Mixing Operations:: Multiple actions per invocation. * Mixing Operations:: Multiple actions per invocation.
* Multiple Stow Directories:: Further segregating software. * Multiple Stow Directories:: Further segregating software.
* Target Maintenance:: Cleaning up mistakes. * Target Maintenance:: Cleaning up mistakes.
@ -417,18 +416,6 @@ directory.
The following options are deprecated: The following options are deprecated:
@end table @end table
The following options are deprecated as of Stow version 2:
@table @samp
@item -c
@itemx --conflicts
Print any conflicts that are encountered. This option
implies @samp{-n}, and is used to search for all conflicts that might
arise from an actual Stow operation.
This option is deprecated as conflicts are now printed by default and no
operations will be performed if any conflicts are detected.
@end table
@xref{Resource Files}, for a way to set default values for any of these @xref{Resource Files}, for a way to set default values for any of these
options. options.
@ -699,7 +686,7 @@ package.
@c =========================================================================== @c ===========================================================================
@node Conflicts, Deferred Operation, Deleting Packages, Top @node Conflicts, Mixing Operations, Deleting Packages, Top
@chapter Conflicts @chapter Conflicts
If, during installation, a file or symlink exists in the target tree and If, during installation, a file or symlink exists in the target tree and
@ -711,37 +698,28 @@ other hand, if the existing name is merely a symlink that already points
where Stow needs it to, then no conflict has occurred. (Thus it where Stow needs it to, then no conflict has occurred. (Thus it
is harmless to install a package that has already been installed.) is harmless to install a package that has already been installed.)
A conflict causes Stow to exit immediately and print a warning For complex packages, scanning the stow and target trees in tandem,
(unless @samp{-c} is given), even if that means aborting an installation and deciding whether to make directories or links, split-open or fold
in mid-package. directories, can actually take a long time (a number of seconds).
Moreover, an accurate analysis of potential conflicts requires us to
take into account all of these operations.
@cindex false conflict @anchor{Deferred Operation}
When running Stow with the @samp{-n} or @samp{-c} options, no actual @section Deferred Operation
filesystem-modifying operations take place. Thus if a folded tree would
have been split open, but instead was left in place because @samp{-n} or Since version 2.0, Stow now adopts a two-phase algorithm, first
@samp{-c} was used, then Stow will report a @dfn{false conflict}, since scanning for any potential conflicts before any stowing or unstowing
the directory that Stow was expecting to populate has remained an operations are performed. If any conflicts are found, they are
un-populatable symlink. displayed and then Stow terminates without making any modifications to
the filesystem. This means that there is much less risk of a package
being partially stowed or unstowed due to conflicts.
Prior to version 2.0, if a conflict was discovered, the stow or unstow
operation could be aborted mid-flow, leaving the target tree in an
inconsistent state.
@c =========================================================================== @c ===========================================================================
@node Deferred Operation, Mixing Operations, Conflicts, Top @node Mixing Operations, Multiple Stow Directories, Conflicts, Top
@chapter Deferred Operation
For complex packages, scanning the stow and target trees in tandem, and
deciding whether to make directories or links, split-open or fold directories,
can actually take a long time (a number of seconds). Moreover, an accurate
analysis of potential conflicts requires us to take into account all of
these operations.
Since version 2.0, Stow now adopts a two-phase algorithm, first scanning
for any potential conflicts before any stowing or unstowing operations
are performed. This means that there is much less risk of a package
being partially stowed or unstowed due to conflicts. Prior to version
2.0, if a conflict was discovered, the stow or unstow operation could be
aborted mid-flow, leaving the target tree in an inconsistent state.
@c ===========================================================================
@node Mixing Operations, Multiple Stow Directories, Deferred Operation, Top
@chapter Mixing Operations @chapter Mixing Operations
Since version 2.0, multiple distinct actions can be specified in a single Since version 2.0, multiple distinct actions can be specified in a single

View file

@ -1323,11 +1323,6 @@ sub process_tasks {
debug(2, "Processing tasks..."); debug(2, "Processing tasks...");
if ($self->{simulate}) {
warn "WARNING: simulating so all operations are deferred.\n";
return;
}
# Strip out all tasks with a skip action # Strip out all tasks with a skip action
$self->{tasks} = [ grep { $_->{action} ne 'skip' } @{ $self->{tasks} } ]; $self->{tasks} = [ grep { $_->{action} ne 'skip' } @{ $self->{tasks} } ];