eg-examples for Mac

eg Useful examples at the command line.

Overview

eg provides examples of common uses of command line tools.

Man pages are great. How does find work, again? man find will tell you, but you'll have to pore through all the flags and options just to figure out a basic usage. And what about using tar? Even with the man pages tar is famously inscrutable without the googling for examples.

No more!

eg will give you useful examples right at the command line. Think of it as a companion tool for man. eg comes from _exempli gratia_, and is pronounced like the letters: "ee gee".

Installation

With pip

With brew

Run from source

Clone the repo and create a symlink to eg_exec.py. Make sure the location you choose for the symlink is on your path: Note that the location of eg_exec.py changed in version 0.1.x in order to support Python 3 as well as 2. Old symlinks will print a message explaining the change, but you'll have to update your links to point at the new location. Or you can install with pip or brew.

eg doesn't ship with a binary. Dependencies are very modest and should not require you to install anything (other than pytest if you want to run the tests). If you find otherwise, open an issue.

Usage

eg

eg takes an argument that is the name of a program for which it contains examples.

eg find will provide examples for the find command.

eg --list will show all the commands for which eg has examples.

The complete usage statement, as shown by eg --help, is:

How it Works

Files full of examples live in examples/. A naming convention is followed such that the file is the name of the tool with .md. E.g. the examples for find are in find.md.

eg find will pipe the contents of find.md through less (although it tries to respect the PAGER environment variable).

Configuration and Extension

eg works out of the box, no configuration required.

If you want to get fancy, however, eg can be fancy.

For example, maybe a team member always sends you bzipped tarballs and you can never remember the flag for bzipping--why can't that guy just use gzip like everybody else? You can create an example for untarring and unzipping bzipped tarballs, stick it in a file called tar.md, and tell eg where to find it.

The way to think about what eg does is that it takes a program name, for example find, and looks for files named find.md in the default and custom directories (including subdirectories). If it finds them, it pipes them through less, with the custom files at the top. Easy.

The default and custom directories can be specified at the command line like so:

Instead of doing this every time, you can define a configuration file. It must begin with a section called eg-config and can contain two keys: custom-dir and examples-dir. Here is an example of a valid config file:

[eg-config] examples-dir = ~/examples-dir custom-dir = ~/my/fancy/custom/dir