Skip to content

Commit 4f5652b

Browse files
author
Heiko Alexander Weber
committed
#patch | restored README.md
1 parent 64e924b commit 4f5652b

1 file changed

Lines changed: 138 additions & 9 deletions

File tree

‎docs/README.md‎

Lines changed: 138 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,143 @@
1-
# How to use ADRs
1+
# complate
22

3-
This piece of documentation uses the tool `mdbook` in order to generate a servable website.
3+
[![crates.io](https://img.shields.io/crates/v/complate.svg)](https://crates.io/crates/complate)
4+
[![crates.io](https://img.shields.io/crates/d/complate?label=crates.io%20downloads)](https://crates.io/crates/complate)
5+
[![pipeline](https://github.com/replicadse/complate/workflows/pipeline/badge.svg)](https://github.com/replicadse/complate/actions?query=workflow%3Apipeline)
6+
[![docs.rs](https://img.shields.io/badge/docs.rs-latest-blue)](https://docs.rs/crate/complate/latest)
47

5-
## How to install
8+
## Introduction and use case
69

7-
1) Make sure that you have `cargo` installed
8-
2) Make sure that you have `clang` or any other fitting C compiler installed
9-
3) Install `mdbook` via `cargo`: \
10-
`cargo install mdbook`
10+
`complate` (a portmanteau of "commit" and "template") is a project that allows the user to generate strings in a guided way. The original use-case of this was the standardization of GIT commit messages.\
11+
Many projects and teams are standardizing their commit messages in a certain way. This is somewhat error prone and people just tend to mess things up. Spaces, spelling errors or linebreaks are common issues that lead to inconsistency. It can also have more effects than just consistency in the format. If you use [github-tag-action by anothrnick](https://github.com/anothrNick/github-tag-action) in GitHub Workflows (like this project does), the commit message can have direct influence on your version number that is generated on build.
1112

12-
## How to serve
13+
## Installation via `cargo`
14+
Find this project on [crates.io](https://crates.io/crates/complate).
15+
Install or update (update needs the `--force` flag) the software by executing:
16+
```
17+
cargo install complate --force
18+
```
1319

14-
1) Execute `mdbook serve` in `documentation/adrs`.
20+
## Idea
21+
22+
The idea for the concrete use case of standardizing GIT commit messages is to have a configuration file inside the repository which is read by the program. You are then able to select a template that you would like to use for your message. The configuration file declares the template (in handlebars syntax) as well as variables and how to replace them.
23+
24+
## Usage
25+
26+
In order to use `complate`, the recommended way is to place the program including the configuration files and templates into the repository itself. Consider the following structure:
27+
```
28+
Repository root
29+
├── .git
30+
├── .complate
31+
│ ├── complate
32+
│ ├── config.yml
33+
│ └── templates
34+
│ └── template-a.tpl
35+
├── src
36+
│ └── *
37+
└── docs
38+
└── *
39+
```
40+
41+
`complate` writes the generated message to the stdout pipe.\
42+
Expecting the recommended folder structure, you should be able to simply run `./.complate/complate print | git commit -F -` in order to create a new standardized commit.
43+
44+
## General overview
45+
46+
The template itself can be declared as string inside the configuration file or as a reference to a file that contains the template. The template string can contain variables in handlebars syntax ( `{{ variable}}` ). All distinct variables must have a representation in the according section that then also defines on how to find the value for this variable.
47+
48+
## Technical documentation
49+
50+
### Disclaimer
51+
52+
All features that are marked as `experimental` are _not_ considered a public API and therefore eplicitly not covered by the backwards-compatibility policy inside a major version (see [semver v2](https://semver.org)). Use these features on your own risk!
53+
54+
### Features
55+
56+
|Name|Description|Default|
57+
|-- |-- |-- |
58+
|backend+cli|The CLI backend which maps to the original dialoguer implementation.|Yes|
59+
|backend+ui|The UI backend which maps to the new cursive/fui implementation.|No|
60+
61+
#### `backend+`
62+
63+
Either one of the `backend+` flags (or both) MUST be enabled for `complate` to work (it won't compile otherwise).
64+
65+
### Application level arguments
66+
67+
|Name|Short|Long|Description|
68+
|-- |-- |-- |-- |
69+
|Experimental|-e|--experimental|Activates experimental features that are not stable yet. All features that are marked as experimental are not referenced when keeping backwards compatibility inside one major version.|
70+
71+
### Commands
72+
73+
|Command|Description|Status|
74+
|-- |-- |-- |
75+
|help|Prints the help to `STDOUT`.|stable|
76+
|init|Initializes the default configuration in `./.complate/config.yml`|stable|
77+
|print|Prompts for the template, prompts for variable values and prints the data to `STDOUT`|stable|
78+
79+
### `print` command flags
80+
|Name|Short|Long|Description|Status|
81+
|-- |-- |-- |-- |-- |
82+
|Config file path|-c|--config|The path to the configuration file that shall be used. This path can be relative or absolute. The default path is `./complate/config.yml`.|stable|
83+
|Shell trust||--shell-trust|Enables the shell value provider for replacing template placeholders. Due to the potential security risk with this option, it is disabled by default. Possible values for this option are `none` (default), `prompt` and `ultimate`|stable|
84+
|Backend|-b|--backend|Defines the backend for the user interaction.|`CLI` is stable. `UI` is experimental (feature = "backend+ui").|
85+
86+
### Configuration file
87+
88+
Please find an example for the configuration file here:
89+
```
90+
version: 0.6
91+
templates:
92+
default:
93+
content:
94+
inline: |-
95+
{{ a.summary }} | {{ e.version }}
96+
Components: [{{ f.components }}]
97+
Author: {{ b.author.name }} | {{ c.author.account }}
98+
99+
Files:
100+
{{ d.git.staged.files }}
101+
values:
102+
a.summary:
103+
prompt: "Enter the summary"
104+
b.author.name:
105+
shell: "git config user.name | tr -d '\n'"
106+
c.author.account:
107+
shell: "whoami | tr -d '\n'"
108+
d.git.staged.files:
109+
shell: "git diff --name-status --cached"
110+
e.version:
111+
select:
112+
text: Select the version level that shall be incremented
113+
options:
114+
- "#patch"
115+
- "#minor"
116+
- "#major"
117+
f.components:
118+
check:
119+
text: Select the components that are affected
120+
options:
121+
- security
122+
- command::print
123+
- backend+cli
124+
- backend+ui
125+
- misc
126+
127+
```
128+
This project also uses complate templates that can be found in `./complate/config.yml`.
129+
130+
#### Value providers
131+
132+
|Type|Description|Fields|
133+
|-- |-- |-- |
134+
|static|Replaces the value by a static string.|-|
135+
|prompt|Asks the user for input when executing the templating process.|text: string|
136+
|shell|Invokes a certain shell command and renders STDOUT as replacing string into the variable. Due to the fact that this option can run arbitrary shell commands, it is disabled by default. Pass the `--shell-trust` flag to the CLI in order to activate this feature.|-|
137+
|select|Gives the user the option to select _one_ item from the provided array of items.|text: string, options: []string|
138+
|check|Gives the user the option to select _n_ items from the provided array of items.|text: string, options: []string|
139+
140+
<!-- cargo-sync-readme start -->
141+
142+
143+
<!-- cargo-sync-readme end -->

0 commit comments

Comments
 (0)