[[buckets.jpg]]

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: #+BEGIN_SRC sh $ bucket "I wondered why the frisbee was getting bigger, and then it hit me" #+END_SRC

Pour from default bucket: #+BEGIN_SRC sh $ bucket I wondered why the frisbee was getting bigger, and then it hit me #+END_SRC

Pipe default bucket into named bucket: #+BEGIN_SRC sh $ bucket | bucket jokes #+END_SRC

Pipe into named bucket, verbosely: #+BEGIN_SRC sh $ dmesg | grep error | bucket -v errors [ 7.817768] EXT4-fs (sdc1): re-mounted. Opts: errors=remount-ro,user_xattr #+END_SRC

Pour from named bucket: #+BEGIN_SRC sh $ bucket errors [ 7.817768] EXT4-fs (sdc1): re-mounted. Opts: errors=remount-ro,user_xattr #+END_SRC

Append to a bucket by argument: #+BEGIN_SRC sh $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. #+END_SRC

List buckets: #+BEGIN_SRC sh $ bucket -l bucket errors jokes #+END_SRC

List buckets verbosely (just the first line of each bucket): #+BEGIN_SRC sh $ 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 #+END_SRC

List buckets completely: #+BEGIN_SRC sh $ 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. #+END_SRC

Grep buckets: #+BEGIN_SRC sh $ 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 #+END_SRC

Edit buckets (using =EDITOR=): #+BEGIN_SRC sh bucket -e Waiting for Emacs... $ bucket -e jokes Waiting for Emacs... #+END_SRC

Empty buckets: #+BEGIN_SRC sh $bucket -E$ bucket $bucket -E jokes$ bucket jokes #+END_SRC

Expire old buckets: #+BEGIN_SRC sh sleep 14d # Default: 2 weeks bucket -x $ bucket -l #+END_SRC

And, of course, you can always: #+BEGIN_SRC sh 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 / '. / _ '..---..' _
/ '-. ( ) .-'
/ .---'. . -,- . .'---.
| -' . | . '- | / . ' /;\ ' . ,
'-. '-..-( ' )-..-' / '. '-' .' '-..,_ __,..-' '---' #+END_SRC

** Usage Yes, you can haz usage.

#+BEGIN_SRC 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 #+END_SRC

** 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 :PROPERTIES: :ID: fa457145-d56c-4674-95c1-b1f162758730 :END: If you like to think in terms of registers, you might like to alias bucket to something like r so you can do:

#+BEGIN_SRC sh $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 #+END_SRC

Or you might like to use:

#+BEGIN_SRC sh $alias buckets "bucket -l"$ buckets jokes #+END_SRC

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

#+BEGIN_SRC sh $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$ #+END_SRC

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

#+BEGIN_SRC sh $alias log 'bucket.sh --directory ~/.log --append$(date --rfc-3339=date) $(date +$ 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. #+END_SRC

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:

#+BEGIN_SRC sh alias logV 'bucket.fish --directory ~/.log -lV' #+END_SRC

** 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.