Man page for lns

NAME

lns – symbolic link creation utility

SYNOPSIS

lns [ flags ] srcfile destfile
lns [ flags ] srcfile [srcfile...] destdir

DESCRIPTION

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.

ARGUMENTS

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.

OPTIONS

-a
Create symlinks with absolute path names (beginning with a slash). Normally, 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
Overwrite an existing symlink at the target location. Normally, 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
Like -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
Tolerate an existing symlink at the target location, if it has the same link text that 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
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, 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
Verbose mode: makes lns talk about what it is doing. You can make it more verbose by adding a second instance of -v.
-q
Quiet mode: prevents lns from printing an error message if the link target already exists.

EXAMPLES

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:

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

LIMITATIONS

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.

LICENCE

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


[lns version 20230903.c678881]