rreadlink

rreadlink

A multi-platform Unix CLI that prints a symlink's complete chain of targets using absolute paths.

The primary purpose of rreadlink (recursive readlink) is to follow a given symlink to its ultimate target, printing all intermediate symlinks along the way.
All paths are printed as absolute paths, with the ultimate target printed in canonical form.

This is hepful on Linux platforms, for instance, where some utilities are installed as symlinks that point to other symlinks before resolving to the ultimate target, making it difficult to understand what is ultimately invoked; e.g., on some Linux distros /usr/bin/nawk links to /etc/alternatives/nawk, which in turn links to the actual target, /usr/bin/gawk.
Note that the native GNU readline can either only give you the next target (not the ultimate one), or, with -f or -e or -m, only the ultimate target (not intermediate ones).

Loosely speaking, rreadlink provides the functionality of GNU readline -e while also including intermediate targets. rreadlink has the added advantage of being multi-platform (see Supported Platforms below).

Alternatively, given a non-symlink, rreadlink prints the argument's canonical path (i.e., any directory components that are symlinks are resolved to their ultimate targets).

See the Usage chapter for details.

^{See also: typex provides information about executables in the path (among other things) and has rreadlink's behavior built in to show what file is ultimately invoked.}

Supported Platforms

Any Unix-like platform with POSIX-compatible utilities, with bash installed; for instance, Linux and OS X.

Quick Examples

# Print the symlink chain for executable /usr/bin/nawk (e.g., on Ubuntu):
$ rreadlink /usr/bin/nawk
/usr/bin/nawk@ -> /etc/alternatives/nawk@ -> /usr/bin/gawk

# Ditto, but printing one path per line, without the symlink sigil (@):
# (This format is the default when not outputting to a terminal.)
$ rreadlink -1 /usr/bin/nawk
/usr/bin/nawk
/etc/alternatives/nawk
/usr/bin/gawk

# Canonicalize the path of a non-symlink:
# (Assume that /var links to /private/var and that log is a regular file.)
$ rreadlink /var/log
/private/var/log

Installation

With node.js installed, install via the npm registry (you may have to prepend sudo):

npm install rreadlink -g

Usage

$ rreadlink --help


SYNOPSIS
  rreadlink [-s|-1] symLink
  rreadlink -e symLink

DESCRIPTION
  Recursive readlink: prints the CHAIN OF SYMLINKS
  from the input file to its ultimate target, using ABSOLUTE PATHS.

  -s
    Short output format - a single line is output with ' -> ' between paths,
    with symlinks marked with a terminal '@' (similar to  `ls -lF`).
    This is the default output format when printing to a terminal.

  -1 
    (The number one.) One-line-per-path output format.
    Prints each output path on its own line, without the terminal '@'.
    This is the default output format when not printing to a terminal.

  -e
    Prints only the *ultimate* target's absolute path.
    Same as GNU readlink's -e (--canonicalize-existing) option.
  
  If the input file is indeed a symlink, you'll get at least 2
  output paths (unless -e is specified): the input symlink and its
  target; if there are intermediate symlinks, you'll get more.

  While each file is output by its absolute path, it is only
  the *ultimate* target whose path will be *canonical*.

  CAVEAT: *Circular* symlinks are NOT detected and will result in
  an infinite loop.

  If any of the files in the chain do not exist, processing
  stops, an error message is output and exit code 1 is returned.

  If the input file is NOT a symlink, only *its* full path is
  printed in its *canonical* form. I.e., the file's directory
  path - if it happens to have symlink components - is resolved to
  its ultimate target.

  Thus, you can use
    rreadlink -e anyFile
  on any existing filesystem object, and you'll either get its own
  canonical path (if not a symlink) or its ultimate target's canonical
  path (if a symlink).

EXAMPLES
    # Prints the chain of symlinks for the `git` executable
    # in the $PATH.
  rreadlink $(which git)
    # Prints the canonicalized path of the given non-symlink.
    # (Example from OSX, where /var links to /private/var.)
  rreadlink /var/log  # -> '/private/var/log'

License

Copyright (c) 2015 Michael Klement, released under the MIT license.

Acknowledgements

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: (D) denotes a development-time-only dependency, (O) an optional dependency, and (P) a peer dependency.

npm dependencies

• json (D)
• replace (D)
• semver (D)
• shall (D)
• urchin (D)

Changelog

Versioning complies with semantic versioning (semver).

• v0.1.5 (2015-06-26):

  • [doc] Read-me: npm badge changed to shields.io; license badge added; typo fixed.
  • [dev] To-do added; Makefile updated.

• v0.1.4 (2015-05-30):

  • [doc] npm registry badge added.

• v0.1.3 (2015-02-11):

  • Doc: Read-me improvements.

• v0.1.2 (2015-02-11):

  • Doc: Read-me and CLI help improvements.

• v0.1.1 (2015-02-11):

  • Dev: Tests improved.

• v0.1.0 (2015-02-11):

  • Initial release.