git-state(1) - a customizable view for the state of a working tree

git-state(1)
git-state(1)

NAME

git-state - a customizable view for the state of a working tree

SYNOPSIS

git state [view] [--show-status] [--no-show-status]
                 [--show-*] [--no-show-*]
                 [--no-show-all] [--no-show [extension ...]]
                 [(-e|--show-empty)] [(-E|--no-show-empty)]
                 [(-c|--color) [when]] [(-C|--no-color)]
                 [(-p|--pretty)] [(-f|--format) format]
                 [--clear] [--no-clear] [--no-page]
                 [(-o|--order) section [section ...]]
                 [(-O|--options) option [option ...]]
git state create (-c|--command) command [(-n|--name) name]
                 [(-o|--options) options] [--no-show] [--no-color]
                 extension
git state edit [(-c|--command) command] [(-n|--name) name]
               [(-o|--options) options] [--no-show] [--no-color]
               extension
git state delete extension
git state config extension
git state list
git state run extension
git state (-h|--help)
git state (-v|--version)

DESCRIPTION

Used to see a more concise and comprehensive view of the working directory through custom extensions.

OPTIONS

view

View the current state of a repository.

-h|--help

Print a simple help message.

-v|--version

Print version.

--show-status

Print the status section.

--no-show-status

Don't print the status section.

--show-*

Show extension *. Where * is the configuration key value. For instance, given:

git-state.extentions.last-ten-commits=git log --oneline -10
git-state.extentions.last-ten-commits.name=last ten commits

The show flag is --show-last-ten-commits.

--no-show-*

Hide extension *.

--no-show-all

Hide all extensions.

--no-show [extension ...]

A list of extensions to hide. If none are specified, all of them will be hidden. See EXTENSIONS section for more detail.

-e|--show-empty

Show empty sections rather than omitting them.

-E|--no-show-empty

Omit empty sections. This only applies to the status section when no clean message is used.

-c|--color [when]

Color output. when must be one of always, never, or auto. Defaults to color.ui configuration value or auto.

-C|--no-color

Never color output. Same as --color=never.

-p|--pretty

Display in pretty format. This is equivalent to -f|--format pretty.

-f|--format format

The format used to print each section. Valid values include: compact and pretty.

--clear

Clear the screen before printing.

--no-clear

Do not clear the screen before printing.

--no-page

Do not page output if it exceeds the terminal window.

-o|--order section [section ...]

A custom section order.

-O|--options option [option ...]

A list of options to pass to an extension. Options are formatted as <extension_name>:<option>. See EXTENSIONS section for more detail.

create

Create an extension.

extension: Name of the extension. Must be a valid git-config sub-section name.
-c|--command command: The command to execute.
-n|--name name: The section name to use when printing the extension alongside others.
-o|--options options: Any other options to include when running the extension command.
--no-show: Set the extension to not show by default. --show-* will override this setting at execution time.
--no-color: Do no include coloring option --color=<when> when executing the command.

edit

Edit an extension.

extension: Name of the extension. Must be a valid git-config sub-section name.
-c|--command command: The command to execute.
-n|--name name: The section name to use when printing the extension alongside others.
-o|--options options: Any other options to include when running the extension command.
--no-show: Set the extension to not show by default. --show-* will override this setting at execution time.
--no-color: Do no include coloring option --color=<when> when executing the command.

delete

Delete an extension.

extension: The name of an extension.

config

View the configuration of an extension.

extension: The name of an extension.

list

List the names of all extensions. This command has no options.

run

Run an extension. This command overrides any option that would otherwise hide the extension.

extension: The name of an extension.

CONFIGURATION

git-state.status.show-clean-message bool

True or false flag determining whether a message should be printed when the working directory is clean. Similar to git status.

Default: true

git-state.format string

The default formatting for git-state. Valid options include: pretty and compact. If no value is specified or an invalid value is entered, compact is used. The options -f|--format format or -p|--pretty will override this setting.

Default: compact

git-state.show-empty bool

True or false flag determining whether empty sections should be shown. Options (-e|--show-empty) and (-E|--no-show-empty) override this value.

Default: false

git-state.clear bool

True or false flag determining whether to clear the screen before printing. Options --clear and --no-clear override this value.

Default: true

color.ui string

Determines whether or not colors are printed in the output. Options --color [when] and --no-color override this value.

Default: auto

git-state.extensions.*.command string

A custom command to execute and print as its own section. See EXTENSIONS section for more detail.

git-state.extensions.*.name string

A custom name for an extension. If not specified, the extension key is used. See EXTENSIONS section for more detail.

git-state.extensions.*.options string

Options to pass to the extension. These are merged with any command line options for the extension. See EXTENSIONS section for more detail.

git-state.extensions.*.show bool

True or false flag determining whether to show the extension. Options --show-* and --no-show-* override this value. See EXTENSIONS section for more detail.

Default: true

git-state.extensions.*.color bool

Whether the extension should be called with --color=<when>.

Default: true

git-state.order string

Custom order in which to print sections. Multiple section names are separated by a pipe (|) character. Any remaining sections not included are printed in the order they are handled internally. Option -o|--order overrides this value.

EXTENSIONS

Out of the box, git-state isn't that useful. It simply reformats git status --short. That's where extensions come in. Extensions allow you to configure git-state to show the information useful to you. One can be created by running the extension create command:

git state extension create log --command 'git log --oneline -10'

The extension can be any valid script or command.

$ git alias graph "git log --oneline --graph --all --decorate -10"
$ git state extensions create graph --command "git graph"
$ git state
# status (state-extensions)

     M bin/commands/state.py
     M man/man1/git-state.ronn

# graph

    *   b27b2e5 (master) Merge branch 'fix-blank-lines'
    |\
    | * c40b5cf Fix upstream printing blank line
    | * 918d4f7 Fix settings printing blank line
    |/
    *   89736f9 Merge branch 'fix-documentation'
    |\
    | * 0e7cc6e Add see also section
    | * 059ff8b Fix settings documentation formatting
    | * 4d66f32 Fix changes documentation
    |/
    | * 48ab35e (HEAD, state-extensions) Fix status title
    | * bc45540 Refactor how arguments are passed into subcommands
    | * a0ea096 Refactor parameters

$

Extension settings are stored in config files like all other git configurations. They can be edited manually but it is highly discouraged unless you are create global extensions. This is due to a limitation of the extensions command that only modifies local configuration files. However, git-state will inspect non-local files.

Coloring

By default, an extension must accept the flag --color=when. This flag must be respected so coloring options are matched. when will only be one of: never or always. If an extension never colors, include --no-color when creating the extension.

Naming

The section name for an extension defaults to the key name but can be overridden by including --name <name>.

Option Passing

Options can be passed to an extension using the -O|--option flag and are applied in the order they are received. Values passed this way must be formatted as <extension_name>:<option>. The extension_name refers to the value used in configuration defining the extension. Not the display name.

For instance, say an extension were defined to show changes: git state extensions create changes --command 'git changes'. It could be toggled to run in stat mode and against develop by using --options changes:develop changes:--stat.

Options can be handled per configuration by setting --options <options>.

Hide an Extension

An extension can be hidden by setting --no-show. This is useful for globally defined extensions that aren't needed for all repositories.

Alternatively, an extension can be hidden by listing it in --no-show [extension ...] or using the flag --no-show-*.

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

CONFIGURATION

EXTENSIONS

Coloring

Naming

Option Passing

Hide an Extension

SEE ALSO