gist, a git repository status pretty-printer

An expression based, ergonomic langauge for writing the status of your git repository into your shell prompt.

For example :"\<\b\(\+\-)>\[\M\A\R\D':'\m\a\u\d]\{\h('@')}':'" results in something that might look like <master(+1)>[M1:D3]{@5}: where

• master is the name of the current branch.
• +1: means we are 1 commit ahead of the remote branch
• M1: the number of staged modifications
• D3: is the number of unstaged deleted files
• @5: is the number of stashes

gist expressions also support inline format expressions to do things like making text red, or bold, or using ANSI terminal escape sequences, or setting RGB colors for your git information.

Grammar

gist expressions have four basic types of expressions:

1. Named expressions
2. Format expressions
3. Group expressions
4. Literals

Literals

Any characters between single quotes literal, except for backslashes and single quotes. Literals are left untouched. For example, 'literal' outputs literal.

Named expressions

Named expressions represent information about your git repository.

Name	Meaning	Example
\b	branch name or head commit id	master
\B	remote name	origin/master
\+	# of commits ahead remote	+1
\-	# of commits behind remote	-1
\m	# of unstaged modified files	M1
\a	# of untracked files	?1
\d	# of unstaged deleted files	D1
\u	# of merge conflits	U1
\M	# of staged modified files	M1
\A	# of added files	A1
\R	# of renamed files	R1
\D	# of staged deleted files	D1
\h	# of stashed files	H1

You can provide other expressions as arguments to expressions which replace the default prefix which appears before the result or file count. For example, \h('@') will output @3 instead of H3 if your repository has 3 stashed files. You can provide an arbitrary number of valid expressions as a prefix to another named expression.

Group Expressions

Gist will surround grouped expressions with parentheses or brackets, and will print nothing if the group is empty.

Macro	Result
\[]	empty
\()	empty
\<>	empty
\{}	empty
\{\b}	{master}
\<\+\->	<+1-1>
\[\M\A\R]	[M1A3] where \R is empty
\[\r\(\a)]	empty, when \r, \a are empty

Format Expressions

Gist expressions support ANSI terminal formatting through the following styles:

Format	Meaning
#~(...)	reset
#_(...)	underline
#i(...)	italic text
#*(...)	bold text
#r(...)	red text
#g(...)	green text
#b(...)	blue text
#m(...)	magenta/purple text
#y(...)	yellow text
#w(...)	white text
#k(...)	bright black text
#[01,02,03](...)	24 bit rgb text color
#R(...)	red background
#G(...)	green background
#B(...)	blue background
#M(...)	magenta/purple background
#Y(...)	yellow background
#W(...)	white background
#K(...)	bright black background
#{01,02,03}(...)	24 bit rgb background color
#01(...)	ANSI bold, support for any ANSI terminal code

Format styles can be combined in a single expression by separating them with semicolons:

Format	Meaning
#w;K(...)	white text, black background
#r;*(...)	red bold text
#1;42(...)	bold red text
#_;*(...)	underline bold text

Work at MangoHacks

Before mangohacks, I had no implementation for half of the named expressions which connect to the libgit2 api, and I had no format macros, and no implementation for them.

Specifically, my work at mangohacks included:

• Adding format macros to the abstract syntax tree
• De-duping the parser
• De-duping the interpreter
• Simplifying the recursive tree structure of the Abstract Syntax Tree
• Simplifying the grammar to make the language more ergonomic
• Adding an implementation for the format macros
  • Refactoring the interpreter
  • Coming up with a recursive divide-and-conquer strategy to implicitly flatten the AST to a list while keeping format information
  • Using an ANSI terminal library to automagically support (slightly) platform independent color

Built With

• rust
• shell