mdw@git.distorted.org.uk Git - sgt/utils/blob - lns/lns.but

   1 \cfg{man-identity}{lns}{1}{2004-11-21}{Simon Tatham}{Simon Tatham}
   2
   3 \title Man page for \cw{lns}
   4
   5 \U NAME
   6
   7 \cw{lns} - symbolic link creation utility
   8
   9 \U SYNOPSIS
  10
  11 \c lns [ flags ] srcfile destfile
  12 \e bbb   iiiii   iiiiiii iiiiiiii
  13 \c lns [ flags ] srcfile [srcfile...] destdir
  14 \e bbb   iiiii   iiiiiii  iiiiiii     iiiiiii
  15
  16 \U DESCRIPTION
  17
  18 \cw{lns} creates symbolic links.
  19
  20 The standard command \cw{ln -s} also does this, but it interprets
  21 its first argument as the literal text to be placed in the symlink.
  22 If your current working directory is not the same as the target
  23 directory, this can get confusing. For example, to create a symlink
  24 to a file \cw{hello.c} in a subdirectory \cw{programs}, you would
  25 have to write \c{ln -s ../hello.c programs}, even though
  26 \cw{hello.c} is actually in your current directory, not one level
  27 up. In particular, this is unhelpful because it makes it difficult
  28 to use tab completion to set up the command line.
  29
  30 \cw{lns} solves this problem, by creating symlinks using the obvious
  31 semantics you would expect from \cw{mv} or \cw{cp}. All of its
  32 arguments are expected to be either absolute path names, or relative
  33 to the \e{current} working directory. So, in the above example, you
  34 would write \c{lns hello.c programs/hello.c} or just \c{lns hello.c
  35 programs}, exactly as you would have done if the command had been
  36 \cw{cp}; and \cw{lns} will figure out for itself that the literal
  37 text of the symlink needs to be \c{../hello.c}.
  38
  39 \U ARGUMENTS
  40
  41 If you provide precisely two arguments to \cw{lns}, and the second
  42 one is not a directory (or a symlink to a directory), then \cw{lns}
  43 will interpret the second argument as a destination file name, and
  44 create its target link with precisely that name.
  45
  46 If the second argument is a directory, \cw{lns} will assume you want
  47 a link created \e{inside} that directory, with the same filename as
  48 the source file. If you supply more than two arguments, \cw{lns}
  49 will \e{expect} the final argument to a directory, and will do this
  50 for each of the other arguments.
  51
  52 (This behaviour is intended to mimic \cw{cp} as closely as
  53 possible.)
  54
  55 The source file(s) are not required to exist. \cw{lns} will create
  56 links to their locations whether they actually exist or not; if you
  57 create them later, the links will point to them.
  58
  59 \U OPTIONS
  60
  61 \dt \cw{-a}
  62
  63 \dd Create symlinks with absolute path names (beginning with a
  64 slash). Normally, \cw{lns} will create relative symlinks. Relative
  65 symlinks are often more useful: if a parent directory of both the
  66 link and its target is moved to a new location, a relative symlink
  67 will still work while an absolute one will fail.
  68
  69 \dt \cw{-f}
  70
  71 \dd Overwrite an existing symlink at the target location. Normally,
  72 \cw{lns} will warn and refuse to do anything if the target location
  73 is already occupied by a symlink to a file; using \cw{-f} will cause
  74 it to replace the existing link with its new one.
  75
  76 \lcont{
  77
  78 If the target location is occupied by something that is \e{not} a
  79 symlink, \cw{lns} will refuse to overwrite it no matter what options
  80 you supply.
  81
  82 If you specify precisely two arguments, and the second is a symlink
  83 to a directory, \cw{lns} will treat it as a destination directory
  84 rather than a destination file, even if \cw{-f} is specified. Use
  85 \cw{-F}, described next, to override this.
  86
  87 }
  88
  89 \dt \cw{-F}
  90
  91 \dd Like \cw{-f}, but additionally forces \cw{lns} to interpret its
  92 second argument as a destination \e{file} name rather than a
  93 destination directory. This option is useful for overriding an
  94 existing link to one directory with a link to a different one.
  95
  96 \dt \cw{-v}
  97
  98 \dd Verbose mode: makes \cw{lns} talk about what it is doing. You
  99 can make it more verbose by adding a second instance of \cw{-v}.
 100
 101 \dt \cw{-q}
 102
 103 \dd Quiet mode: prevents \cw{lns} from printing an error message if
 104 the link target already exists.
 105
 106 \U EXAMPLES
 107
 108 In simple situations, \cw{lns} can be used pretty much as you would
 109 use \cw{cp}. For example, suppose you start in directory \cw{dir}
 110 and issue the following commands:
 111
 112 \c $ lns file1 subdir
 113 \e   bbbbbbbbbbbbbbbb
 114 \c $ lns file2 ..
 115 \e   bbbbbbbbbbbb
 116 \c $ lns subdir/file3 subdir2/subsubdir
 117 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
 118 \c $ lns subdir2/file4 subdir2/subsubdir
 119 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
 120
 121 Assuming all the subdirectories mentioned actually exist, this will
 122 create the following symlinks:
 123
 124 \b \cw{subdir/file1}, with link text \cq{../file1}.
 125
 126 \b \cw{../file2}, with link text \cq{dir/file2}.
 127
 128 \b \cw{subdir2/subsubdir/file3}, with link text
 129 \cq{../../subdir/file3}.
 130
 131 \b \cw{subdir3/subsubdir/file4}, with link text \cq{../file4}.
 132
 133 Note that in each case \cw{lns} has constructed the \e{shortest}
 134 relative link it could manage: it did not mindlessly create the
 135 fourth link with text \cq{../../subdir/file4}.
 136
 137 You can specify a target file name instead of a target directory.
 138 For example, the following command has the same effect as the first
 139 of the list above:
 140
 141 \c $ lns file1 subdir/file1
 142 \e   bbbbbbbbbbbbbbbbbbbbbb
 143
 144 Now suppose there is another file called \cw{file1} in \cw{subdir2},
 145 and you want to change the link in \cw{subdir} to point to that.
 146 Normally \cw{lns} will give you an error:
 147
 148 \c $ lns subdir2/file1 subdir
 149 \e   bbbbbbbbbbbbbbbbbbbbbbbb
 150 \c lns: failed to link subdir2/file1 to subdir/file1: target exists
 151
 152 You can override this error by using \cw{-f}:
 153
 154 \c $ lns -f subdir2/file1 subdir
 155 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbb
 156
 157 This will overwrite the existing link \cw{subdir/file1} with a new
 158 one whose text reads \cq{../subdir2/file1}.
 159
 160 Now let's create some symlinks to \e{directories}. Again, this is
 161 simple to begin with:
 162
 163 \c $ lns subdir2 subdir3
 164 \e   bbbbbbbbbbbbbbbbbbb
 165
 166 This creates a symlink called \cw{subdir3} with text \cq{subdir2}.
 167
 168 In order to overwrite this directory, the \cw{-F} option is likely
 169 to be useful. Suppose I now want the link \cw{subdir3} to point at
 170 \cw{subdir} instead of \cw{subdir2}. If I do this:
 171
 172 \c $ lns -f subdir subdir3
 173 \e   bbbbbbbbbbbbbbbbbbbbb
 174
 175 then \cw{lns} will immediately notice that the second argument
 176 \cw{subdir3} is (a symlink to) a directory, and will therefore
 177 assume that it was intended to be the directory \e{containing} the
 178 new link. So it will create a file \cw{subdir3/subdir} (equivalent
 179 to \cw{subdir/subdir}, of course, since \cw{subdir3} is currently a
 180 symlink to \cw{subdir}) with link text \cw{../subdir}.
 181
 182 In order to overwrite the directory symlink correctly, you need the
 183 \cw{-F} option:
 184
 185 \c $ lns -F subdir subdir3
 186 \e   bbbbbbbbbbbbbbbbbbbbb
 187
 188 \cw{-F} tells \cw{lns} that you really want the new symlink to be
 189 \e{called} \cw{subdir3}, not to be \e{in the directory}
 190 \cw{subdir3}; and it also implies the \cw{-f} option to force
 191 overwriting. So now you get what you wanted: the previous symlink
 192 \cw{subdir3} is replaced with one whose link text reads \cq{subdir}.
 193
 194 \U LICENCE
 195
 196 \cw{lns} is free software, distributed under the MIT licence. Type
 197 \cw{lns --licence} to see the full licence text.
 198
 199 \versionid $Id$