Skip to Content
gnux

lnx

Make hard or symbolic links between files.

Mirrors GNU ln. Run it as lnx, or as gnux lnx.

Synopsis

lnx [OPTION]... TARGET... [LINK_NAME|DIRECTORY]

GNU reference

Description

lnx creates a link to TARGET. It accepts ln's four forms: TARGET LINK_NAME; TARGET alone (a link of the same name in the current directory); TARGET... DIRECTORY; and -t DIRECTORY TARGET.... Links are hard links by default and symbolic with -s; a symbolic link stores TARGET exactly as written unless -r rewrites it relative to the link's own location. An existing destination is an error unless -f (replace it) or -i (ask first) is given, and the replacement is atomic, so the old entry survives a failure. -n treats a LINK_NAME that is a symbolic link to a directory as the entry to replace rather than a directory to link into, and -T always treats LINK_NAME as a plain file. --backup[=CONTROL] (or -b) first renames each existing destination to a backup: CONTROL simple (or never) appends a suffix, numbered (t) appends .N with N one past the highest already there, existing (nil, the default) numbers the backup only when numbered backups already exist, and none (off) makes none; without a CONTROL the VERSION_CONTROL variable chooses. The suffix is ~, or SUFFIX with -S (which asks for backups by itself), or the SIMPLE_BACKUP_SUFFIX variable. A backup replaces the destination as -f would, and -v reports it as 'BACKUP' ~ 'LINK' => 'TARGET'. For hard links, -L links to what a symbolic link TARGET points at and -P (the default) to the link itself. GNU ln lets the last of conflicting options win; lnx cannot see option order, so it prefers the most cautious (-i over -f) and -L over -P. On a terminal, gnux's terminal view colors the -v report: the verb (removed, created, renamed), each quoted name and the arrows, in the theme --theme or GNUX_THEME names; the words are GNU's, and piped or redirected output is never colored (--pretty=never or GNUX_PRETTY=never turns it off).

Permissions

Creating a link needs write and search permission on the directory that will hold it. A symbolic link needs no access to TARGET, which may not even exist; a hard link requires TARGET to exist on the same filesystem and cannot point at a directory. On Windows, creating symbolic links requires Developer Mode or an elevated prompt; a link's target is stored with backslashes, the only separator a Windows link follows; and replacing a link to a directory (-sfn) removes the old link before renaming the new one in, since Windows cannot rename over it, so it is not atomic there.

Use cases

  • Pointing a stable name (current, latest) at a versioned file or directory.
  • Atomically switching a symlink to a new release with -sfn.
  • Creating relocatable links inside a tree with -sr.
  • Giving one file a second name without duplicating its data.
  • Exposing scripts on PATH by linking them into ~/bin with -t.
  • Installing the gnux per-tool commands as links to one binary.
  • Snapshotting a file with a hard link before it is replaced.
  • Linking dotfiles from a repository into the home directory.

Flags

      --backup CONTROL[="$VERSION_CONTROL"]   make a backup of each existing destination file; CONTROL is none (off), simple (never), existing (nil) or numbered (t)
  -b, --backup-default                        like --backup but does not accept an argument
  -f, --force                                 remove existing destination files
      --help                                  display this help and exit
  -i, --interactive                           prompt whether to remove destinations
  -L, --logical                               dereference TARGETs that are symbolic links
  -n, --no-dereference                        treat LINK_NAME as a normal file if it is a symbolic link to a directory
  -T, --no-target-directory                   treat LINK_NAME as a normal file always
  -P, --physical                              make hard links directly to symbolic links (default)
      --pretty WHEN[="always"]                the gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default
  -r, --relative                              with -s, create links relative to link location
  -S, --suffix SUFFIX                         override the usual backup suffix, '~', with SUFFIX
  -s, --symbolic                              make symbolic links instead of hard links
  -t, --target-directory string               specify the DIRECTORY in which to create the links
      --theme NAME                            color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default
  -v, --verbose                               print name of each linked file
      --version                               output version information and exit

Examples

lnx -s /opt/app/releases/v2 current
lnx -sfn releases/v3 current
lnx -v data.db data.db.snapshot
lnx -sr -t ~/bin tools/build tools/deploy
lnx -s ../shared/config.yml
lnx -sv ../dotfiles/.vimrc ../dotfiles/.gitconfig home/
lnx -si settings.prod.json settings.json
lnx -sf app-v2.conf app.conf
lnx -sT releases/v3 current-release
lnx -L current.log saved.log
lnx -P current.log current-link.log
for t in $(gnux --list); do lnx -sf gnux "$t"; done

Report whether linking succeeded

lnx -s target.txt link.txt && echox linked || echox "link exists already"

Create a release directory and point current at it with the gnux shell

gnux shell -c 'mkdirx -p releases/v4 && lnx -sfnv releases/v4 current'
lnx -sbv releases/v5 current

Options

Each option has a page of its own, with its usage and examples.

  • --backup: Make a backup of each existing destination file; CONTROL is none (off), simple (never), existing (nil) or numbered (t).
  • -b, --backup-default: Like --backup but does not accept an argument.
  • -f, --force: Remove existing destination files.
  • -i, --interactive: Prompt whether to remove destinations.
  • -L, --logical: Dereference TARGETs that are symbolic links.
  • -n, --no-dereference: Treat LINK_NAME as a normal file if it is a symbolic link to a directory.
  • -T, --no-target-directory: Treat LINK_NAME as a normal file always.
  • -P, --physical: Make hard links directly to symbolic links (default).
  • --pretty: The gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default.
  • -r, --relative: With -s, create links relative to link location.
  • -S, --suffix: Override the usual backup suffix, '~', with SUFFIX.
  • -s, --symbolic: Make symbolic links instead of hard links.
  • -t, --target-directory: Specify the DIRECTORY in which to create the links.
  • --theme: Color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default.
  • -v, --verbose: Print name of each linked file.

Exit status

StatusMeaning
0success: every operand was processed
1failure: an operand could not be processed (diagnosed on standard error), or a command-line mistake

Help in the terminal

lnx --help                # options, first examples, exit status
gnux help lnx             # this page: the full manual
gnux help lnx --OPTION    # one option in depth, with its examples

See also

On this page