From: simon Date: Sun, 21 Nov 2004 14:15:05 +0000 (+0000) Subject: My user-friendly symlinking tool `lns' is another thing that really X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/utils/commitdiff_plain/337ff28503c35c30ffc26915b43a217287ca56cd My user-friendly symlinking tool `lns' is another thing that really ought to be in utils. Move it over, write it a manpage, etc. git-svn-id: svn://svn.tartarus.org/sgt/utils@4868 cda61777-01e9-0310-a592-d414129be87e --- diff --git a/Makefile b/Makefile index 2833a1e..67da13e 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -SUBDIRS = base64 cvt-utf8 multi nntpid xcopy +SUBDIRS = base64 cvt-utf8 lns multi nntpid xcopy # for `make html' and `make release'; should be a relative path DESTDIR = . diff --git a/lns/Makefile b/lns/Makefile new file mode 100644 index 0000000..95849b8 --- /dev/null +++ b/lns/Makefile @@ -0,0 +1,33 @@ +# for `make release' and `make html' +DESTDIR = . + +# for `make install' +PREFIX = /usr/local +BINDIR = $(PREFIX)/bin +MANDIR = $(PREFIX)/man/man1 + +all: lns.1 + +%.1: %.but + halibut --man=$@ $< + +clean: + rm -f *.1 *.html *.tar.gz + +html: + halibut --html=$(DESTDIR)/lns.html lns.but + +release: lns.1 + mkdir -p reltmp/lns + ln -s ../../lns reltmp/lns + ln -s ../../lns.1 reltmp/lns + ln -s ../../lns.but reltmp/lns + ln -s ../../Makefile reltmp/lns + tar -C reltmp -chzf $(DESTDIR)/lns.tar.gz lns + rm -rf reltmp + +install: lns.1 + mkdir -p $(BINDIR) + install lns $(BINDIR)/lns + mkdir -p $(MANDIR) + install -m 0644 lns.1 $(MANDIR)/lns.1 diff --git a/lns/lns b/lns/lns new file mode 100755 index 0000000..ebe9e62 --- /dev/null +++ b/lns/lns @@ -0,0 +1,225 @@ +#!/usr/bin/env perl + +# lns -- create a symbolic link. Alternative to "ln -s". +# This program works more like "cp", in that the source path name is not +# taken literally. +# ln -s filename /tmp +# creates a link +# /tmp/filename -> filename +# whereas we would prefer +# /tmp/filename -> /home/me/filename +# or wherever the file *really* was. +# +# Usage: lns [-afF] file1 file2 +# or lns [-af] file1 [file2...] dir +# +# Where: +# -a means absolute - "symlink /usr/bin/argh /usr/local/bin/argh" produces +# a relative link "/usr/bin/argh -> ../local/bin/argh", but using the +# -a option will give a real absolute link. +# -f means forceful - overwrite the target filename if it exists *and* is +# a link. You can't accidentally overwrite real files like this. +# -q means quiet - don't complain if we fail to do the job. +# -v means verbose - say what we're doing. +# -F means FILE - forces interpretation to be the "file1 file2" syntax, +# even if file2 is a link to a directory. This option implies -f. + +use Cwd; + +$usage = + "usage: lns [flags] srcfile destfile\n". + " or: lns [flags] srcfile [srcfile...] destdir\n". + "where: -a create symlinks with absolute path names\n". + " -f overwrite existing symlink at target location\n". + " -F like -f, but works even if target is link to dir\n". + " -v verbosely log activity (repeat for more verbosity)\n". + " -q suppress error messages on failure\n". + " also: lns --version report version number\n" . + " lns --help display this help text\n" . + " lns --licence display (MIT) licence text\n"; + +$licence = + "lns is copyright 1999,2004 Simon Tatham.\n" . + "\n" . + "Permission is hereby granted, free of charge, to any person\n" . + "obtaining a copy of this software and associated documentation files\n" . + "(the \"Software\"), to deal in the Software without restriction,\n" . + "including without limitation the rights to use, copy, modify, merge,\n" . + "publish, distribute, sublicense, and/or sell copies of the Software,\n" . + "and to permit persons to whom the Software is furnished to do so,\n" . + "subject to the following conditions:\n" . + "\n" . + "The above copyright notice and this permission notice shall be\n" . + "included in all copies or substantial portions of the Software.\n" . + "\n" . + "THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\n" . + "EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n" . + "MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\n" . + "NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\n" . + "BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\n" . + "ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\n" . + "CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n" . + "SOFTWARE.\n"; + +$abs=$force=$quiet=$verbose=$FILE=0; +while ($_=shift @ARGV) { + last if /^--$/; + unshift (@ARGV, $_), last unless /^-(.*)/; + if ($1 eq "-help") { + print STDERR $usage; + exit 0; + } elsif ($1 eq "-version") { + if ('$Revision$' =~ /Revision:\s+(\d+)/) { + print "lns revision $1\n"; + } else { + print "lns: unknown revision\n"; + } + exit 0; + } elsif ($1 eq "-licence" or $1 eq "-license") { + print $licence; + exit 0; + } else { + foreach $opt (split //, $1) { + if ($opt eq "a") { $abs=1; } + elsif ($opt eq "f") { $force=1; } + elsif ($opt eq "q") { $quiet=1; } + elsif ($opt eq "v") { $verbose++; } + elsif ($opt eq "F") { $force=$FILE=1; } + else { die "$0: unrecognised option '-$1'\n"; } + } + } +} + +die $usage if $#ARGV < 1; + +die "$0: multiple source files specified with -F option\n" + if $#ARGV > 1 && $FILE; +die "$0: -q (quiet) and -v (verbose) options both specified\n" + if $quiet && $verbose; + +$target = pop @ARGV; +die "$0: multiple source files specified, $target not a directory\n" + if $#ARGV > 0 && !-d $target; + +$multiple = (-d $target && !$FILE); +$whereami = getcwd(); + +$target =~ s/// if $target =~ /\/$/; # strip trailing slash if present + +if ($multiple) { + foreach $source (@ARGV) { + $source =~ /^(.*\/)?([^\/]*)$/; # find final file name component + &makelink($source, "$target/$2"); # actually make a link + } +} else { + $source = $ARGV[0]; # only one source file + &makelink($source, $target); # make the link +} + +sub makelink { + local ($source, $target) = @_; + + # If the target exists... + if (-e $target || readlink $target) { + # If it's a symlink and we're in Force mode, remove it and carry on. + if ($force && readlink $target) { + unlink $target || die "$0: unable to remove link $target\n"; + # Report that if in Verbose mode. + warn "$0: removing existing target link $target\n" if $verbose; + } else { + # Otherwise, fail. Report that fact if not in Quiet mode. + warn "$0: failed to link $source to $target: target exists\n" + if !$quiet; + return; + } + } + + # OK, now we're ready to do the link. Calculate the absolute path names + # of both source and target. + $source = &absolute($source); + $target = &absolute($target); + + # If we're in Relative mode (the default), calculate the relative path + # name we will reference the source by. + $sourcename = $abs ? $source : &relname($source, $target); + + warn "$0: linking $source: $target -> $sourcename\n" if $verbose; + + # Make the link + symlink($sourcename, $target) || die "$0: unable to make link to $target\n"; +} + +sub absolute { + local ($_) = @_; + $_ = "$whereami/$_" if !/^\//; + s//$whereami/ if /^\./; + 1 while s/\/\.\//\//; + 1 while s/\/\//\//; + 1 while s/\/[^\/]+\/\.\.//; + 1 while s/^\/\.\.\//\//; + $_; +} + +sub relname { + local ($source, $target) = @_; + local $prefix; + + # Strip the last word off the target (the actual file name) to + # obtain the target _directory_. + $target =~ s/\/[^\/]*$//; + + # Our starting prefix is empty. We will add one "../" at a time + # until we find a match. + + while (1) { + + # If $target is a prefix of $source, we are done. (No matter what + # symlinks may exist on the shared common pathname, if we are + # linking `a/b/c/foo' to `foo' then a simple relative link will + # work.) + if (substr($source, 0, length $target) eq $target) { + return $prefix . substr($source, 1 + length $target); # skip the slash + } + + # Otherwise, descend to "..". + + $target = $target . "/.."; + + # Now normalise the path by removing all ".." segments. We want + # to do this while _as far as possible_ preserving symlinks. So + # the algorithm is: + # + # - Repeatedly search for the rightmost `directory/..' + # fragment. + # - When we find it, one of two cases apply. + # * If the directory before the .. is not a symlink, we can + # remove both it and the .. from the string. + # * If it _is_ a symlink, we substitute it for its link + # text, and loop round again. + while ($target =~ + /^(.*)\/((\.|\.\.[^\/]+|\.?[^\/\.][^\/]*)\/\.\.)(\/.*)?$/) + { + my ($pre, $dir, $frag, $post) = ($1,$2,$3,$4); + my $log = "transforming $target -> "; + if (-l "$pre/$frag") { + my $linktext = readlink "$pre/$frag"; + if ($linktext =~ /^\//) { # absolute link + $target = $linktext; + } else { # relative link + $target = "$pre/$linktext"; + } + $target .= "/.." . $post; + } else { + $target = $pre . $post; + } + $target = "/" if $target eq ""; # special case + $log .= "$target"; + warn "$0: $log\n" if $verbose > 1; + } + + # Now we have replaced $target with a pathname equivalent to + # `$target/..'. So add a "../" to $prefix, and try matching + # again. + $prefix .= "../"; + } +} diff --git a/lns/lns.but b/lns/lns.but new file mode 100644 index 0000000..2c19c1d --- /dev/null +++ b/lns/lns.but @@ -0,0 +1,199 @@ +\cfg{man-identity}{lns}{1}{2004-11-21}{Simon Tatham}{Simon Tatham} + +\title Man page for \cw{lns} + +\U NAME + +\cw{lns} - symbolic link creation utility + +\U SYNOPSIS + +\c lns [ flags ] srcfile destfile +\e bbb iiiii iiiiiii iiiiiiii +\c lns [ flags ] srcfile [srcfile...] destdir +\e bbb iiiii iiiiiii iiiiiii iiiiiii + +\U DESCRIPTION + +\cw{lns} creates symbolic links. + +The standard command \cw{ln -s} also does this, but it interprets +its first argument as the literal text to be placed in the symlink. +If your current working directory is not the same as the target +directory, this can get confusing. For example, to create a symlink +to a file \cw{hello.c} in a subdirectory \cw{programs}, you would +have to write \c{ln -s ../hello.c programs}, even though +\cw{hello.c} is actually in your current directory, not one level +up. In particular, this is unhelpful because it makes it difficult +to use tab completion to set up the command line. + +\cw{lns} solves this problem, by creating symlinks using the obvious +semantics you would expect from \cw{mv} or \cw{cp}. All of its +arguments are expected to be either absolute path names, or relative +to the \e{current} working directory. So, in the above example, you +would write \c{lns hello.c programs/hello.c} or just \c{lns hello.c +programs}, exactly as you would have done if the command had been +\cw{cp}; and \cw{lns} will figure out for itself that the literal +text of the symlink needs to be \c{../hello.c}. + +\U ARGUMENTS + +If you provide precisely two arguments to \cw{lns}, and the second +one is not a directory (or a symlink to a directory), then \cw{lns} +will interpret the second argument as a destination file name, and +create its target link with precisely that name. + +If the second argument is a directory, \cw{lns} will assume you want +a link created \e{inside} that directory, with the same filename as +the source file. If you supply more than two arguments, \cw{lns} +will \e{expect} the final argument to a directory, and will do this +for each of the other arguments. + +(This behaviour is intended to mimic \cw{cp} as closely as +possible.) + +The source file(s) are not required to exist. \cw{lns} will create +links to their locations whether they actually exist or not; if you +create them later, the links will point to them. + +\U OPTIONS + +\dt \cw{-a} + +\dd Create symlinks with absolute path names (beginning with a +slash). Normally, \cw{lns} will create relative symlinks. Relative +symlinks are often more useful: if a parent directory of both the +link and its target is moved to a new location, a relative symlink +will still work while an absolute one will fail. + +\dt \cw{-f} + +\dd Overwrite an existing symlink at the target location. Normally, +\cw{lns} will warn and refuse to do anything if the target location +is already occupied by a symlink to a file; using \cw{-f} will cause +it to replace the existing link with its new one. + +\lcont{ + +If the target location is occupied by something that is \e{not} a +symlink, \cw{lns} will refuse to overwrite it no matter what options +you supply. + +If you specify precisely two arguments, and the second is a symlink +to a directory, \cw{lns} will treat it as a destination directory +rather than a destination file, even if \cw{-f} is specified. Use +\cw{-F}, described next, to override this. + +} + +\dt \cw{-F} + +\dd Like \cw{-f}, but additionally forces \cw{lns} to interpret its +second argument as a destination \e{file} name rather than a +destination directory. This option is useful for overriding an +existing link to one directory with a link to a different one. + +\dt \cw{-v} + +\dd Verbose mode: makes \cw{lns} talk about what it is doing. You +can make it more verbose by adding a second instance of \cw{-v}. + +\dt \cw{-q} + +\dd Quiet mode: prevents \cw{lns} from printing an error message if +the link target already exists. + +\U EXAMPLES + +In simple situations, \cw{lns} can be used pretty much as you would +use \cw{cp}. For example, suppose you start in directory \cw{dir} +and issue the following commands: + +\c $ lns file1 subdir +\e bbbbbbbbbbbbbbbb +\c $ lns file2 .. +\e bbbbbbbbbbbb +\c $ lns subdir/file3 subdir2/subsubdir +\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb +\c $ lns subdir2/file4 subdir2/subsubdir +\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb + +Assuming all the subdirectories mentioned actually exist, this will +create the following symlinks: + +\b \cw{subdir/file1}, with link text \cq{../file1}. + +\b \cw{../file2}, with link text \cq{dir/file2}. + +\b \cw{subdir2/subsubdir/file3}, with link text +\cq{../../subdir/file3}. + +\b \cw{subdir3/subsubdir/file4}, with link text \cq{../file4}. + +Note that in each case \cw{lns} has constructed the \e{shortest} +relative link it could manage: it did not mindlessly create the +fourth link with text \cq{../../subdir/file4}. + +You can specify a target file name instead of a target directory. +For example, the following command has the same effect as the first +of the list above: + +\c $ lns file1 subdir/file1 +\e bbbbbbbbbbbbbbbbbbbbbb + +Now suppose there is another file called \cw{file1} in \cw{subdir2}, +and you want to change the link in \cw{subdir} to point to that. +Normally \cw{lns} will give you an error: + +\c $ lns subdir2/file1 subdir +\e bbbbbbbbbbbbbbbbbbbbbbbb +\c lns: failed to link subdir2/file1 to subdir/file1: target exists + +You can override this error by using \cw{-f}: + +\c $ lns -f subdir2/file1 subdir +\e bbbbbbbbbbbbbbbbbbbbbbbbbbb + +This will overwrite the existing link \cw{subdir/file1} with a new +one whose text reads \cq{../subdir2/file1}. + +Now let's create some symlinks to \e{directories}. Again, this is +simple to begin with: + +\c $ lns subdir2 subdir3 +\c bbbbbbbbbbbbbbbbbbb + +This creates a symlink called \cw{subdir3} with text \cq{subdir2}. + +In order to overwrite this directory, the \cw{-F} option is likely +to be useful. Suppose I now want the link \cw{subdir3} to point at +\cw{subdir} instead of \cw{subdir2}. If I do this: + +\c $ lns -f subdir subdir3 +\c bbbbbbbbbbbbbbbbbbbbb + +then \cw{lns} will immediately notice that the second argument +\cw{subdir3} is (a symlink to) a directory, and will therefore +assume that it was intended to be the directory \e{containing} the +new link. So it will create a file \cw{subdir3/subdir} (equivalent +to \cw{subdir/subdir}, of course, since \cw{subdir3} is currently a +symlink to \cw{subdir}) with link text \cw{../subdir}. + +In order to overwrite the directory symlink correctly, you need the +\cw{-F} option: + +\c $ lns -F subdir subdir3 +\c bbbbbbbbbbbbbbbbbbbbb + +\cw{-F} tells \cw{lns} that you really want the new symlink to be +\e{called} \cw{subdir3}, not to be \e{in the directory} +\cw{subdir3}; and it also implies the \cw{-f} option to force +overwriting. So now you get what you wanted: the previous symlink +\cw{subdir3} is replaced with one whose link text reads \cq{subdir}. + +\U LICENCE + +\cw{lns} is free software, distributed under the MIT licence. Type +\cw{lns --licence} to see the full licence text. + +\versionid $Id$