326 lines
11 KiB
Markdown
326 lines
11 KiB
Markdown
# git-graph manual
|
|
|
|
**Content**
|
|
|
|
* [Overview](#overview)
|
|
* [Options](#options)
|
|
* [Formatting](#formatting)
|
|
* [Custom branching models](#custom-branching-models)
|
|
|
|
## Overview
|
|
|
|
The most basic usage is to simply call git-graph from inside a Git repository:
|
|
|
|
```
|
|
git-graph
|
|
```
|
|
|
|
This works also deeper down the directory tree, so no need to be in the repository's root folder.
|
|
|
|
Alternatively, the path to the repository to visualize can be specified with option `--path`:
|
|
|
|
```
|
|
git-graph --path "path/to/repo"
|
|
```
|
|
|
|
**Branching models**
|
|
|
|
The above call assumes the GitFlow branching model (the default). Different branching models can be used with the option `--model` or `-m`:
|
|
|
|
```
|
|
git-graph --model simple
|
|
```
|
|
|
|
To *permanently* set the branching model for a repository, use subcommand `model`, like
|
|
|
|
```
|
|
git-graph model simple
|
|
```
|
|
|
|
Use the subcommand without argument to view the currently set branching model of a repository:
|
|
|
|
```
|
|
git-graph model
|
|
```
|
|
|
|
To view all available branching models, use option `--list` or `-l` of the subcommand:
|
|
|
|
```
|
|
git-graph model --list
|
|
```
|
|
|
|
For **defining your own models**, see section [Custom branching models](#custom-branching-models).
|
|
|
|
**Styles**
|
|
|
|
Git-graph supports different styles. Besides the default `normal` (alias `thin`), supported styles are `round`, `bold`, `double` and `ascii`. Use a style with option `--style` or `-s`:
|
|
|
|
```
|
|
git-graph --style round
|
|
```
|
|
|
|
|
|
|
|
Style `ascii` can be used for devices and media that do not support Unicode/UTF-8 characters.
|
|
|
|
**Formatting**
|
|
|
|
Git-graph supports predefined as well as custom commit formatting through option `--format`. Available presets follow Git: `oneline` (the default), `short`, `medium` and `full`. For details and custom formatting, see section [Formatting](#formatting).
|
|
|
|
For a complete list of all available options, see the next section [Options](#options).
|
|
|
|
## Options
|
|
|
|
All options are explained in the CLI help. View it with `git-graph -h`:
|
|
|
|
```
|
|
Structured Git graphs for your branching model.
|
|
https://github.com/mlange-42/git-graph
|
|
|
|
EXAMPES:
|
|
git-graph -> Show graph
|
|
git-graph --style round -> Show graph in a different style
|
|
git-graph --model <model> -> Show graph using a certain <model>
|
|
git-graph model --list -> List available branching models
|
|
git-graph model -> Show repo's current branching models
|
|
git-graph model <model> -> Permanently set model <model> for this repo
|
|
|
|
USAGE:
|
|
git-graph [FLAGS] [OPTIONS] [SUBCOMMAND]
|
|
|
|
FLAGS:
|
|
-d, --debug Additional debug output and graphics.
|
|
-h, --help Prints help information
|
|
-l, --local Show only local branches, no remotes.
|
|
--no-color Print without colors. Missing color support should be detected
|
|
automatically (e.g. when piping to a file).
|
|
Overrides option '--color'
|
|
--no-pager Use no pager (print everything at once without prompt).
|
|
-S, --sparse Print a less compact graph: merge lines point to target lines
|
|
rather than merge commits.
|
|
--svg Render graph as SVG instead of text-based.
|
|
-V, --version Prints version information
|
|
|
|
OPTIONS:
|
|
--color <color> Specify when colors should be used. One of [auto|always|never].
|
|
Default: auto.
|
|
-f, --format <format> Commit format. One of [oneline|short|medium|full|"<string>"].
|
|
(First character can be used as abbreviation, e.g. '-f m')
|
|
Default: oneline.
|
|
For placeholders supported in "<string>", consult 'git-graph --help'
|
|
-n, --max-count <n> Maximum number of commits
|
|
-m, --model <model> Branching model. Available presets are [simple|git-flow|none].
|
|
Default: git-flow.
|
|
Permanently set the model for a repository with
|
|
> git-graph model <model>
|
|
-p, --path <path> Open repository from this path or above. Default '.'
|
|
-s, --style <style> Output style. One of [normal/thin|round|bold|double|ascii].
|
|
(First character can be used as abbreviation, e.g. '-s r')
|
|
-w, --wrap <wrap> Line wrapping for formatted commit text. Default: 'auto 0 8'
|
|
Argument format: [<width>|auto|none[ <indent1>[ <indent2>]]]
|
|
For examples, consult 'git-graph --help'
|
|
|
|
SUBCOMMANDS:
|
|
help Prints this message or the help of the given subcommand(s)
|
|
model Prints or permanently sets the branching model for a repository.
|
|
```
|
|
|
|
For longer explanations, use `git-graph --help`.
|
|
|
|
## Formatting
|
|
|
|
Formatting can be specified with the `--format` option.
|
|
|
|
Predefined formats are `oneline` (the default), `short`, `medium` and `full`. They should behave like the Git formatting presets described in the [Git documentation](https://git-scm.com/docs/pretty-formats).
|
|
|
|
**oneline**
|
|
|
|
```
|
|
<hash> [<refs>] <title line>
|
|
```
|
|
|
|
**short**
|
|
|
|
```
|
|
commit <hash> [<refs>]
|
|
Author: <author>
|
|
|
|
<title line>
|
|
```
|
|
|
|
**medium**
|
|
|
|
```
|
|
commit <hash> [<refs>]
|
|
Author: <author>
|
|
Date: <author date>
|
|
|
|
<title line>
|
|
|
|
<full commit message>
|
|
```
|
|
|
|
**full**
|
|
|
|
```
|
|
commit <hash> [<refs>]
|
|
Author: <author>
|
|
Commit: <committer>
|
|
Date: <author date>
|
|
|
|
<title line>
|
|
|
|
<full commit message>
|
|
```
|
|
|
|
### Custom formatting
|
|
|
|
Formatting strings use a subset of the placeholders available in `git log --format="..."`:
|
|
|
|
| Placeholder | Replaced with |
|
|
| ----------- | ------------------------------------------- |
|
|
| %n | newline |
|
|
| %H | commit hash |
|
|
| %h | abbreviated commit hash |
|
|
| %P | parent commit hashes |
|
|
| %p | abbreviated parent commit hashes |
|
|
| %d | refs (branches, tags) |
|
|
| %s | commit summary |
|
|
| %b | commit message body |
|
|
| %B | raw body (subject and body) |
|
|
| %an | author name |
|
|
| %ae | author email |
|
|
| %ad | author date |
|
|
| %as | author date in short format `YYYY-MM-DD` |
|
|
| %cn | committer name |
|
|
| %ce | committer email |
|
|
| %cd | committer date |
|
|
| %cs | committer date in short format `YYYY-MM-DD` |
|
|
|
|
If you add a '+' (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string.
|
|
|
|
If you add a '-' (minus sign) after % of a placeholder, all consecutive line-feeds immediately preceding the expansion are deleted if and only if the placeholder expands to an empty string.
|
|
|
|
If you add a ' ' (space) after % of a placeholder, a space is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string.
|
|
|
|
See also the [Git documentation](https://git-scm.com/docs/pretty-formats).
|
|
|
|
More formatting placeholders are planned for later releases.
|
|
|
|
**Examples**
|
|
|
|
Format recreating `oneline`:
|
|
|
|
```
|
|
git-graph --format "%h%d %s"
|
|
```
|
|
|
|
Format similar to `short`:
|
|
|
|
```
|
|
git-graph --format "commit %H%nAuthor: %an %ae%n%n %s%n"
|
|
```
|
|
|
|
## Custom branching models
|
|
|
|
Branching models are configured using the files in `APP_DATA/git-graph/models`.
|
|
|
|
* Windows: `C:\Users\<user>\AppData\Roaming\git-graph`
|
|
* Linux: `~/.config/git-graph`
|
|
* OSX: `~/Library/Application Support/git-graph`
|
|
|
|
File names of any `.toml` files in the `models` directory can be used in parameter `--model`, or via sub-command `model`. E.g., to use a branching model defined in `my-model.toml`, use:
|
|
|
|
```
|
|
git-graph --model my-model
|
|
```
|
|
|
|
**Branching model files** are in [TOML](https://toml.io/en/) format and have several sections, relying on Regular Expressions to categorize branches. The listing below shows the `git-flow` model (slightly abbreviated) with explanatory comments.
|
|
|
|
```toml
|
|
# RegEx patterns for branch groups by persistence, from most persistent
|
|
# to most short-leved branches. This is used to back-trace branches.
|
|
# Branches not matching any pattern are assumed least persistent.
|
|
persistence = [
|
|
'^(master|main)$', # Matches exactly `master` or `main`
|
|
'^(develop|dev)$',
|
|
'^feature.*$', # Matches everything starting with `feature`
|
|
'^release.*$',
|
|
'^hotfix.*$',
|
|
'^bugfix.*$',
|
|
]
|
|
|
|
# RegEx patterns for visual ordering of branches, from left to right.
|
|
# Here, `master` or `main` are shown left-most, followed by branches
|
|
# starting with `hotfix` or `release`, followed by `develop` or `dev`.
|
|
# Branches not matching any pattern (e.g. starting with `feature`)
|
|
# are displayed further to the right.
|
|
order = [
|
|
'^(master|main)$', # Matches exactly `master` or `main`
|
|
'^(hotfix|release).*$', # Matches everything starting with `hotfix` or `release`
|
|
'^(develop|dev)$', # Matches exactly `develop` or `dev`
|
|
]
|
|
|
|
# Colors of branches in terminal output.
|
|
# For supported colors, see section Colors (below this listing).
|
|
[terminal_colors]
|
|
# Each entry is composed of a RegEx pattern and a list of colors that
|
|
# will be used alternating (see e.g. `feature...`).
|
|
matches = [
|
|
[
|
|
'^(master|main)$',
|
|
['bright_blue'],
|
|
],
|
|
[
|
|
'^(develop|dev)$',
|
|
['bright_yellow'],
|
|
],
|
|
[ # Branches obviously merged in from forks are prefixed with 'fork/'.
|
|
# The 'fork/' prefix is only available in order and colors, but not in persistence!
|
|
'^(feature|fork/).*$',
|
|
['bright_magenta', 'bright_cyan'], # Multiple colors for alternating use
|
|
],
|
|
[
|
|
'^release.*$',
|
|
['bright_green'],
|
|
],
|
|
[
|
|
'^(bugfix|hotfix).*$',
|
|
['bright_red'],
|
|
],
|
|
[
|
|
'^tags/.*$',
|
|
['bright_green'],
|
|
],
|
|
]
|
|
# A list of colors that are used (alternating) for all branches
|
|
# not matching any of the above pattern.
|
|
unknown = ['white']
|
|
|
|
# Colors of branches in SVG output.
|
|
# Same structure as terminal_colors.
|
|
# For supported colors, see section Colors (below this listing).
|
|
[svg_colors]
|
|
matches = [
|
|
[
|
|
'^(master|main)$',
|
|
['blue'],
|
|
],
|
|
[
|
|
'...',
|
|
]
|
|
]
|
|
unknown = ['gray']
|
|
```
|
|
|
|
**Tags**
|
|
|
|
Internally, all tags start with `tag/`. To match Git tags, use RegEx patterns like `^tags/.*$`. However, only tags that are not on any branch are ordered and colored separately.
|
|
|
|
**Colors**
|
|
|
|
**Terminal colors** support the 8 system color names `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and `white`, as well as each of them prefixed with `bright_` (e.g. `bright_blue`).
|
|
|
|
Further, indices of the 256-color palette are supported. For a full list, see [here](https://jonasjacek.github.io/colors/). Indices must be quoted as strings (e.g. `'16'`)
|
|
|
|
**SVG colors** support all named web colors (full list [here](https://htmlcolorcodes.com/color-names/)), as well as RGB colors in hex notation, like `#ffffff`.
|