lns
lns
– symbolic link creation utility
lns [ flags ] srcfile destfile
lns [ flags ] srcfile [srcfile...] destdir
lns
creates symbolic links.
The standard command 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 hello.c
in a subdirectory programs
, you would have to write ln -s ../hello.c programs
, even though 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.
lns
solves this problem, by creating symlinks using the obvious semantics you would expect from mv
or cp
. All of its arguments are expected to be either absolute path names, or relative to the current working directory. So, in the above example, you would write lns hello.c programs/hello.c
or just lns hello.c programs
, exactly as you would have done if the command had been cp
; and lns
will figure out for itself that the literal text of the symlink needs to be ../hello.c
.
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 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.
If you provide precisely two arguments to lns
, and the second one is not a directory (or a symlink to a directory), then 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, lns
will assume you want a link created inside that directory, with the same filename as the source file. If you supply more than two arguments, lns
will expect the final argument to be a directory, and will do this for each of the other arguments.
(This behaviour is intended to mimic cp
as closely as possible.)
The source file(s) are not required to exist. lns
will create links to their locations whether they actually exist or not; if you create them later, the links will point to them.
-a
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.
-f
lns
will warn and refuse to do anything if the target location is already occupied by a symlink to a file; using -f
will cause it to replace the existing link with its new one.
If the target location is occupied by something that is not a symlink, 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, lns
will treat it as a destination directory rather than a destination file, even if -f
is specified. Use -F
, described next, to override this.
-F
-f
, but additionally forces lns
to interpret its second argument as a destination 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.
-e
lns
would have created. (Think of it as ‘ensure this link exists’, which lns
will be equally happy to arrange by creating it or by doing nothing.)
-r
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.
If a directory already exists at the target site, lns
will recurse into it; so you can, for instance, use lns -r -f
to refresh an existing link tree.
-v
lns
talk about what it is doing. You can make it more verbose by adding a second instance of -v
.
-q
lns
from printing an error message if the link target already exists.
In simple situations, lns
can be used pretty much as you would use cp
. For example, suppose you start in directory dir
and issue the following commands:
$ lns file1 subdir
$ lns file2 ..
$ lns subdir/file3 subdir2/subsubdir
$ lns subdir2/file4 subdir2/subsubdir
Assuming all the subdirectories mentioned actually exist, this will create the following symlinks:
subdir/file1
, with link text ‘../file1
’.
../file2
, with link text ‘dir/file2
’.
subdir2/subsubdir/file3
, with link text ‘../../subdir/file3
’.
subdir2/subsubdir/file4
, with link text ‘../file4
’.
Note that in each case lns
has constructed the shortest relative link it could manage: it did not mindlessly create the fourth link with text ‘../../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:
$ lns file1 subdir/file1
Now suppose there is another file called file1
in subdir2
, and you want to change the link in subdir
to point to that. Normally lns
will give you an error:
$ lns subdir2/file1 subdir
lns: failed to link subdir2/file1 to subdir/file1: target exists
You can override this error by using -f
:
$ lns -f subdir2/file1 subdir
This will overwrite the existing link subdir/file1
with a new one whose text reads ‘../subdir2/file1
’.
Now let's create some symlinks to directories. Again, this is simple to begin with:
$ lns subdir2 subdir3
This creates a symlink called subdir3
with text ‘subdir2
’.
In order to overwrite this directory, the -F
option is likely to be useful. Suppose I now want the link subdir3
to point at subdir
instead of subdir2
. If I do this:
$ lns -f subdir subdir3
then lns
will immediately notice that the second argument subdir3
is (a symlink to) a directory, and will therefore assume that it was intended to be the directory containing the new link. So it will create a file subdir3/subdir
(equivalent to subdir/subdir
, of course, since subdir3
is currently a symlink to subdir
) with link text ../subdir
.
In order to overwrite the directory symlink correctly, you need the -F
option:
$ lns -F subdir subdir3
-F
tells lns
that you really want the new symlink to be called subdir3
, not to be in the directory subdir3
; and it also implies the -f
option to force overwriting. So now you get what you wanted: the previous symlink subdir3
is replaced with one whose link text reads ‘subdir
’.
Next, a couple of examples with -r
. Suppose you have your subdirectory subdir
. Then running
$ lns -r subdir subdir-mirror
will create a new subdirectory called subdir-mirror
, containing symlinks to everything in subdir
.
If the directory subdir-mirror
already existed, however, lns
's command-line processing will notice that it's a directory, and will assume things are supposed to be copied into it, so that your mirror of subdir
will end up at subdir-mirror/subdir
. To fix this, you can again use -F
, to tell lns
to literally create its output at the precise location you specify rather than inside it:
$ lns -rF subdir subdir-mirror
Because lns
attempts to guess what you probably wanted the exact text of your symlinks to be, it will not let you control that text with complete precision.
For example, it might be important to you that your symlink contains a path that indirects through another symlink, so that it behaves correctly when the latter symlink changes. Or you might specifically need a symlink of the form ../../foo/bar
instead of ../bar
, so that when the link gets moved from the foo
directory into another one, the link will continue to point to some particular file.
In situations where the precise link text is important to you, lns
is probably not the tool for the job, and you should revert to using ln -s
.
lns
is free software, distributed under the MIT licence. Type lns --licence
to see the full licence text.