shmark

Categorized shell directory bookmarking for Bash

shmark is a collection of Bash functions for enabling shell directory bookmarking with optional categories. It allows you to bookmark a directory so that you can easily and quickly return to it later. You can organize the bookmarks list in categories and rearrange the list of bookmarks in any order. shmark also includes Bash completions allowing you to type a partial command or directory path and then hit the tab key to auto-complete the command.

The shmark function can be called with shmark or, if the optional aliases are installed, it can be called with just bm (short for “bookmark”). The other optional alias that can be installed is go for shmark cd. You can instead define your own aliases if the included ones conflict with existing commands or aliases on your system or if you’d just like to add aliases for more shmark actions. The included aliases and completions can be used as examples in those cases.

Features

Bookmark shell directories so that they can be quickly returned to later.
Change to a bookmarked directory using either its list position or tab completion for its name/path.
Show a list of bookmarked directories.
Bookmarks can be assigned a category. The bookmarks are sorted by category when listing. (Some examples of category names might be “@CURRENT”, “@NEXT” or “@PENDING” for GTD-style categories, and “RECENT” or “MISC” for others.)
Rearrange bookmarks in the saved bookmark list.
Change a bookmark’s category.
Delete a bookmark.
Insert a bookmark into a specific list position when adding it.
Undo the last action.
Declare a default action that shmark will run when called without any arguments (list for example).

Usage

The following is a typical example of basic usage (shortcuts are shown in comments).

Start by changing to a directory normally:
```
$ cd ~/Desktop/foo
```

Bookmark the directory with shmark:

$ shmark add            # or `shmark a` or just `bm a`

Change to another directory normally:
```
$ cd ~/Desktop/bar
```
Bookmark the directory, this time with an optional category:
```
$ shmark add @CURRENT   # or `bm a @CURRENT`
```
List your categorized directory bookmarks (notice that uncategorized bookmarks are omitted):
```
$ shmark list           # or `bm ls`
@CURRENT
  1) ~/Desktop/bar
```

List all bookmarks. Uncategorized bookmarks will be listed under a configurable default category:

$ shmark listall        # or `bm lsa`
@CURRENT
  1) ~/Desktop/bar
MISCELLANEOUS
  2) ~/Desktop/foo

Assign a category (in this case “@NEXT”) to the uncategorized bookmark (identified by its current list position: 2):
```
$ shmark chcat @NEXT 2  # or `bm cc @NEXT 2`
```

List the categorized bookmarks again to see the change:

$ shmark list           # or `bm ls`
@CURRENT
  1) ~/Desktop/bar
@NEXT
  2) ~/Desktop/foo

Change to a bookmarked directory using its list number:

$ shmark cd 2           # or `bm cd 2` or `bm -2` or just `go 2`
~/Desktop/foo

Change to a bookmarked directory using tab completion:

$ shmark cd bar[TAB]    # or `bm cd bar[TAB]` or `go bar[TAB]`
~/Desktop/bar

Those are a few of the most common commands, but there are many more commands that can be used for things such as deleting a bookmark, moving a bookmark in the list, inserting a bookmark into a specific list position, and more. Here is a brief listing of the available commands:

$ shmark -h
Usage: shmark [-hV] [-f bookmark_file] [-#] [action] [bookmark|category]

Actions:
    add|a [CATEGORY]
    append|app [CATEGORY]
    cat
    cd|go [BOOKMARK]
    cd|go [NUMBER]
    chcat|cc [-f] CATEGORY [BOOKMARK]
    chcat|cc [-f] CATEGORY [NUMBER]
    del|rm [-f] [BOOKMARK]
    del|rm [-f] [NUMBER]
    edit|ed
    env
    help [ACTION]
    index|idx
    insert|ins NUMBER
    list|ls [-#] [CATEGORY]
    listall|lsa [-#] [CATEGORY]
    listcat|lsc
    listdir|lsd
    listunsort|lsus
    move|mv [-f] [FROM_POSITION] TO_POSITION
    print
    shorthelp
    undo

Try the "help" action for full details.

Configuration

shmark can be customized by exporting a few environment variables in your .bash_profile or .bashrc file.

Default Action

Specify a default action that shmark will run when called without any arguments (see the output of the -h option or the help action for a list of available actions):

export SHMARK_DEFAULT_ACTION=list

Default Category

If no category is specified when adding a bookmark, the bookmark will appear under a default category of “MISCELLANEOUS” which is always listed as the last category. To change the name of that default category, export an environment variable with the desired category name, for example:

export SHMARK_DEFAULT_CATEGORY=Archive

Bookmarks File Name

By default, shmark will save bookmarks in a ~/var/shmark/bookmarks file if it finds a ~/var directory or in ~/.shmark/bookmarks otherwise. A custom file path can be specified instead (including a custom parent directory for the file is a good idea because the function creates backup and temporary files):

export SHMARK_FILE=$HOME/.some_directory/my_shmarks

Installation

shmark is a Bash functions file along with some optional aliases and Bash completion files. These files need to be sourced into your shell environment. To install the files and enable them:

cd to the directory containing the shmark source code and run:
```
$ make
```
Run one of the following commands depending on which files you wish to install:
```
$ make install      # Default: main functions and completion files.
$ make install-all  # Same as the default, plus optional aliases.
$ make install-min  # Only the main functions file; no completions or aliases.
```
Details:
- make install installs the main shmark functions file and its Bash completion file in the ~/.bash_functions.d and ~/.bash_completion.d directories respectively. If you’d rather install them somewhere else, then only run make and then copy or move the files from the build directory to your desired location.
- make install-all installs two extra files in addition to the main shmark functions and completion files installed by make install. The extra files provide the short bm and go aliases along with completions for those aliases. You could instead just use those as examples to define your own aliases and completions.
- make install-min only installs the main functions file without installing the completions or aliases.
To enable the functions, aliases, and completions, you’ll need to source the files into your shell environment. If you installed the files in the default directories, you could add something like the following to your ~/.bash_profile or .bashrc file:
```
# Enable custom Bash functions:
if [ -d ~/.bash_functions.d ]; then
    for f in ~/.bash_functions.d/*.sh; do
        . "$f"
    done
    unset f
fi

# Enable custom Bash completions:
if [ -d ~/.bash_completion.d ]; then
    for f in ~/.bash_completion.d/*.sh; do
        . "$f"
    done
    unset f
fi
```
If you only have single files to enable, you could still use code like the above, or you could instead just use lines such as:
```
. ~/.bash_functions.d/shmark.sh
```
And:
```
. ~/.bash_completion.d/shmark.sh
```

Bugs

Please report any bugs using the GitHub issue tracker for shmark. If you don’t have a GitHub account, you can instead use this site’s email contact form.

Credits

shmark was written by Steve Wheeler.

License

shmark is free software available under the terms of a BSD-style (3-clause) open source license.