INSTALL

gitsh installation
==================

The ideal way to install gitsh is via your operating system's package manager.
Currently gitsh packages are available for:

* macOS (via Homebrew)
* Arch Linux
* OpenBSD (-current)

On other operating systems you should install using the tarball, following the
instructions in this guide.


Prerequisites
-------------

* Ruby version 2.3.0 or later
* gcc or a similar C compiler
* GNU Readline


gitsh and Ruby version managers
-------------------------------

The gitsh configuration script will attempt to find a system wide version of
Ruby 2.3.0 or later. Rubies installed by Ruby version managers will usually be
ignored to avoid problems when those binaries are moved or deleted.

To force gitsh to use a specific Ruby binary, set the $RUBY environment variable
when running the configuration script. For example, this will use the first ruby
binary on the $PATH:

        RUBY=$(which ruby) ./configure


GNU Readline
------------

gitsh provides a Ruby C extension that integrates with GNU Readline. Ruby ships
with its own Readline module, but it doesn't offer all of the features required
for comprehensive tab-completion.

Other line editor libraries, like libedit, are partly compatible with GNU
Readline, but don't offer enough features to be supported by gitsh.

The configure script may fail if GNU Readline isn't found. You can set the
$CPPFLAGS and $LDFLAGS environment variables to provides paths for the compiler
and linker to use. For example, with GNU Readline install under /usr/local/opt,
you might use:

        CPPFLAGS="-I/usr/local/opt/readline/include" \
          LDFLAGS="-L/usr/local/opt/readline/lib" \
          ./configure

If your system uses a different name for Readline, you can set the
$READLINE_LIB environment variable. For example, on OpenBSD where the Readline
library is named ereadline, you might use:

        READLINE_LIB="ereadline" \
          CPPFLAGS="-I/usr/local/include/ereadline" \
          LDFLAGS="-L/usr/local/lib" \
          ./configure

Finally, on macOS systems with a universal Ruby binary (e.g. /usr/bin/ruby),
and a non-universal Readline shared library, you may need to explicitly pass
an architecture to use via the $READLINE_ARCH environment variable:

        READLINE_ARCH=x86_64 \
          RUBY=/usr/bin/ruby \
          ./configure


Installation
------------

1. Download and extract the latest release:

        curl -OL https://github.com/thoughtbot/gitsh/releases/download/v0.14/gitsh-0.14.tar.gz
        tar -zxvf gitsh-0.14.tar.gz
        cd gitsh-0.14

2. Configure the distribution. This step will determine which version of Ruby
   should be used, which has important implications; see the notes on "gitsh and
   Ruby version managers" above.

        ./configure

3. Build and install gitsh:

        make
        sudo make install