Breadcrumbs

Making upward navigation in symlinks intuitive and maintainable.

Breadcrumbs offer a simpler way to move up in directory hierarchies by using symbolic links with easy-to-understand "breadcrumbs" markers. This replaces the confusing ../ sequences, making it easier to track and manage paths.

Concept

Traditional Approach

Consider the following directory structure:

project/
│
├─── module1/
│    └─── sub1/
│         └─── file1.txt
│
└─── module2/
     └─── sub2/

With the usual method, to create a symlink inside sub2 to file1.txt, we run:

ln -s ../../module1/sub1/file1.txt

Problems:

• Obscurity: Multiple ../ sequences can be hard to decipher, especially in deeper directory structures.
• Maintenance: When restructuring directories, updating numerous symlinks becomes tedious.
• Brittleness: Modifying the directory structure can not only break links, but may also unintentionally reference existing files, leading to unpredictable issues.

Breadcrumbs Approach

Using Breadcrumbs, the "upward" path from sub2 to the project directory becomes more intuitive, such as ..project/module1/sub1/file1.txt.

How It Works:

1. Initialization: A breadcrumb symlink named ..project is created inside the project directory, pointing to the project directory itself (.).
2. Progression: As we traverse towards sub2, at each step, another breadcrumb symlink ..project is created pointing to the parent directory's breadcrumb (../..project).
3. End Result: By the time we reach sub2, we've established a trail of breadcrumb symlinks, guiding us from sub2 back to the project directory seamlessly.

After setting up breadcrumbs for the given example, we get the following:

project/
│
├─── module1/
│    └─── sub1/
│         └─── file1.txt
│
├─── module2
│    │
│    ├─── sub2/
│    │    └─── ..project -> ../..project
│    │
│    └─── ..project -> ../..project
│
└─── ..project -> .

Then, to create a symlink inside sub2 to file1.txt, just run:

ln -s ..project/module1/sub1/file1.txt

Benefits:

• Clarity: Instead of puzzling over multiple ../, the ..project/ breadcrumb explicitly indicates the journey up to the project directory.
• Maintainability: Breadcrumbs simplify symlink updates; adding or removing hierarchy levels often requires minimal to no breadcrumb adjustments.
• Robustness: When a significant structural change occurs, the breadcrumb symlink explicitly fails, preventing unintended file references.
• Documentation: The presence of breadcrumbs highlights inter-module file references, offering clear insights into file dependencies.

Script

The repository also includes a ready-to-use script that showcases how this method works in practice.

Installation

Download the tarball and extract:

wget https://github.com/niqodea/breadcrumbs/releases/download/v0.2.0/breadcrumbs-v0.2.0-x86_64-unknown-linux-gnu.tar.gz
tar -xzf breadcrumbs-v0.2.0-x86_64-unknown-linux-gnu.tar.gz

then cp the breadcrumbs binary in the bin directory.

1. Global Installation:

   sudo cp breadcrumbs /usr/bin
   

2. Local Installation: First, ensure ~/.local/bin is in your PATH. Then:

   cp breadcrumbs ~/.local/bin
   

Usage

Refer to the command's help message:

breadcrumbs --help

For example, to create a trail of breadcrumbs from the current directory to the one two levels above, run:

breadcrumbs trail ../..