Adding upstream version 0.6.0.
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
parent
4de83856e9
commit
5b48f7aed6
GPG key ID:
FBB4F0E80A80222F
21 changed files with 5187 additions and 0 deletions
326
docs/manual.md
Normal file
326
docs/manual.md
Normal file
|
|
@ -0,0 +1,326 @@
|
|||
# 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`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue