brew-desc.rb - Searchable descriptions for Homebrew formulas

NOTICE

brew desc has switched to a new upgrade and installation method. In a nutshell, you no longer need to install brew desc in the old way (brew install brew-desc). Intead, all you need to do is tap this directory and the command is already installed. In addition, this means that upgrades will be delivered automatically whenever you run brew update. That is, updating brew itself will also update this command.

The easiest way to make sure that you're up to date is to run the following:

brew update && brew uninstall brew-desc && brew tap --repair

That should be it. However, if you have any problems, please file an issue.

What is it?

It's an external command for Homebrew. It provides short descriptions for Homebrew packages. You can also search for packages by description. So if you know you want to install a mail program, but you're not sure which one, brew-desc is for you.

Usage

Although the script's name is brew-desc.rb, Homebrew external commands work in such a way that you invoke it as brew desc. (It functions exactly like a sub-command built into Homebrew.)

If you already know the name of a package, and you want to see a bit about it, that's easy:

$ brew desc mutt
mutt: Mongrel of Mail User Agents (part Elm, Pine, Mush, mh, etc)

If you know the kind of thing you're interested in, but not the name of specific items, that's easy too:

$ brew desc -s key-value
redis: A persistent key-value database with built-in net interface
kumofs: A scalable and highly available distributed key-value store
cassandra: Highly scalable, eventually consistent, distributed key-value store

Both -s and --search are acceptable. Searches are always case insensitive, and the argument you pass to -s or --search is interpreted as a Ruby regular expression. So you can even do silly searches like this:

$ brew desc -s 'm\b'
abnfgen: Quickly generate random documents that match an ABFN grammar
aescrypt: Program for encryption/decryption
...<way too much output>

Installation

You can install brew desc in two ways.

1. Tap this repository.
2. Install manually.

For the first method, do the following:

brew tap telemachus/homebrew-desc

That's it! In addition to being easy, this method has an advantage over the manual method described below: once this repo has been tapped, you will automatically receive updates to brew desc whenever you run brew update. I highly recommend that you follow this method.

However, if you don't want to tap the repo, there is another option. Clone or download this repository, and then put the file brew-desc.rb anywhere in your $PATH. For example:

mv brew-desc.rb ~/bin

Leave the name as is if you follow this method. Homebrew knows how to find it.

The major downside to this installation method is that you get no upgrades, unless you handle them manually.

Once you've installed via either method, you can use the command as described above.

Contributors

I started this project with the descriptions from the MacPorts ports tree. I also used the Debian package descriptions. In both cases, I edited many items for consistency and length.

The following people have also contributed to the project:

• Ismail Badawi
• Xu Cheng
• coruus
• Sietse de Kaper
• Misty De Meo
• Baptiste Fontaine
• Magnus Holm
• Marek Hrusovsky
• Gregory Igelmund
• Jeroen
• Steve Mayer
• Max Nordlund
• David Powell
• Hamid Rohani
• Peter N. Steinmetz
• Christian Schwang
• Soulshaker
• Peter Souter
• Dominyk Tiller
• John Speno
• Mike Warren
• Nikolaus Wittenstein
• Yann-R
• Humza Yaqoob
• Zearin

Contributing

All formulas now have descriptions. However, many could probably be improved to be clearer or more precise. There are also probably typos and flat-out mistakes. If you want to help, please fork, edit one or more descriptions and send a pull request.

However, Homebrew constantly adds new packages. So at any given time I might be behind by a handful of new items. Please feel free to write those up as well.

If you are going to contribute to the descriptions in any way, here are my two most important rules for description contents:

• Be brief
• No advertising or boilerplate

Ideally all descriptions should fit into one average-size terminal window (including the name of the piece of software). That means that "name: description goes here" should never be longer than around 80 characters. Trim relentlessly!

Also please remove all advertising language or boilerplate. For example, nearly all command line tools claim to be small, simple and fast. (I learned this by editing thousands of descriptions for this project.) Please don't include any of this sort of thing. Often if you go to the project's one-line synopsis, this will be what you get. In that case, please read further to find a more specific description for the item.

Thanks.