Browse files

added some comments, added extending-completion example

cleaned up the wrapping sanity-check
  • Loading branch information...
1 parent 5930093 commit 254af1bfeefebfdda3db5380c7af84ff7dd24ca6 @pdkl95 committed Jan 27, 2012
Showing with 649 additions and 440 deletions.
  1. +75 −6 README.markdown
  2. +574 −434 rubygems-completion.bash
@@ -1,28 +1,79 @@
-Bash completion support for [rubygems]( (based on gem 1.8.10)
+Bash completion support for
+I have useed these versions of rubygems a lot
+during development of this script and in my general
+ruby use:
+* 1.8.10
+* 1.8.11
+* 1.8.15
+Other versions shold work fine regardless unless the
+interface to `gem` suddenly changed. It's probably worth
+trying on any version that's even remotely "recent-ish".
Put rubygems-completion.bash in one of the following locations:
- * /etc/bash_completion.d
- * /usr/local/etc/bash_completion.d
- * ~/.bash_completion.d
+* /etc/bash_completion.d
+* /usr/local/etc/bash_completion.d
+* ~/.bash_completion.d
or otherwise make sure it is sourced into your shell.
+Extending Completion
+You can apply completion to your own function
+or alias with `_gemcomp`. I recommend using this
+if possible, instead of calling `complete` directly,
+for future compatability.
+### Aliasing the `gem` top-level command ###
+The function `_gem` handles completion for the
+top-level `gem` command itself. For example:
+alias rg="command /some/obscure/path/to/gem"
+_gemcomp _gem rg
+### Aliasing individual gem-commands ###
+If you want to alias a specific gem command, hook
+directly to the command's completion function
+instead of going through `_gem`. The command functions
+are named by the command name itself prefixed with `_gem_`
+(e.g. `_gem_foo` for the `gem foo` command).
+alias gi="command gem install --verbose"
+_gemcomp _gem_install gi
Hard-Coded Options
Initially, I dynamically pulled some of the completion
lists out of gem itself, but that turned out to be VERY
slow in practice. An extra second or two on each execution
-of .bashrc is just too much delay.
+of `.bashrc` is just too much delay.
It might be practical to have several versions of the options,
and select them by a simple version user-setting, but... that's not
@@ -33,10 +84,28 @@ I'm open to suggestions, though, if anybody has an idea on how
to do this efficiently.
+Future Plans
+I'm currently experimenting with a compromise on the above
+dynamic-vs-speed issue: precompiling the what I parse out of
+the gem command into to bash arrays. It would require triggering
+a "recompile" task when rubygems is updated, but I suspect that's
+not too big of an issue.
+I will never change the default of this script away form
+the the "inoffensive and fast" default that it has right now,
+but an optional dynamic-update feature could be useful.
+At a minimum, I need to find the various `rubygems_plugin.rb` in
+gems so the top-level command list can be completed correctly,
+even when gem itself has been extended.
The Fine Print
-Copyright (c) 2011 [Brent Sanders]( <>
+Copyright (c) 2011,2012 [Brent Sanders]( <>
Derived losely from []( in the
Oops, something went wrong.

0 comments on commit 254af1b

Please sign in to comment.