Skip to content

Commit 61904b7

Browse files
barelyhumanbarelyhuman
committed
docs: manual update for basics
1 parent 9c4b170 commit 61904b7

File tree

2 files changed

+217
-5
lines changed

2 files changed

+217
-5
lines changed

‎docs/manual.md

Lines changed: 192 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,195 @@
1212

1313
# Manual
1414

15-
TBD
15+
- [Basics](#basics)
16+
- [generate](#generate)
17+
- [release](#release)
18+
- [Advanced](#advanced)
19+
- [CLI](#cli)
20+
21+
<h3 id="basics">Basics</h3>
22+
23+
**_`commitlog`_** come with 2 basic functionalities
24+
25+
- Generating commits as changelogs in markdown
26+
- Managing your version and tags
27+
28+
Both the above are available as sub commands and we'll go through each one by
29+
one.
30+
31+
Just running `commitlog` no longer works as it did in v1, you'll need to specify
32+
a sub command to get it working.
33+
34+
This has been done to keep it simpler to keep arbitrary behaviour to a minimum
35+
36+
<h4 id="generate">generate</h3>
37+
38+
The first one is `generate` and in most cases you'll just be using this to
39+
handle generation of commits as a list of markdown notes
40+
41+
Here's an example of what it'll look like to run the `generate` sub-command
42+
43+
```sh
44+
$ commitlog generate
45+
# or
46+
$ commitlog g
47+
```
48+
49+
**Output**:
50+
51+
```md
52+
## All Changes
53+
87ce3fc76b252908cdd81f9537713f8d67813652 chore: v2.0.0-beta.0
54+
55+
09fc85c0d1d52d770bbbf39ac45907103a53d354 refactor: swap go-git for push with exec
56+
57+
5bafe9d105298001707c7c816e60d3ef0257a816 fix: tag creation
58+
59+
909fd032facdeb4fb7633a4fad82dced28e8de83 chore: swap debugging logger with stderr printer
60+
<!-- .... more commits till the end of tag -->
61+
```
62+
63+
The behaviour of the `generate` command is like so
64+
65+
- go through all commits from the current `HEAD` (commit with the `HEAD`
66+
reference) till the last commit or the most recent tagged commit.
67+
- the other case is where if the latest commit is also a tagged commit, it'll
68+
still go till the most recent tagged commit.
69+
70+
eg: v0.0.2 -> HEAD, v0.0.1 -> SOMEHASH, would give you the commits between
71+
both the tags.
72+
73+
This is the default behavior of commitlog and can be changed by passing various
74+
flags which you'll read about soon.
75+
76+
<h4 id="release">release</h3>
77+
78+
The `release` sub-command is a complimentary sub-command added to commitlog to
79+
help you with managing release versions. I understand that most languages have
80+
their own package version management and you might want to work with them but
81+
that's also why the `release` sub-command isn't something you need, it's there
82+
for cases where you might wanna use it.
83+
84+
My primary usecase is when working with repositories that work with multiple
85+
languages and I'd prefer a unified version.
86+
87+
The `release` command doesn't modify your source code files but instead handles
88+
the version with it's own file named `.commitlog.release`, which just holds the
89+
**version** number right now and while this does have the X.X.X format (semantic
90+
versioning format) the increments or how you handle them doesn't have to be.
91+
92+
The command is flexible enough for you to combine and create your own way of
93+
versioning.
94+
95+
##### Initialize
96+
97+
```sh
98+
$ commitlog release --init
99+
# or
100+
$ commitlog r --init
101+
```
102+
103+
Once initialized, you'll see a `.commitlog.release` file in your repo with the
104+
version `v0.0.0` to start with.
105+
106+
##### Increments
107+
108+
Post that you can use the remaining flags to help you incrementing the version
109+
as needed.
110+
111+
```sh
112+
$ commitlog r --major # change to v1.0.0
113+
$ commitlog r --minor # change to v0.1.0
114+
$ commitlog r --patch # change to v0.0.1
115+
$ commitlog r --pre # change to v0.0.0-beta.0
116+
$ commitlog r --pre --pre-tag="dev" # change to v0.0.0-dev.0
117+
118+
# or go bonkers
119+
$ commitlog r --patch --pre --pre-tag="dev" # change to v0.0.1-dev.0
120+
$ commitlog r --major --patch --pre --pre-tag="dev" # change to v1.0.1-dev.0
121+
```
122+
123+
#### Git actions
124+
125+
Most times you'd also want a tool like this to create commits and tags for you
126+
which is fair, so `release` does come with a few git actions.
127+
128+
- `--commit` (will create a commit and tag it for you)
129+
- `--push` (will push the commits and tags for you)
130+
131+
The whole command would look a little something like this
132+
133+
```sh
134+
$ commitlog r --patch --commit --push
135+
```
136+
137+
<h3 id="advanced">Advanced</h3>
138+
139+
**TBD**
140+
141+
<h3 id="cli">CLI</h3>
142+
143+
This is the entire CLI reference, which you can also access by using the `-h`
144+
flag on the downloaded binary.
145+
146+
**`commitlog -h`**
147+
148+
```
149+
NAME:
150+
commitlog - commits to changelogs
151+
152+
USAGE:
153+
commitlog [global options] command [command options] [arguments...]
154+
155+
COMMANDS:
156+
generate, g commits to changelogs
157+
release, r manage .commitlog.release version
158+
help, h Shows a list of commands or help for one command
159+
160+
GLOBAL OPTIONS:
161+
--help, -h show help (default: false)
162+
```
163+
164+
---
165+
166+
**`commitlog g -h`**
167+
168+
```
169+
NAME:
170+
commitlog generate - commits to changelogs
171+
172+
USAGE:
173+
commitlog generate [command options] [arguments...]
174+
175+
OPTIONS:
176+
--categories value categories to use, includes all commits by default. any text you add here will be used to create categories out of the commits
177+
--end END, -e END END reference for the commit to stop including commits at.This is exclusive of the given commit reference
178+
--out FILE, -o FILE path to the output FILE
179+
--path PATH, -p PATH root with the '.git' folder PATH (default: ".")
180+
--promo add promo text to the end of output (default: false)
181+
--start START, -s START START reference for the commit to include commits from,This is inclusive of the given commit reference
182+
--stdio print to the stdout (default: true)
183+
```
184+
185+
---
186+
187+
**`commitlog r -h`**
188+
189+
```
190+
NAME:
191+
commitlog release - manage .commitlog.release version
192+
193+
USAGE:
194+
commitlog release [command options] [arguments...]
195+
196+
OPTIONS:
197+
--commit if true will create a commit and tag, of the changed version (default: false)
198+
--init initialise commitlog release (default: false)
199+
--major create a major version (default: false)
200+
--minor create a minor version (default: false)
201+
--patch create a patch version (default: false)
202+
--path PATH, -p PATH PATH to a folder where .commitlog.release exists or is to be created.(note: do not use `--commit` or `--push` if the file isn't in the root) (default: ".")
203+
--pre create a pre-release version. will default to patch increment unlessspecified and not already a pre-release (default: false)
204+
--pre-tag value create a pre-release version (default: "beta")
205+
--push if true will create push the created release commit + tag on origin (default: false)
206+
```

‎docs/styles.css

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
@import url("https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;600;700&display=swap");
22

3+
4+
:root {
5+
--base: #fff;
6+
--surface: #efefef;
7+
--text: #333;
8+
--muted: #444;
9+
--accent: dodgerblue;
10+
}
11+
12+
html,
13+
body {
14+
background: var(--base);
15+
}
16+
317
html {
418
font-size: 87.5%;
519
/*14px*/
@@ -9,7 +23,7 @@ body {
923
max-width: 100ch;
1024
margin: 0 auto;
1125
padding: 1em;
12-
26+
color: var(--text);
1327
font-family: "Fira Code", monospace;
1428
font-weight: 400;
1529
line-height: 1.75;
@@ -59,15 +73,17 @@ code {
5973

6074
code {
6175
padding: 5px;
62-
border: 1px solid slategray;
76+
border: 1px solid var(--surface);
6377
}
6478

6579
pre {
80+
white-space: pre-wrap;
6681
padding: 10px;
67-
border: 1px solid slategray;
82+
border: 1px solid var(--surface);
6883
}
6984

7085
pre>code {
86+
padding: 0px;
7187
border: 0px;
7288
}
7389

@@ -76,5 +92,10 @@ a {
7692
}
7793

7894
a:hover {
79-
color: dodgerblue;
95+
color: var(--accent);
96+
}
97+
98+
hr {
99+
border: 0px;
100+
border-top: 1px solid var(--surface);
80101
}

0 commit comments

Comments
 (0)