beenotung/realpath-cli

Node.js shim of the Linux-style realpath command for macOS compatibility

realpath-cli

Node.js shim of the Linux-style realpath command for macOS compatibility.

Introduction

realpath-cli is a Node.js command-line utility that mimics the Linux-style realpath command, enhancing macOS compatibility. It resolves the absolute path of provided files, with support for symbolic links and the ability to output paths relative to a specified directory. This tool is particularly useful for scripts and applications requiring consistent path resolution across different operating systems, ensuring that macOS users can achieve the same path resolution results as those on Linux.

Installation

To install realpath-cli with npm, run the following command:

npm install -g realpath-cli

This will download this package and make realpath and realpath-cli commands available in your PATH, allowing it to be run from anywhere in your terminal.

Usage

realpath [options] <file>

Options

• -h, --help: Display the help message and exit.
• -v, --version: Output version information and exit.
• -s: Treat the link symbolically instead of resolving it.
• --relative-to=path: Output the relative path with respect to the directory provided. If no path is specified immediately after, it expects the next argument to be the path.

Arguments

• <file>: The file path to resolve to its absolute path.

Examples

Resolve the absolute path of a SQLite database file:

realpath data/db.sqlite3

Resolve the path symbolically:

realpath -s data/db.sqlite3

Output the relative path with respect to the current working directory:

realpath --relative-to="$PWD" data/db.sqlite3

Combine symbolic link handling with relative path output:

realpath -s --relative-to "$PWD" data/db.sqlite3

Note on environment setup

When using realpath-cli, it's essential to ensure that the Node.js installation path (where npx and npm are installed) appears before the system path in your PATH environment variable. This setup is crucial because it ensures that when you run realpath-cli or any other Node.js-based command-line tools, your system uses the Node.js version from your Node.js installation rather than any system-provided versions that might exist.

If you do not prefer to put all Node.js cli packages before the system bins, it is possible to configure your environment so that only specific Node.js packages, like realpath-cli, are prioritized over system binaries without affecting the priority of all other system binaries. You can achieve this by selectively modifying your PATH environment variable or using symbolic links. Here are two approaches you might consider:

1. Using Symbolic Links

You can create a symbolic link for realpath-cli in a directory that is higher up in the PATH priority than the system directories but not change the overall order for other Node.js tools. Here's how you can do it:

1. Identify: First, find out where realpath-cli is installed. This is typically inside the node_modules/.bin directory in your global npm installation path. You can find it using:

which realpath-cli

2. Create a symbolic link: Choose or create a directory that is earlier in the PATH than your system paths but not earlier than your Node.js path. For example, if /usr/local/bin is suitable, you can create a symbolic link there:

ln -s /path/to/node_modules/.bin/realpath-cli /usr/local/bin/realpath

Replace /path/to/node_modules/.bin/realpath-cli with the actual path obtained from the which command.

In typical setting, you may need to run the ln with sudo, i.e.

sudo ln -s /path/to/node_modules/.bin/realpath-cli /usr/local/bin/realpath

2. Custom PATH Modification for Specific Sessions

If you prefer not to use symbolic links, you can modify the PATH for specific terminal sessions to prioritize realpath-cli.

1. Write a script: Create a small shell script that modifies the PATH only for the duration of your terminal session:

For example in realpath-cli-path.sh:

#!/bin/bash
export PATH="/path/to/realpath-cli-directory:$PATH"
exec "$SHELL"

Ensure /path/to/realpath-cli-directory is the directory containing realpath-cli.

2. Use the script: Whenever you need to prioritize realpath-cli, start your terminal session by running this script:

./realpath-cli-path.sh

Examples of actual path for /path/to/realpath-cli-directory include:

• /opt/homebrew/bin
• /Users/username/.nvm/versions/node/v20.12.1/bin

This approach allows you to have realpath-cli take precedence over same-name system binaries without globally affecting the order of all other system binaries. This can be particularly useful in environments where you need to maintain the default system behavior for other tools but require specific behavior for realpath-cli.

Credit

This documentation is generated by GPT-4 then modified manually.

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

• The freedom to run the program as you wish, for any purpose
• The freedom to study how the program works, and change it so it does your computing as you wish
• The freedom to redistribute copies so you can help others
• The freedom to distribute copies of your modified versions to others