docs: help with shallow clone troubleshooting

* closes #7
* closes #12

Author: marionebl

readme.md

@@ -29,7 +29,7 @@ resolves `extends` configurations.
 
 ```shell
 ❯ conventional-changelog-lint --help
-  conventional-changelog-lint@0.1.0 - Lint commit messages against a conventional-changelog preset and ruleset
+  conventional-changelog-lint - Lint commit messages against a conventional-changelog preset and ruleset
 
   [input] reads from stdin if --edit, --from, --to are omitted
   --color,-c    toggle formatted output, defaults to: true
@@ -42,6 +42,41 @@ resolves `extends` configurations.
 
 ```
 
+### Recipes
+
+#### git hook
+As a `commitmsg` git-hook with ["husky"](https://git.io/JDwyQg)
+
+```json
+  {
+    "scripts": {
+      "commitmsg": "conventional-changelog-lint -e"
+    }
+  }
+```
+
+
+#### Last commit
+As part of `npm test`
+
+```json
+  {
+    "scripts": {
+      "test": "conventional-changelog-lint --from=HEAD~1"
+    }
+  }
+```
+
+#### Travis
+
+```yml
+# Force full git checkout
+before_install: git fetch --unshallow
+
+# Lint all commits not in the target branch
+before_script: conventional-changelog-lint --from=$TRAVIS_BRANCH to=$TRAVIS_PULL_REQUEST_BRANCH
+```
+
 ### API
 
 The programming interface does not read configuration by default,
@@ -77,28 +112,6 @@ const report = lint(
 );
 ```
 
-### Recipes
-
-*   As a `commitmsg` git-hook with ["husky"](https://git.io/JDwyQg)
-
-```json
-  {
-    "scripts": {
-      "commitmsg": "conventional-changelog-lint -e"
-    }
-  }
-```
-
-*   As part of `npm test`
-
-```json
-  {
-    "scripts": {
-      "test": "conventional-changelog-lint --from=HEAD~1"
-    }
-  }
-```
-
 ## Configuration
 
 `conventional-changelog-lint` is configured via
@@ -186,6 +199,45 @@ wildcards: {
 }
 ```
 
+## Shallow clones
+
+### TL;DR
+
+Perform `git fetch --shallow` before linting.
+
+Most likely you are reading this because you where presented with an error message:
+
+```
+  'Could not get git history from shallow clone. 
+  Use git fetch --shallow before linting.
+  Original issue: https://git.io/vyKMq\n Refer to https://git.io/vyKMv for details.'
+```
+
+### Explanation
+
+git supports checking out `shallow` clones of a repository to save bandwith in times.
+These limited copies do not contain a full git history. This makes `conventional-changelog-lint`
+fail, especially when running on large commit ranges. 
+To ensure linting works every time you should convert a shallow git repo to a complete one.
+Use `git fetch --shallow` to do so.
+
+### Travis
+
+Ensure full git checkouts on TravisCI, add to `.travis.yml`:
+
+```yml
+before_install: 
+  - git fetch --unshallow
+```
+
+### Appveyor
+
+Ensure full git checkouts on AppVeyor, add to `appveyor.yml`:
+
+```yml
+shallow_clone: false
+```
+
 ## Supported Node.js versions
 
 conventional-changelog-lint supports the active Node.js [LTS](https://github.com/nodejs/LTS#lts-schedule) version and higher: `>= 4`

source/library/get-messages.js

@@ -6,6 +6,12 @@ import {readFile} from 'mz/fs';
 
 export default getCommitMessages;
 
+const SHALLOW_MESSAGE = [
+	'Could not get git history from shallow clone.',
+	'Use git fetch --shallow before linting.',
+	'Original issue: https://git.io/vyKMq\n Refer to https://git.io/vyKMv for details.'
+].join('\n');
+
 // Get commit messages
 // Object => Promise<Array<String>>
 async function getCommitMessages(settings) {
@@ -16,7 +22,7 @@ async function getCommitMessages(settings) {
 	}
 
 	if (await isShallow()) {
-		throw new Error('Could not get git history from shallow clone. Original issue: https://git.io/vyKMq\n Refer to https://git.io/vyKMv for details.');
+		throw new Error(SHALLOW_MESSAGE);
 	}
 
 	return await getHistoryCommits({from, to});