sax

Overview and usage

sax (scissor in Swedish) is an intuitive way to find your beloved shell commands. sax is somewhat similar to history | grep <COMMAND> but is able to provide you with context. Instead of only having ~/.bash_history as the source you have your own set if files.

Here is the usage help message.

~ $ sax -h
sax [OPTION]... PATTERN [ROW NR]

Options:

  -h    show help
  -i    include $HISTFILE in search files
  -f    append comma separated list of files to look in
  -q    remove $SAXFILE from file list

Examples:
  # Search for find in $SAXFILE and show all matches.
  sax find

  # Search for find in $SAXFILE and return row number 66.
  sax find 66

  # Search for find in $SAXFILE and $HISTFILE and return row number 66.
  sax -i find 66

  # Search for awk in /home/nils/.bash_history and return row nr 66. This is very similar to
  # history awk | grep awk && !66
  sax -qf /home/nils/.bash_history awk 66

  # Search for awk in all .org files found in ~/git/dotfiles and $SAXFILE.
  sax -f `find ~/git/dotfiles/ -type f -iname "*.org" -print | xargs echo | sed 's/ /,/g'` awk

Here is an example org document with a couple of commands. This is our example source and the document path is set as the $SAXFILE environment variable.

#+TITLE: My useful shell commands

* tar
** Compress entire directory or a single file

   https://www.howtogeek.com/248780/how-to-compress-and-extract-files-using-the-tar-command-on-linux/

   #+BEGIN_SRC shell
     tar -czvf name-of-archive.tar.gz /path/to/directory-or-file
   #+END_SRC

** Extract archive

   #+BEGIN_SRC shell
     tar -xzvf archive.tar.gz
   #+END_SRC

* user management
** create new user

   #+BEGIN_SRC shell
    useradd -m -g users -G wheel,video <USER>
   #+END_SRC

* random top heading
** random sub heading
*** some command

    This is not a real command. Just here to show that =sax= finds this section.

    #+BEGIN_SRC shell
      some command where tar is used
    #+END_SRC

Example usage:

~ $ sax tar
3 * tar
4 ** Compress entire directory or a single file
5
6    https://www.howtogeek.com/248780/how-to-compress-and-extract-files-using-the-tar-command-on-linux/
7
8    #+BEGIN_SRC shell
9      tar -czvf name-of-archive.tar.gz /path/to/directory-or-file
10    #+END_SRC
11
12 ** Extract archive
13
14    #+BEGIN_SRC shell
15      tar -xzvf archive.tar.gz
16    #+END_SRC
17
27 *** Some command
28
29     This is not a real command. Just here to show how that =sax= finds this section.
30
31     #+BEGIN_SRC shell
32       some command where tar is used
33     #+END_SRC
~ $ sax tar 15 | wl-copy      # The line nr 15 is now trimmed and added to clipboard
~ $ tar -xzvf archive.tar.gz  # Command is pasted back in the shell from clipboard

In the showcase we look for tar commands as I never can remember the correct arguments to extract an archive. We get a few hits. One of them is in a places where tar is used together with another command. But the major one is a heading matching tar and all of its subsections. On line 15 is the command I am looking for. By running sax again with the same argument + the line nr it returns that line. Trimmed and without a trailing newline. This makes it perfect to pipe into a clipboard.

If a heading contains a match. Its returned together with all of its sub sections.

If a match is found in a non heading line. Only that section is provided.

sax does only 2 things. It looks for a pattern and tries to provide matches together with their context. And it can provide a single line from a set of matches.

Install

Clone the repo to some place, in the examples it’s cloned to: ~/git/sax.

Set environment variable so you can reach sax. Point SAXFILE to your org file.

export PATH="$PATH:$HOME/git/sax/"
export AWKPATH="$AWKPATH:$HOME/git/sax/"
export SAXFILE="$HOME/org-documents/shell-commands.org"
export SAXPIPE=wl-copy

You may need to logout and login again to update environment variables. Or source your .bashrc using: source ~/.bashrc