GITSH(1)

NAME
gitsh - Interactive shell for the git version control system

SYNOPSIS
gitsh [--version] [-h] [--git CMD] [file]

DESCRIPTION
gitsh is a language for interacting with a git(1) repository. It supports all git subcommands, custom aliases, and custom commands for interacting with the shell itself.

Running gitsh with no arguments will start an interactive session. Quit by either typing :exit or:q or sending an EOF character.

Passing the path to a file containing a series of commands or sending a series of commands to gitsh's standard input will run each of those commands in sequence.

In interactive mode, commands and their arguments can be completed using tab completion. The rules for what can be completed are defined in configuration files; see gitsh_completions(5) for details.

It supports these options and arguments:

--git CMD
    use the git command specified in CMD, instead of the default ( /usr/bin/env git or as specified by the gitsh.gitCommand configuration option ).

-h, --help
    display a help message and exit.

--version
    display the version number and exit.

file
    the path to a file of commands to be executed. If the path is - then the commands will be read from the standard input.

Within the shell you can use the following types of commands:

command [arguments]
    execute a Git command or alias with the given arguments, e.g. status will execute git-status(1).

!command [arguments]
    execute a shell command with the given arguments, e.g. !ls will execute ls(1).

:command [arguments]
    execute a built-in gitsh command. See the section on BUILT-IN COMMANDS for a list of supported commands.

#comment
    any input after a # character will be treated as comments and ignored.

Commands can be combined using the following operators, which have similar semantics to sh(1):

left && right
    only execute right if left succeeds.

left || right
    only execute right if left fails.

left ; right
    execute left, and then right.

As in sh(1), and many other general-purpose languages, && has greater precedence than ||. That precedence can be overridden by surrounding a clause with parentheses. For example, the following two commands are not equivalent:

    @ :echo $first || :echo $second && :echo $third
    @ (:echo $first || :echo $second) && :echo $third

PROMPT
The prompt changes based on the status of the repository. By default it consist of three parts: the basename of the current working directory, the current HEAD and the terminator sigil.

The current HEAD is a branch name, tag name, abbreviated SHA, or the text uninitialized when the present working directory is not a git repository. It is limited to 15 characters.

The state of the repository is reflected by the terminating sigil and the color of both the current HEAD and the sigil:
Status | Sigil | Color setting | Default
Not a git repo | !! | gitsh.color.uninitialized | normal red
Untracked files |! | gitsh.color.untracked | red
Modified files | & | gitsh.color.modified | yellow
Default | @ | gitsh.color.default | blue

  Prompt customisation
The prompt can be customised by setting the gitsh.prompt variable using the git-config(1) command. The following placeholders can be used in the custom prompt:
Placeholder | Meaning
%# | terminating sigil (see previous table)
%b | current HEAD (full branch name, tag name, etc.)
%B | current HEAD, limited to 15 characters
%d | absolute path to current working directory
%D | basename of the current working directory
%g | absolute path of git binary in use
%G | basename of git binary in use
%c | start coloring based on status (see previous table)
%w | return to default color (e.g. after using %c)

For example, setting gitsh.prompt to (%b)%d%# would produce prompts like (master)/home/me/repo@ and (uninitialized)/home/me!!

BUILT-IN COMMANDS
Built-in commands are used to give instructions to the shell. To distinguish them from git commands, and to avoid collisions with git aliases and extensions, they are prefixed with a: character.

The following commands are supported:

:set variable value
    sets a variable in the gitsh environment to the given value.

        @ :set george "George <george@thoughtbot.com>"
        @ commit --author $george

    Variable names containing a dot can be used to temporarily override git-config(1) variables for the duration of a gitsh session.

        @ :set user.name George
        @ :set user.email george@thoughtbot.com
        @ commit

    See the section on VARIABLES for more information.

:echo string ...
    prints the given strings to standard output, followed by a newline. All whitespace is collapsed into one space. This can be useful for viewing the value of a variable:

        @ :echo $user.name

    Or for a mix of variables and arbitrary strings:

        @ :echo "This is ${user.name}'s work"

:cd [path]
    changes directory to the given path. Without an argument it changes directory to the repository's root.

:help [command]
    displays help about the given built-in command. Without an argument it outputs a list of all built-in commands. When given the name of a command, it outputs a usage message and brief description of that command.

:source path
    runs the commands in the given file. Variables :set in the sourced file will remain set after the :source command has finished, making it similar to the source built-in command in sh(1) and other Unix shells.

        @ :source /home/george/.gitshrc

:exit
    ends the gitsh session.

:q  alias for :exit.

VARIABLES
Variables can be read using the $ prefix. There are three kinds of variables supported by gitsh:

1.  Variables set using the :set command.

        @ :set greeting "Hello, world"
        @ :echo $greeting

2.  All git-config(1) settings can be treated as variables in gitsh. For example, the following commands will produce the same output.

        @ config user.name
        @ :echo $user.name

3.  There are a number of "magic variables" which expose information about the current state of the repository.

    $_prior
        The name of the previous branch that was checked out. This is usually equivalent to @{-1}, but will also work in situations where the branch name is required.

    $_merge_base
        When there is a merge in progress, this will be the hash of the merge's base commit. It is equivalent to the output of merge-base HEAD MERGE_HEAD.

    $_rebase_base
        When there is a rebase in progress, this will be the hash of the commit onto which we are rebasing, for example after running rebase master this variable would evaluate to the hash of the commit at the head of the master branch.

    $_root
        The absolute path to the current repository's root directory. This is equivalent to the output of git-rev-parse --show-toplevel.

Attempting to use an unset variable will cause a command to fail. This is different to sh(1), which will ignore unset variable arguments.

Magic variables will behave like unset variables when used in a context where they don't make sense, e.g. using $_root outside of a Git repository.

SUB-SHELLS

Sub-shells can be used to pass the output of any command--including Git commands, internal commands, and shell commands--as an argument to another command. A sub-shell is surrounded by $(...). For example:

    @ :set directory $(!pwd)

COMMAND ARGUMENTS

When arguments are passed to Git commands, internal commands, or shell commands, gitsh will recognise and interpret various methods of quoting characters. These are similar to those supported by sh(1), and other general-purpose shells.

In general, a character which would otherwise have some special meaning may be included as a literal character in an argument if it is prefixed with a \ character.

In an unquoted argument, the string delimiters ('"), the variable or sub-shell prefix ($), parentheses (()), and any character which would indicated the end of the argument (spaces, &|;#) can be escaped.

In a double-quoted argument, only the string delimiter ("), and the variable or sub-shell prefix ($) can be escaped.

In a single-quoted argument, very few characters have special meaning, and so only the string delimiter (') can be escaped.

Line-breaks can be escaped by ending a line with a \ character. This is useful for splitting long commands over multiple lines.

A literal \ character can always be produced by repeating it (\\), but a single \ will also be interpreted as a literal as long as it isn't followed by a character that can be escaped in the current context.

CONFIGURATION
The following git-config(1) variables can be used to customise the behaviour of gitsh:

gitsh.historyFile
    The path to the gitsh history file. The default is ~/.gitsh_history

gitsh.historySize
    The number of lines of history to save in the gitsh history file. The default is 500.

gitsh.prompt
    The format of the prompt. See the PROMPT section above for details.

gitsh.noGreeting
    If this is set to true then no greeting message will be displayed when gitsh starts.

gitsh.defaultCommand
    The command that will be run when a user presses return without entering any command. By default this is status.

gitsh.gitCommand
    The command that gitsh will use to run git commands. The default is /usr/bin/env git.

gitsh.color.*
    Various settings are available to customize the colors used in the prompt. See the PROMPT section above for a list of settings, and git-config(1) for the values that color settings can take.

In addition, some standard git-config(1) variables modify the behaviour of gitsh:

help.autocorrect
    When this is set to anything other than 0, an extraneous git prefix to a command will be automatically removed. This will help users who are used to using git(1) through a general purpose shell.

FILES

$HOME/.gitshrc
    A user's personal configuration file. If this file exists, it will be loaded at the start of interactive sessions, as if it had been passed to the :source command.

    The .gitshrc file will not be loaded for non-interactive sessions, e.g. when gitsh is invoked with the path to a script file.

/etc/gitsh/completions
    System-wide tab completions file, which defines the tab completion options for popular Git commands.

    See gitsh_completions(5) for details on the format of this file.

$HOME/.gitsh_completions
    User-defined tab completions file, which can be used to add additional completion rules, for example to add tab completion support for custom commands and aliases.

    As with the system-wide completions file, this file uses the format described in gitsh_completions(5).

ENVIRONMENT

TERM
    The terminfo(1) name for the terminal. This is used to determine whether to show colors.

EXAMPLES

    init
    commit --allow-empty
    checkout -b new-feature
    rebase master
    :exit

SEE ALSO
gitsh_completions(5) git(1) gittutorial(7)

HISTORY
Written by George Brocklehurst <george@thoughtbot.com>, based on a prototype by Mike Burns <mburns@thoughtbot.com> from October 2013, inspired by a talk by Reda Lemeden <reda@thoughtbot.com>.

AUTHORS
thoughtbot <hello@thoughtbot.com>