navtag

Path shortcut manager CLI for Unix-like systems.

Features

• List, add and remove shortcuts
• Resolve shortcut labels to their path
• Resolve paths including shortcut labels to their total path
• Shell extension: shortcut support for built-in commands and more
• Path / label tab-completion for extended commands

Quickstart

1. Clone this repository to any destination
2. Enter the cloned repo and run:

./install.sh

3. If you want to add the extension commands to your shell, follow the instructions generated by install.sh

Useage

From here on, $mfp is equivalent to the path to the shortcut file. List shortcuts:

navtag $mfp -l

Add shortcut:

navtag $mfp -a <label> <path>

Remove shortcut:

navtag $mfp -d <label>

Translate shortcut labels:

navtag $mfp -t [label]

Shell extension

The following commands are implemented in commands.sh, using navtag. They shall be used for managing and manipulating the shortcuts. This is a summary on the usage of every command:

• marks: list all shortcuts
• mark <label> [path]: create a shortcut for given the optional path and label. The default path is the current working directory
• unmark <label>: remove shortcut with given label

The following list are all implemented built-in commands which support shortcuts:

• cd
• cp
• mv
• mkdir

If you would like addtional commands to support path shortcuts, they might be implemented in this branch, or you could configure them by yourself.

Dependencies

You might need to install the bash-completion package. You can check this by running _filedir in your terminal.

Examples:

Here are some small examples given a file structure and shortcuts like below:

.
├── dir1
│   └── dir1.1
│       └── file1.txt
├── dir2
│   └── file2.txt
└── file3.txt

$ marks
Mark file: /some/path/file.txt
LABEL : PATH
------------
d11 : dir1/dir1.1
d2 : dir2

Add new shortcut (for current directory)

mark my_shortcut

Enter dir2

cd d2

or

cd d2/

Move file1.txt to dir2

mv d11/file1.txt d2/.

Copy file3.txt to dir1.1 as file4.txt

cp file3.txt d11/file4.txt

Tips and Tricks

Configure Additional Commands

If you want your favorite command to support your shortscuts / tab-completion of shortcuts, you can check whether it was already implemented in this branch. If not, follow the instructions below. Feel free to contribute your implementation to the local branch! :)

Step 1: Override the current command
Create a function which overrides the command, for this instance the touch command.

touch(){
    navtag "$mfp" -t "$@" | xargs touch
}

Replace every occurence of touch with the name of your respective command. This does not work for commands which can not run as a subprocess, so you might need to implement some workarounds (see implementation of cd). Reload your shell to include the change.

Step 2: Add tab-completion for shortcut labels
In order to support tab-completion of shortcut labels, one needs to implement the respective completion function. These are already implemented in commands.sh: _navtag_labels, _navtag_dir and _navtag_filedir. As the touch commands completion should include labels, directories and files, we need to use the _navtag_filedir function (see comments in commands.sh).

Go to the line where the repective completion is instantiated:

complete -F _navtag_filedir -o nospace mv cp 

Add your command to the list of commands to support the completion:

complete -F _navtag_filedir -o nospace mv cp touch

You can also add aliases to support tab-completion.

Label naming

In order to retain the current behaviour of commands as little as possible, it is adviced to name the shortcut labels to a file / directory after its filename.

Label name collisions

Suppose there was a directory / file docs which has the same name as a shortcut label docs. Using shortcut supported commands on this file might lead to the wrong file (destination of the shortcut) to be used. This can be circumvented by specifying the file as follows:

[command] ./docs

This works because shortcut labels are only considered up to the first '/' of a given path.