PATH arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one PATH per line. It is an error to supply PATH arguments on the command line and on standard input.
Arguments beginning with ``-`` are normally interpreted as switches; ``--`` causes the following arguments not to be treated as switches even if they begin with ``-``. Switches and required arguments are recognized only on the command line.
All subcommands accept a ``-q`` or ``--quiet`` switch, which suppresses the usual output but exits with the documented status. In this case these commands will quit early, without reading all of the available input.
All subcommands also accept a ``-z`` or ``--null-in`` switch, which makes them accept arguments from stdin separated with NULL-bytes. Since paths on uni can't contain NULL, that makes it possible to handle all possible paths and read input from e.g. ``find -print0``. If arguments are given on the commandline this has no effect.
All subcommands also accept a ``-Z`` or ``--null-out`` switch, which makes them print output separated with NULL instead of newlines. This is for further processing, e.g. passing to another ``path`` with ``--null-in``, or ``xargs -0``. This is not recommended when the output goes to the terminal or a command substitution.
Some subcommands operate on the paths as strings and so work on nonexistent paths, while others need to access the paths themselves and so filter out nonexistent paths.
``path base`` returns the basename for the given path. This is the part after the last "/", discounting trailing slashes. In other words, it is the part that is not the dirname (discounting superfluous slashes).
It returns 0 if there was a basename, i.e. if the path wasn't empty or just slashes.
``path dir`` returns the dirname for the given path. This is the part before the last "/", discounting trailing slashes. In other words, it is the part that is not the basename (discounting superfluous slashes).
It returns 0 if there was a dirname, i.e. if the path wasn't empty or just slashes.
``path extension`` returns the extension for the given path. This is the part after (and excluding) the last ".", unless that "." followed a "/" or the basename is "." or "..", in which case there is no extension and nothing is printed.
If the filename ends in a ".", the extension is empty, so an empty line will be printed.
``path filter`` returns all of the given paths that match the checks it was given. In all cases, the paths need to exist, nonexistent paths are always filtered.
The available filters are:
-``-t`` or ``--type`` with the options: "dir", "file", "link", "block", "char", "fifo", "socket" and "link", in which case the path needs to be a directory, file, link, block device, character device, named pipe, socket or symbolic link, respectively.
-``-p`` or ``--perm`` with the options: "read", "write", and "exec", as well as "suid", "sgid", "sticky", "user" (referring to the path owner) and "group" (referring to the path's group), in which case the path needs to have all of the given permissions for the current user.
Note that the path needs to be *any* of the given types, but have *all* of the given permissions. The filter options can either be given as multiple options, or comma-separated - ``path filter -t dir,file`` or ``path filter --type dir --type file`` are equivalent.
And if your operating system doesn't support a "sticky" bit, checking for it will always be false, so no path will pass.
With ``--invert``, the meaning of the filtering is inverted - any path that wouldn't pass (including by not existing) passes, and any path that would pass fails.
``path normalize`` returns the normalized versions of all paths. That means it squashes duplicate "/" (except for two leading "//"), collapses "../" with earlier components and removes "." components.
It is the same as ``realpath --no-symlinks``, as it creates the "real", canonical version of the path but doesn't resolve any symlinks. As such it can operate on nonexistent paths.
It returns 0 if any normalization was done, i.e. any given path wasn't in canonical form.
Examples
^^^^^^^^
::
>_ path normalize /usr/bin//../../etc/fish
# The "//" is squashed and the ".." components neutralize the components before
/etc/fish
>_ path normalize /bin//bash
# The "//" is squashed, but /bin isn't resolved even if your system links it to /usr/bin.
``path normalize`` returns the normalized, physical versions of all paths. That means it resolves symlinks and does what ``path normalize`` does: it squashes duplicate "/" (except for two leading "//"), collapses "../" with earlier components and removes "." components.
It is the same as ``realpath``, as it creates the "real", canonical version of the path. As such it can't operate on nonexistent paths.
It returns 0 if any normalization or resolution was done, i.e. any given path wasn't in canonical form.
Examples
^^^^^^^^
::
>_ path real /bin//sh
# The "//" is squashed, and /bin is resolved if your system links it to /usr/bin.
``path strip-extension`` returns the given paths without the extension. This is the part after (and excluding) the last ".", unless that "." followed a "/" or the basename is "." or "..", in which case there is no extension and the full path is printed.
This is, of course, the inverse of ``path extension``.
It returns 0 if there was an extension.
Examples
^^^^^^^^
::
>_ path strip.extension ./foo.mp4
./foo
>_ path strip-extension ../banana
../banana
# but status 1, because there was no extension.
>_ path strip-extension ~/.config
/home/alfa/.config
# status 1
>_ path extension ~/.config.d
/home/alfa/.config
# status 0
>_ path extension ~/.config.
/home/alfa/.config
# status 0
Combining ``path``
-------------------
``path`` is meant to be easy to combine with itself, other tools and fish.
This is why
-``path``'s output is automatically split by fish if it goes into a command substitution, so just doing ``(path ...)`` handles all paths, even those containing newlines, correctly
-``path`` has ``--null-in`` to handle null-delimited input, and ``--null-out`` to pass on null-delimited output
Some examples of combining ``path``::
# Expand all paths in the current directory, leave only executable files, and print their real path
