Import my usual \dash macro into all these man pages, and use it for

[sgt/utils] / lns / lns.but

\cfg{man-identity}{lns}{1}{2004-11-21}{Simon Tatham}{Simon Tatham}

\define{dash} \u2013{-}

\title Man page for \cw{lns}

\U NAME

\cw{lns} \dash 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}.

\cw{lns} also has a mode in which it will create a symlink mirror of
an entire directory tree: that is, instead of creating a single
symlink to the root of the tree, it will create \e{directories} in
the same structure as the whole of the original tree, and fill them
with individual symlinks to the files. This is occasionally handy if
you want to work with a slightly modified version of a large file
hierarchy but you don't want to waste the disk space needed to
create an entirely separate copy: you can symlink-mirror the whole
tree, and then just replace one or two of the symlinks with modified
versions of the files they point to.

\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 be 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{-r}

\dd Enables recursive link-tree construction. If the source pathname
exists and is a directory, then instead of creating a symlink to it
at the target site, \cw{lns} will create a fresh directory, and then
recursively attempt to link every file inside the source directory
to the inside of the new target directory.

\lcont{

If a directory already
exists at the target site, \cw{lns} will recurse into it; so you
can, for instance, use \cw{lns -r -f} to refresh an existing link
tree.

}

\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{subdir2/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{../../subdir2/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
\e   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
\e   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
\e   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}.

Next, a couple of examples with \cw{-r}. Suppose you have your
subdirectory \cw{subdir}. Then running

\c $ lns -r subdir subdir-mirror
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbb

will create a new subdirectory called \c{subdir-mirror}, containing
symlinks to everything in \c{subdir}.

If the directory \c{subdir-mirror} already existed, however,
\cw{lns}'s command-line processing will notice that it's a
directory, and will assume things are supposed to be copied \e{into}
it, so that your mirror of \c{subdir} will end up at
\c{subdir-mirror/subdir}. To fix this, you can again use \cw{-F}, to
tell \cw{lns} to literally create its output at the precise location
you specify rather than inside it:

\c $ lns -rF subdir subdir-mirror
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbb

\U LICENCE

\cw{lns} is free software, distributed under the MIT licence. Type
\cw{lns --licence} to see the full licence text.

\versionid $Id$