shmark
Categorized shell directory bookmarking for Bash
- Download: shmark 0.2.1 (March 26, 2016)
- Source code repository
- Issue tracker
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 runmake
and then copy or move the files from thebuild
directory to your desired location. -
make install-all
installs two extra files in addition to the main shmark functions and completion files installed bymake install
. The extra files provide the shortbm
andgo
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
Copyright © 2014–2016 Steve Wheeler.
shmark is free software available under the terms of a BSD-style (3-clause) open source license.