hoyo

hoyo is a command-line utility that lets the user save directories as bookmarks (similar to in the browser) and easily cd to them.

Contents

• Installation
  • Uninstalling
• Usage
  • Command-line options
  • Examples
  • Configuration
    • Default command
    • Default bookmarks
• Contributing

Installation

Download hoyo-cli and add to path

You can download binary directly from GitHub releases.

After downloading the binary, make it executable and copy it under convenient location, for example:

$ chmod +x hoyo-cli
$ mv hoyo-cli ~/.local/bin/hoyo-cli

Download shell config script and source

Download this bash script.

Add the following line to your .bashrc:

source path/to/hoyo.sh

Uninstalling

Delete hoyo-cli

$ rm -rf ~/.local/bin/hoyo-cli

Remove config and data files:

$ rm -rf ~/.config/hoyo
$ rm -rf ~/.local/share/hoyo

Usage

Command-line options

Running hoyo --help or hoyo help will display all the global default options, as well as the available commands. For command-specific options, run hoyo <cmd> --help or hoyo help <cmd>.

Set directory bookmarks for quick "cd" behaviour

Usage: hoyo [COMMAND] [-C|--config-file <file>] [-B|--bookmarks-file <file>]
            [--fail] [--nofail] [--time] [--notime] [--enable-clear]
            [--disable-clear] [--enable-reset] [--disable-reset]
            [--backup-before-clear] [--no-backup-before-clear]

  For more help on a particular sub-command, run `hoyo <cmd> --help`.

Available options:
  --version                Display version information and exit
  -C,--config-file <file>  Override the default config file
  -B,--bookmarks-file <file>
                           Override the default bookmarks file
  --fail                   Fail on error
  --nofail                 Disable fail on error
  --time                   Display bookmark creation times
  --notime                 Hide bookmark creation times
  --enable-clear           Enable the 'clear' command
  --disable-clear          Disable the 'clear' command
  --enable-reset           Enable the 'config reset' command
  --disable-reset          Disable the 'config reset' command
  --backup-before-clear    Backup the bookmarks file before running `hoyo clear`
  --no-backup-before-clear Don't backup the bookmarks file before running `hoyo
                           clear`
  -h,--help                Show this help text

Available commands:
  add                      Add a bookmark
  move                     Change directory using a bookmark
  list                     List existing bookmarks
  clear                    Clear all bookmarks
  delete                   Delete a bookmark
  refresh                  Re-calculate bookmark indices
  config                   View/manage hoyo config
  check                    Verify validity of config and bookmarks
  help                     Print a help message for the entire program or a
                           specific command

Bugs:
  If something went wrong unexpectedly or you think there's a problem with hoyo,
  let me know! To report an issue, create a bug report at
  https://github.com/fpringle/hoyo/issues

Online documentation:
  To read the web documentation, visit https://github.com/fpringle/hoyo#readme

Examples

List the current bookmarks

$ hoyo list
1. /home/Documents     (doc)
2. /home/Music/Albums

cd to a bookmark

$ hoyo move doc
$ pwd
/home/Documents
$ hoyo move 2
$ pwd
/home/Music/Albums

Add a new bookmark

$ hoyo add /home h
$ hoyo list
1. /home/Documents     (doc)
2. /home/Music/Albums
3. /home h
$ hoyo move h
$ pwd
/home

Delete a bookmark

$ hoyo delete 2
$ hoyo list
1. /home/Documents  (doc)
3. /home h

Reset bookmark indices

$ hoyo refresh
$ hoyo list
1. /home/Documents  (doc)
2. /home h

View config

$ hoyo config print
fail_on_error = false
enable_clearing = true
backup_before_clear = false
display_creation_time = false
enable_reset = true

Modify config

$ hoyo config set display_creation_time true
$ hoyo list
1. 12/26/22 16:55:13    /home/Documents  (doc)
2. 12/27/22 12:01:55    /home h

Reset config

$ hoyo config reset
Are you sure you want to clear your hoyo configuration? (y/n) y
$ hoyo config print
fail_on_error = false
enable_clearing = false
backup_before_clear = false
display_creation_time = false
enable_reset = false

Clear all bookmarks

$ hoyo clear --enable-clear
Are you sure you want to delete all your saved backups? (y/n) y
$ hoyo list
[ no output ]

Validate your config file

$ hoyo check
Config is good
Bookmarks file is good

Configuration

The default config file is at $XDG_CONFIG_HOME/hoyo/config.toml, which is normally ~/.config/hoyo/config.toml. To use a different config file, see Command-line options.

# a sample hoyo config file, with explanations

# whether to backup the bookmarks file before running the `hoyo clear` command
backup_before_clear     = false

# whether to display bookmark creation time when running the `hoyo list` command
display_creation_time   = false

# set to False to disable the `hoyo clear` command as a safety mechanism
enable_clearing         = true

# set to False to disable the `hoyo config reset` command as a safety mechanism
enable_reset            = false

# whether to fail if we hit a non-fatal error e.g.  adding a bookmark that already exists
fail_on_error           = false

# optionally set a default command - see section "Default command"
default_command         = "list"

# optionally set a list of default bookmarks - see section "Default bookmarks"
[[default_bookmark]]
  directory             = "/home/me"

[[default_bookmark]]
  directory             = "/home/me/coding/haskell"
  name                  = "hask"

Default bookmarks

You can optionally set a list of default bookmarks. When running hoyo for the first time, or running hoyo clear to delete all the existing bookmarks, the bookmarks list will be populated by the bookmarks in this list. A default bookmark can have these fields:

• directory: required. The directory of the bookmark.
• name: optional. Give the bookmark a nickname for easier cd.

Default command

If the default_command option is set, then running hoyo with no arguments will actually run the default command.

For example, if default_command = "list":

$ hoyo      # no arguments
1. /home/me
2. /home/me/coding/haskell  (hask)

If the default_command option is no set, then running hoyo with no arguments is equivalent to running hoyo --help.

Contributing

Please submit any bug reports or feature requests on the issues page.

When submitting pull requests, make sure you've done a few things first:

• If adding a new feature, make sure to add relevant tests.

• Install pre-commit and run pre-commit install inside the root directory of the repository. This sets up pre-commit hooks to run useful scripts (in the scripts directory) like linting, keeping documentation up to date, and running tests.

• Update CHANGELOG.md under the Unreleased section with a short description of your changes.