gitstatus - Front-end for gitstatusd

The main idea of this package is to provide a fast and asynchronous Git status information that may be used as an UI element, say, in eshell prompt or in mode line.

The following example provides a full flow view with a gitstatus information added to the highly customized eshell prompt when it is ready, e.g. after the main parts of the prompt are drawn. This info starts with the word on on the first line of each prompt and ends just before the clock icon:

Or, with default eshell prompt:

Otherwise, you may use gitstatus-build-str to get a status string and use it elsewhere. In addition, the API provides enough separation to override the default processing of the data.

Note, the package wraps an external executable gitstatusd. The executable is distributed under GNU General Public License v3.0 and provides a much faster alternative to git status and git describe. It works on Linux, macOS, FreeBSD, Android, WSL, Cygwin and MSYS2. The original work includes scripts to be used in Bash and Zsh shells’ prompts. The executable has to be installed on the end-user machine for the package to work.

The package may be installed from Melpa.

Rest of the document presents a public API and customization options.

Minimal configuration

;; Customize path to `gitstatusd' executable
(with-eval-after-load 'gitstatusd
  (customize-set-variable 'gitstatusd-exe "~/.cache/gitstatus/gitstatusd-linux-x86_64"))
;; All the essential functions are autoloaded.
;; For `eshell': Add hook to connect between its prompt and `gitstatusd'.
(add-hook 'eshell-before-prompt-hook #'gitstatus-eshell-start)

gitstatusd.el

Main wrapper for the gitstatusd external executable. Opens asynchronous process and communicates with it.

Public API

Uses cl-defstruct called gitstatusd.

• gitstatusd-get-status (path callback) Make asynchronous request to gitstatusd for PATH with CALLBACK.
• gitstatusd-kill Kill gitstatusd process and clear callbacks.
• gitstatusd-remove-callback (req-id) Remove callback with REQ-ID.
• gitstatusd-calc-threads-num Calculate number of threads to use for gitstatusd.

Customization

Most of the values are as suggested for the external app. Please refer to the official guideline.

• gitstatusd-exe - executable path of the external application. Default: gitstatusd
• gitstatusd-threads-num - integer or function representing the number of threads to use for the exe. Default: #'gitstatusd-calc-threads-num. For Emacs 28 on all operating systems and Emacs 25-27 on Windows, BSD, Mac and Linux it returns 2 * (number of cores).
• gitstatusd-cmd-args - cmd args of the exe. Default: -s -1 -u -1 -d -1 -c -1 -m -1 -v FATAL.
• gitstatusd-is-compute-by-index - use Git index to perform computation. Default: t.

gitstatus.el

Common front-end. Parses the raw status data, processes it and wraps with fonts, icons, etc.

Public API

• gitstatus-build-str (res) Build gitstatus string from RES.

Customization

Please refer to the source, as there are too many custom options to change icons, faces, etc.

gitstatus-eshell.el

The module adds Git status information to the eshell prompt.

Public API

• gitstatus-eshell-start Run gitstatusd to extract the info.
• gitstatus-eshell-build (res) Build eshell prompt based on gitstatusd result, represented by RES.

Customization

• gitstatus-eshell-neighbour-regex - Neighbour of the gitstatus in eshell prompt. Default: \\( [$#]\\)
• gitstatus-eshell-is-neighbour-append - Append the status to the neighbour. Default: nil.
• gitstatus-eshell-prompt-lines - How many lines of the prompt are to be searched for the neighbour. Default: 1.