Skip to content

Commit 646b0a0

Browse files
marioneblmarionebl
committed
docs: move doc bodies to docs/
1 parent e55f711 commit 646b0a0

File tree

3 files changed

+145
-179
lines changed

3 files changed

+145
-179
lines changed

‎@commitlint/cli/readme.md

Lines changed: 2 additions & 179 deletions
Original file line numberDiff line numberDiff line change
@@ -2,188 +2,11 @@
22
33
# @commitlint/cli
44

5-
## Installation
5+
## Getting started
66

77
```shell
88
npm install --save-dev @commitlint/cli @commitlint/config-angular
99
echo '{"extends": ["@commitlint/config-angular"]}' > .commitlintrc
1010
```
1111

12-
## Usage
13-
14-
```shell
15-
❯ commitlint --help
16-
commitlint - Lint commit messages
17-
18-
[input] reads from stdin if --edit, --from, --to are omitted
19-
--color,-c toggle formatted output, defaults to: true
20-
--edit,-e read last commit message found in ./git/COMMIT_EDITMSG
21-
--extends,-x array of shareable configurations to extend
22-
--from,-f lower end of the commit range to lint; applies if edit=false
23-
--to,-t upper end of the commit range to lint; applies if edit=false
24-
--quiet,-q toggle console output
25-
```
26-
27-
### Recipes
28-
29-
#### git hook
30-
As a `commitmsg` git-hook with ["husky"](https://git.io/JDwyQg)
31-
32-
```json
33-
{
34-
"scripts": {
35-
"commitmsg": "commitlint -e"
36-
}
37-
}
38-
```
39-
40-
#### Last commit
41-
As part of `npm test`
42-
43-
```json
44-
{
45-
"scripts": {
46-
"test": "commitlint --from=HEAD~1"
47-
}
48-
}
49-
```
50-
51-
#### Lint all commits in Pull Request
52-
53-
You can lint all commits in a PR by passing all commits that
54-
are present in `SOURCE_BRANCH` but unavailable in `BASE_BRANCH`:
55-
56-
```sh
57-
commitlint --from=BASE_BRANCH to=SOURCE_BRANCH
58-
```
59-
60-
Most of the time `BASE_BRANCH` will be `master` for Github Flow.
61-
62-
This assumes `SOURCE_BRANCH` is available on your local checkout.
63-
This is not true by default for all PRs originating from clones of a repository.
64-
65-
Given you'd like to lint all commits in PR origination from branch `remote-test` on the
66-
repository `github.com/other-name/test` targeting `master` on `github.com/your-name/test`:
67-
68-
```sh
69-
cd test # make sure CWD is in your repository
70-
git remote add other-name https://github.com/other-name/test.git
71-
git fetch other-name
72-
73-
commitlint --from=master --to=other-name/test
74-
```
75-
76-
See [scripts/lint:commit.sh](./scripts/lint:commit.sh#6) for an example on how to obtain `SOURCE_BRANCH` from a Github clone automatically on Travis.
77-
78-
#### Travis
79-
80-
Commit Linting on CI has to handle the following cases
81-
82-
* Direct commits
83-
* Branch Pull Requests
84-
* Fork Pull Requests
85-
86-
An exemplary implementation is provided as bash script working on Travis CI.
87-
88-
```yml
89-
# Force full git checkout
90-
before_install: git fetch --unshallow
91-
92-
script:
93-
- ./scripts/lint:commit.sh # [1] scripts/lint:commit.sh
94-
```
95-
96-
> \[1\]: See [scripts/lint:commit.sh](./scripts/lint:commit.sh) for reference
97-
98-
## Shallow clones
99-
100-
### TL;DR
101-
102-
Perform `git fetch --shallow` before linting.
103-
104-
Most likely you are reading this because you where presented with an error message:
105-
106-
```
107-
'Could not get git history from shallow clone.
108-
Use git fetch --shallow before linting.
109-
Original issue: https://git.io/vyKMq\n Refer to https://git.io/vyKMv for details.'
110-
```
111-
112-
### Explanation
113-
114-
git supports checking out `shallow` clones of a repository to save bandwith in times.
115-
These limited copies do not contain a full git history. This makes `commitlint`
116-
fail, especially when running on large commit ranges.
117-
To ensure linting works every time you should convert a shallow git repo to a complete one.
118-
Use `git fetch --shallow` to do so.
119-
120-
### Travis
121-
122-
Ensure full git checkouts on TravisCI, add to `.travis.yml`:
123-
124-
```yml
125-
before_install:
126-
- git fetch --unshallow
127-
```
128-
129-
### Appveyor
130-
131-
Ensure full git checkouts on AppVeyor, add to `appveyor.yml`:
132-
133-
```yml
134-
shallow_clone: false
135-
```
136-
137-
## Related projects
138-
139-
* [angular-precommit](https://git.io/vwTDd)
140-
– Pre commit with angular conventions
141-
142-
* [conventional-changelog-cli](https://git.io/vwTDA)
143-
– Generate a changelog from conventional commit history
144-
145-
* [cz-commitlint](https://git.io/vwTyf)
146-
– Let an interactive command line interface help you with creating commit
147-
messages matching your `commitlint` configuration
148-
149-
* [commitlint-config-angular](https://git.io/vwTy4)
150-
– Shareable commitlint config enforcing the angular
151-
commit convention
152-
153-
* [commitlint-config-atom](https://git.io/vwTy9)
154-
– Shareable configuration for commitlint based on the
155-
atom commit guidelines
156-
157-
* [commitlint-config-patternplate](https://git.io/vwTyz)
158-
– Lint your commits, patternplate-style
159-
160-
* [conventional-commits-detector](https://git.io/vwTyk)
161-
– Detect what commit message convention your repository is using
162-
163-
* [conventional-github-releaser](https://git.io/vwTyI)
164-
– Make a new GitHub release from git metadata
165-
166-
* [conventional-recommended-bump](https://git.io/vwTyL)
167-
– Get a recommended version bump based on conventional commits
168-
169-
* [commitizen](https://git.io/vwTym)
170-
– Simple commit conventions for internet citizens
171-
172-
* [standard-changelog](https://git.io/vwTyO)
173-
– Generate a changelog from conventional commit history, angular-style
174-
175-
---
176-
177-
Copyright by [Mario Nebl](https://github.com/marionebl)
178-
and [contributors](./graphs/contributors).
179-
Released under the [MIT license]('./license.md').
180-
181-
182-
[0]: https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square
183-
[1]: https://nodejs.org/api/documentation.html#documentation_stability_index
184-
[2]: https://img.shields.io/travis/marionebl/commitlint/master.svg?style=flat-square
185-
[3]: https://travis-ci.org/marionebl/commitlint
186-
[4]: https://img.shields.io/appveyor/ci/marionebl/commitlint/master.svg?style=flat-square
187-
[5]: https://ci.appveyor.com/project/marionebl/commitlint
188-
[6]: https://img.shields.io/npm/v/commitlint.svg?style=flat-square
189-
[7]: https://npmjs.org/package/commitlint
12+
Consult [docs/cli](../../docs/cli) for comprehensive documentation.

‎@commitlint/core/readme.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
> Lint commit messages
2+
3+
# @commitlint/core
4+
5+
## Getting started
6+
7+
```shell
8+
npm install --save-dev @commitlint/core
9+
```
10+
11+
Consult [docs/api](../../docs/api) for comprehensive documentation.

‎docs/cli.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# CLI
2+
3+
## Installation
4+
5+
```shell
6+
npm install --save-dev @commitlint/cli
7+
```
8+
9+
## Usage
10+
11+
```shell
12+
❯ commitlint --help
13+
commitlint - Lint commit messages
14+
15+
[input] reads from stdin if --edit, --from, --to are omitted
16+
--color,-c toggle formatted output, defaults to: true
17+
--edit,-e read last commit message found in ./git/COMMIT_EDITMSG
18+
--extends,-x array of shareable configurations to extend
19+
--from,-f lower end of the commit range to lint; applies if edit=false
20+
--to,-t upper end of the commit range to lint; applies if edit=false
21+
--quiet,-q toggle console output
22+
```
23+
24+
### Recipes
25+
26+
#### git hook
27+
As a `commitmsg` git-hook with ["husky"](https://git.io/JDwyQg)
28+
29+
```json
30+
{
31+
"scripts": {
32+
"commitmsg": "commitlint -e"
33+
}
34+
}
35+
```
36+
37+
#### Last commit
38+
As part of `npm test`
39+
40+
```json
41+
{
42+
"scripts": {
43+
"test": "commitlint --from=HEAD~1"
44+
}
45+
}
46+
```
47+
48+
#### Lint all commits in Pull Request
49+
50+
You can lint all commits in a PR by passing all commits that
51+
are present in `SOURCE_BRANCH` but unavailable in `BASE_BRANCH`:
52+
53+
```sh
54+
commitlint --from=BASE_BRANCH to=SOURCE_BRANCH
55+
```
56+
57+
Most of the time `BASE_BRANCH` will be `master` for Github Flow.
58+
59+
This assumes `SOURCE_BRANCH` is available on your local checkout.
60+
This is not true by default for all PRs originating from clones of a repository.
61+
62+
Given you'd like to lint all commits in PR origination from branch `remote-test` on the
63+
repository `github.com/other-name/test` targeting `master` on `github.com/your-name/test`:
64+
65+
```sh
66+
cd test # make sure CWD is in your repository
67+
git remote add other-name https://github.com/other-name/test.git
68+
git fetch other-name
69+
70+
commitlint --from=master --to=other-name/test
71+
```
72+
73+
See [scripts/lint:commit.sh](./scripts/lint:commit.sh#6) for an example on how to obtain `SOURCE_BRANCH` from a Github clone automatically on Travis.
74+
75+
#### Travis
76+
77+
Commit Linting on CI has to handle the following cases
78+
79+
* Direct commits
80+
* Branch Pull Requests
81+
* Fork Pull Requests
82+
83+
An exemplary implementation is provided as bash script working on Travis CI.
84+
85+
```yml
86+
# Force full git checkout
87+
before_install: git fetch --unshallow
88+
89+
script:
90+
- ./scripts/lint:commit.sh # [1] scripts/lint:commit.sh
91+
```
92+
93+
> \[1\]: See [scripts/lint:commit.sh](./scripts/lint:commit.sh) for reference
94+
95+
## Shallow clones
96+
97+
### TL;DR
98+
99+
Perform `git fetch --shallow` before linting.
100+
101+
Most likely you are reading this because you where presented with an error message:
102+
103+
```
104+
'Could not get git history from shallow clone.
105+
Use git fetch --shallow before linting.
106+
Original issue: https://git.io/vyKMq\n Refer to https://git.io/vyKMv for details.'
107+
```
108+
109+
### Explanation
110+
111+
git supports checking out `shallow` clones of a repository to save bandwith in times.
112+
These limited copies do not contain a full git history. This makes `commitlint`
113+
fail, especially when running on large commit ranges.
114+
To ensure linting works every time you should convert a shallow git repo to a complete one.
115+
Use `git fetch --shallow` to do so.
116+
117+
### Travis
118+
119+
Ensure full git checkouts on TravisCI, add to `.travis.yml`:
120+
121+
```yml
122+
before_install:
123+
- git fetch --unshallow
124+
```
125+
126+
### Appveyor
127+
128+
Ensure full git checkouts on AppVeyor, add to `appveyor.yml`:
129+
130+
```yml
131+
shallow_clone: false
132+
```

0 commit comments

Comments
 (0)