alphapapa/bucket

These cats all have buckets. Where’s your bucket?

bucket is like a clipboard manager for the shell. Or it’s like Emacs/Vim-style registers for the shell. It makes it easy to save clips of text to named “buckets” (or a default, unnamed bucket) and access them later.

Examples

Pour into default bucket by argument:

$ bucket "I wondered why the frisbee was getting bigger, and then it hit me"

Pour from default bucket:

$ bucket
I wondered why the frisbee was getting bigger, and then it hit me

Pipe default bucket into named bucket:

$ bucket | bucket jokes

Pipe into named bucket, verbosely:

$ dmesg | grep error | bucket -v errors
[    7.817768] EXT4-fs (sdc1): re-mounted. Opts: errors=remount-ro,user_xattr

Pour from named bucket:

$ bucket errors
[    7.817768] EXT4-fs (sdc1): re-mounted. Opts: errors=remount-ro,user_xattr

Append to a bucket by argument:

$ bucket -a jokes "A plateau is the highest form of flattery."
$ bucket jokes
I wondered why the frisbee was getting bigger, and then it hit me
A plateau is the highest form of flattery.

List buckets:

$ bucket -l
bucket  errors  jokes

List buckets verbosely (just the first line of each bucket):

$ bucket -lv
bucket: I wondered why the frisbee was getting bigger, and then it hit me
errors: [    7.817768] EXT4-fs (sdc1): re-mounted. Opts: errors=remount-ro,user_xattr
jokes: I wondered why the frisbee was getting bigger, and then it hit me

List buckets completely:

$ bucket -lV
bucket:
I wondered why the frisbee was getting bigger, and then it hit me

errors: 
[    7.817768] EXT4-fs (sdc1): re-mounted. Opts: errors=remount-ro,user_xattr

jokes:
I wondered why the frisbee was getting bigger, and then it hit me
A plateau is the highest form of flattery.

Grep buckets:

$ bucket -g frisbee
bucket:I wondered why the frisbee was getting bigger, and then it hit me
jokes:I wondered why the frisbee was getting bigger, and then it hit me

Edit buckets (using $EDITOR):

$ bucket -e
Waiting for Emacs...
$ bucket -e jokes
Waiting for Emacs...

Empty buckets:

$ bucket -E
$ bucket
$ bucket -E jokes
$ bucket jokes

Expire old buckets:

$ sleep 14d  # Default: 2 weeks
$ bucket -x
$ bucket -l

And, of course, you can always:

$ bucket <(echo '
                  ___
   ___======____=---=)
 /T            \_--===)
 [ \ (0)   \~    \_-==)
  \      / )J~~    \-=)
   \\\\___/  )JJ~~~   \)
    \_____/JJ~~~~~    \\
    / \  , \J~~~~~     \\
   (-\)\=|\\\\\~~~~       L__
   (\\\\)  (\\\\\)_           \==__
    \V    \\\\\) ===_____   \\\\\\\\\\\\
           \V)     \_) \\\\\\\\JJ\J\)
                       /J\JT\JJJJ)
                       (JJJ| \UUU)
                        (UU)')
$ bucket | cat
*purr*

# or
$ make cheezburger | bucket
$ bucket | cat
                 .-.   _                __
                `  )`'-,`\        .-''``.-'
   _.-''-.      _.'       `'--._.' ,-'  /
   `\    _`'--'`                      .'
     '._ _`-       .--.   .--.      (`
        `.'       /    '.'    \      '.
       .'         \  0  |  0  /        '.
      /   _        '._.---._.'      _    \
      /    `'-.      (     )    .-'`     \
      / .---'_.   .   `-,-`  .  ._'---.  \
      |   -'`   .       |      .  `'-    |
      /_       .   '   /;\  '    .     ,_\
        '-.     '-..-`( ' )`-..-'     /
           '._         '-'         _.'
              '-..,__       __,..-'
                     `'---'`

Usage

Yes, you can haz usage.

Usage:
    command | bucket [OPTIONS] [BUCKET]
    bucket [OPTIONS] [BUCKET] [DATA]

The first form reads data from STDIN and writes to the default bucket,
or BUCKET if given.  The second form reads DATA and/or BUCKET from
arguments, writing to a bucket or printing a bucket's contents.

Options:
    -a, --append                Append to bucket
    -d, --date                  Sort by date
    -e, --edit                  Edit bucket
    -E, --empty                 Empty bucket
    -g PATTERN, --grep PATTERN  Grep in buckets
    -h, --help                  i can Haz cheezburger?
    -l, --list                  List buckets
    -v, --verbose               Verbose output
    -V, --VERBOSE               VERY verbose output
    -x, --expire                eXpire old buckets (default: +14 days)
    --directory DIRECTORY       Bucket storage directory

Installation

Automatic

To install bucket automatically, run sudo make install, which will install the Bash script, the Fish completions, the man page, and this README file.

Note: I recommend using the fantastic checkinstall utility, which automatically turns any make install command (or any other command) into a Debian/RPM package and installs it using your distro’s package manager. This helps you keep track of what software you have installed, and makes it easy to uninstall software. checkinstall should be packaged in nearly all Linux distros.

If you want to install the Fish script, run sudo make install-fish, which will do all of the above, except with the Fish script instead of the Bash script.

Manual

Or, you can install it manually, e.g. into your homedir:

bucket.sh or bucket.fish should go into a directory in your PATH. You will probably want to remove the extension or symlink it to make it easier to type.
completions/bucket.fish can be put in ~/.config/fish/completions, and then Fish will provide TAB auto-completion for options and bucket names.
getopts.fish should be put in ~/.config/fish/functions if you are using bucket.fish.
bucket.1 should go in ~/.local/share/man/man1.

Uninstallation

If you installed with make install, you can uninstall bucket (D:) with sudo make uninstall.

Files

bucket is provided as both a Bash script, bucket.sh, and a Fish script, bucket.fish. They work identically (or else it’s a bug!). But Fish makes more sense, because how could you put a bash in a bucket? But Bash is faster, because how fast is a goldfish, really?
completions/bucket.fish can be put in ~/.config/fish/completions, and then Fish will provide TAB auto-completion for options and bucket names.
getopts.fish is used by the Fish version, and it’s not yet part of the standard Fish distribution, so it’s included here for convenience. Just drop it into ~/.config/fish/functions. (And check it out! It works really well and is well-documented.)
bucket.1 is the man page, man.
Makefile is how we make the donuts.

Configuration

Empty/expire commands
- The default command for empty and expire is trash-put, part of the trash-cli package,which may not be installed on your system by default. trash-cli is a great package, so I recommend installing it. It uses the standard XDG trash bin from the terminal.
- If you prefer, you can easily change the default to rm by changing the deleteCommand variable near the top of the script.
- Or you could change it to something like mv -t ~/.local/share/Trash/files, although that might cause the trashed files to not show up in GUI trash apps, since they would be missing the .trashinfo files.
Storage directory
- The default directory for bucket storage is ~/.cache/bucket. ~/.cache is probably excluded by most backup programs (it should be), so this seems like a good place for buckets, since buckets are intended to be temporary storage.
- However, you can set a custom directory using the --directory option. Unlike the default directory, it will not be created for you if it doesn’t exist. You might set this option in an alias, that way whenever you use that alias, the buckets would be stored in that directory. This could be helpful if you wanted to store a certain set of buckets more permanently, in a place where they would typically be included in backups.

Aliases

If you like to think in terms of registers, you might like to alias bucket to something like r so you can do:

$ alias r bucket
$ rgrep funny /usr/share/games/fortunes | r jokes
$ r jokes
...
people:We all know that no one understands anything that is not funny.
...

$ alias rl "bucket -l"
$ rl
jokes

Or you might like to use:

$ alias buckets "bucket -l"
$ buckets
jokes

If you like to keep a to-do list, you might find this handy:

$ alias rt "bucket today"
$ alias rta "'bucket -a today"
$ rta Walk the cat
$ rt
Walk the cat
$ rta Feed the cat
$ rt
Walk the cat
Feed the cat
$ cat --walk --feed
MEOW!
*purr*
$ rt -E
$ rt
$

If you want to store buckets more permanently, like for a personal log, you might use an alias like:

$ alias log 'bucket.sh --directory ~/.log --append $(date --rfc-3339=date) $(date +%H:%M)'
$ log "Gus said that he wants to get a fish, just as a pet.  I'm afraid I don't trust him."
$ log "Just as I suspected, I caught him ordering tartar sauce online.  He'll be eating nothing but cheezburgers from now on."
$ log -lV
2015-10-25:
20:26 Gus said that he wants to get a fish, just as a pet.  I'm afraid I don't trust him.
21:12 Just as I suspected, I caught him ordering tartar sauce online.  He'll be eating nothing but cheezburgers from now on.

Note: bucket.sh handles arguments slightly differently than bucket.fish. The Bash version allows specifying options and arguments in any order, while the Fish version treats all options after the first non-option argument as non-option arguments. This means that the Bash version allows a command like bucket.sh --directory ~/.log --append Monday 13:37 -l -V, and the -l -V would cause the script to list buckets verbosely; but the same command using bucket.fish would append the string 13:37 -l -V to the Monday bucket. So if you use the Fish version and want to use an alias like this, you’ll need to use a separate alias for listing, like:

alias logV 'bucket.fish --directory ~/.log -lV'

Development

I can’t think of much else to add right now. But I welcome suggestions and pull requests. Bug reports may be kept to yourself (just kidding).

License

I really don’t think a license is necessary for something this straightfoward. But consider it GPL’ed.

alphapapa / bucket