1 | # node-gitlog
|
2 |
|
3 | Git log parser for Node.JS
|
4 |
|
5 | [![build status](https://api.travis-ci.org/domharrington/node-gitlog.svg)](http://travis-ci.org/domharrington/node-gitlog)
|
6 | [![dependency status](https://david-dm.org/domharrington/node-gitlog.svg)](https://david-dm.org/domharrington/node-gitlog)
|
7 |
|
8 | ## Installation
|
9 |
|
10 | ```sh
|
11 | npm install gitlog --save
|
12 | ```
|
13 |
|
14 | ## Usage
|
15 |
|
16 | ```js
|
17 | const gitlog = require("gitlog").default;
|
18 |
|
19 | const options = {
|
20 | repo: __dirname + "/test-repo-folder",
|
21 | number: 20,
|
22 | author: "Dom Harrington",
|
23 | fields: ["hash", "abbrevHash", "subject", "authorName", "authorDateRel"],
|
24 | execOptions: { maxBuffer: 1000 * 1024 },
|
25 | };
|
26 |
|
27 | // Synchronous
|
28 | const commits = gitlog(options);
|
29 | console.log(commits);
|
30 |
|
31 | // Asynchronous (with Callback)
|
32 | gitlog(options, function (error, commits) {
|
33 | // Commits is an array of commits in the repo
|
34 | console.log(commits);
|
35 | });
|
36 |
|
37 | const { gitlogPromise } = require("gitlog");
|
38 |
|
39 | // Asynchronous (with Promise)
|
40 | gitlogPromise(options)
|
41 | .then((commits) => console.log(commits))
|
42 | .catch((err) => console.log(err));
|
43 | ```
|
44 |
|
45 | `gitlog` comes with full typescript support!
|
46 |
|
47 | ```ts
|
48 | import gitlog, { GitlogOptions } from "gitlog";
|
49 |
|
50 | // Option 1: Just use the function, returned commit type has specified fields
|
51 | gitlog({
|
52 | repo: "foo",
|
53 | fields: ["subject", "authorName", "authorDate"],
|
54 | });
|
55 |
|
56 | // Option 2: Use Options type to create options
|
57 | const options: GitlogOptions<"subject" | "authorName" | "authorDate"> = {
|
58 | repo: "foo",
|
59 | fields: ["subject", "authorName", "authorDate"],
|
60 | };
|
61 |
|
62 | gitlog(options);
|
63 |
|
64 | // Option 3: Typescript Magic
|
65 | const options = {
|
66 | repo: "foo",
|
67 | fields: ["subject", "authorName", "authorDate"] as const,
|
68 | };
|
69 |
|
70 | gitlog(options);
|
71 |
|
72 | // NOT SUPPORTED: Without "as const" gitlog can't create a good return type
|
73 | const options = {
|
74 | repo: "foo",
|
75 | fields: ["subject", "authorName", "authorDate"],
|
76 | };
|
77 |
|
78 | gitlog(options);
|
79 | ```
|
80 |
|
81 | ## Options
|
82 |
|
83 | See [git log](http://git-scm.com/docs/git-log)
|
84 |
|
85 | ### repo
|
86 |
|
87 | The location of the repo, required field.
|
88 |
|
89 | ### number
|
90 |
|
91 | The number of commits to return, defaults to 10.
|
92 |
|
93 | ### since/after
|
94 |
|
95 | Show commits more recent than a specific date.
|
96 |
|
97 | ### until/before
|
98 |
|
99 | Show commits older than a specific date.
|
100 |
|
101 | ### author/committer
|
102 |
|
103 | Limit the commits output to ones with author/committer header lines that match the specified pattern.
|
104 |
|
105 | ### nameStatus
|
106 |
|
107 | Below fields was returned from the log:
|
108 |
|
109 | - files - changed files names (array)
|
110 | - status - changed files status (array)
|
111 |
|
112 | This option is enabled by default.
|
113 |
|
114 | ### findCopiesHarder
|
115 |
|
116 | Much more likely to set status codes to 'C' if files are exact copies of each other.
|
117 |
|
118 | This option is disabled by default.
|
119 |
|
120 | ### includeMergeCommitFiles
|
121 |
|
122 | Pass the `-m` option to includes files in a merge commit.
|
123 |
|
124 | This option is disabled by default.
|
125 |
|
126 | ### all
|
127 |
|
128 | Find commits on all branches instead of just on the current one.
|
129 |
|
130 | This option is disabled by default.
|
131 |
|
132 | ### branch ([revision range](https://git-scm.com/docs/git-log#git-log-ltrevisionrangegt))
|
133 |
|
134 | Show only commits in the specified branch or revision range.
|
135 |
|
136 | By default uses the current branch and defaults to `HEAD` (i.e. the whole history leading to the current commit).
|
137 |
|
138 | ### file
|
139 |
|
140 | Optional file filter for the `git log` command
|
141 |
|
142 | ### execOptions
|
143 |
|
144 | Type: `Object`
|
145 |
|
146 | Specify some options to be passed to the [.exec()](http://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback) method:
|
147 |
|
148 | - `cwd` String _Current working directory of the child process_
|
149 | - `env` Object _Environment key-value pairs_
|
150 | - `setsid` Boolean
|
151 | - `encoding` String _(Default: 'utf8')_
|
152 | - `timeout` Number _(Default: 0)_
|
153 | - `maxBuffer` Number _(Default: 200\*1024)_
|
154 | - `killSignal` String _(Default: 'SIGTERM')_
|
155 |
|
156 | ### optional fields
|
157 |
|
158 | An array of fields to return from the log, here are the possible options:
|
159 |
|
160 | - `hash` - the long hash of the commit e.g. 7dd0b07625203f69cd55d779d873f1adcffaa84a
|
161 | - `abbrevHash` - the abbreviated commit hash e.g. 7dd0b07
|
162 | - `treeHash` - the tree hash of the commit
|
163 | - `abbrevTreeHash` - the abbreviated commit hash
|
164 | - `parentHashes` - the parent hashes
|
165 | - `abbrevParentHashes` - the abbreviated parent hashes
|
166 | - `authorName` - author name of the commit
|
167 | - `authorEmail` - author email of the commit
|
168 | - `authorDate` - author date of the commit
|
169 | - `authorDateRel` - relative author date of the commit
|
170 | - `committerName` - committer name
|
171 | - `committerEmail` - committer email
|
172 | - `committerDate` - committer date
|
173 | - `committerDateRel` - relative committer date
|
174 | - `subject` - commit message (first line)
|
175 | - `body` - commit body
|
176 | - `rawBody` - raw body (subject + body)
|
177 |
|
178 | Defaults to 'abbrevHash', 'hash', 'subject' and 'authorName'.
|
179 |
|
180 | ## How it works
|
181 |
|
182 | This module works by executing a child process (using `child_process.exec()`) to the `git` executable, then parsing the stdout into commits. This is done using the `--pretty` command line option which allows you to provide a custom formatter to `git log`. To enable easy parsing the format is delimited by a tab (`\t`) character.
|
183 |
|
184 | ## Example
|
185 |
|
186 | The following is an example of what a parsed commit might look like.
|
187 |
|
188 | ```json
|
189 | {
|
190 | "hash": "6a7ef5e3b3d9c77743140443c8f9e792b0715721",
|
191 | "abbrevHash": "6a7ef5e",
|
192 | "treeHash": "f1bf51b15b48a00c33727f364afef695029864c0",
|
193 | "abbrevTreeHash": "f1bf51b",
|
194 | "parentHashes": "cfe06dbdb8d0a193640977e016a04678f8f3b04f",
|
195 | "abbrevParentHashes": "cfe06dbdb8d0a193640977e016a04678f8f3b04f",
|
196 | "authorName": "Dom Harrington",
|
197 | "authorEmail": "dom@harringtonxxxxx",
|
198 | "authorDate": "2015-04-09 09:39:23 +0100",
|
199 | "authorDateRel": "6 days ago",
|
200 | "committerName": "Dom Harrington",
|
201 | "committerEmail": "dom@harringtonxxxxx",
|
202 | "committerDate": "Thu Apr 9 09:39:23 2015 +0100",
|
203 | "committerDateRel": "6 days ago",
|
204 | "subject": "1.0.0",
|
205 | "status": ["M"],
|
206 | "files": ["package.json"]
|
207 | }
|
208 | ```
|
209 |
|
210 | ## Contributors ✨
|
211 |
|
212 | Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
|
213 |
|
214 |
|
215 |
|
216 |
|
217 | <table>
|
218 | <tr>
|
219 | <td align="center"><a href="https://github.com/domharrington"><img src="https://avatars0.githubusercontent.com/u/848223?v=4" width="100px;" alt=""/><br /><sub><b>domharrington</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=domharrington" title="Code">💻</a> <a href="https://github.com/domharrington/node-gitlog/commits?author=domharrington" title="Documentation">📖</a> <a href="#example-domharrington" title="Examples">💡</a> <a href="#ideas-domharrington" title="Ideas, Planning, & Feedback">🤔</a></td>
|
220 | <td align="center"><a href="http://hipstersmoothie.com"><img src="https://avatars3.githubusercontent.com/u/1192452?v=4" width="100px;" alt=""/><br /><sub><b>Andrew Lisowski</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=hipstersmoothie" title="Code">💻</a> <a href="https://github.com/domharrington/node-gitlog/commits?author=hipstersmoothie" title="Documentation">📖</a> <a href="#infra-hipstersmoothie" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-hipstersmoothie" title="Maintenance">🚧</a></td>
|
221 | <td align="center"><a href="http://metaodi.ch"><img src="https://avatars1.githubusercontent.com/u/538415?v=4" width="100px;" alt=""/><br /><sub><b>Stefan Oderbolz</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/issues?q=author%3Ametaodi" title="Bug reports">🐛</a> <a href="https://github.com/domharrington/node-gitlog/commits?author=metaodi" title="Code">💻</a></td>
|
222 | <td align="center"><a href="https://github.com/palortoff"><img src="https://avatars1.githubusercontent.com/u/10258543?v=4" width="100px;" alt=""/><br /><sub><b>palortoff</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/issues?q=author%3Apalortoff" title="Bug reports">🐛</a> <a href="https://github.com/domharrington/node-gitlog/commits?author=palortoff" title="Code">💻</a></td>
|
223 | <td align="center"><a href="https://malys.github.io/"><img src="https://avatars1.githubusercontent.com/u/463016?v=4" width="100px;" alt=""/><br /><sub><b>Malys</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/issues?q=author%3Amalys" title="Bug reports">🐛</a> <a href="https://github.com/domharrington/node-gitlog/commits?author=malys" title="Code">💻</a> <a href="https://github.com/domharrington/node-gitlog/commits?author=malys" title="Documentation">📖</a></td>
|
224 | <td align="center"><a href="http://CodeGymSleep.com/"><img src="https://avatars3.githubusercontent.com/u/6986032?v=4" width="100px;" alt=""/><br /><sub><b>Mike Mellor</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=mikemellor11" title="Code">💻</a></td>
|
225 | <td align="center"><a href="https://github.com/hmedney"><img src="https://avatars3.githubusercontent.com/u/1221751?v=4" width="100px;" alt=""/><br /><sub><b>Hunter Medney</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=hmedney" title="Code">💻</a></td>
|
226 | </tr>
|
227 | <tr>
|
228 | <td align="center"><a href="https://github.com/Gilwyad"><img src="https://avatars3.githubusercontent.com/u/1919041?v=4" width="100px;" alt=""/><br /><sub><b>Peter Baranyi</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=Gilwyad" title="Code">💻</a> <a href="https://github.com/domharrington/node-gitlog/issues?q=author%3AGilwyad" title="Bug reports">🐛</a></td>
|
229 | <td align="center"><a href="https://twitter.com/B_Blackwo"><img src="https://avatars0.githubusercontent.com/u/7598058?v=4" width="100px;" alt=""/><br /><sub><b>Benjamin Blackwood</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=BBlackwo" title="Documentation">📖</a></td>
|
230 | <td align="center"><a href="https://github.com/Asheboy"><img src="https://avatars1.githubusercontent.com/u/1822529?v=4" width="100px;" alt=""/><br /><sub><b>Ash Summers</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=Asheboy" title="Code">💻</a> <a href="https://github.com/domharrington/node-gitlog/commits?author=Asheboy" title="Tests">⚠️</a></td>
|
231 | <td align="center"><a href="https://github.com/007design"><img src="https://avatars0.githubusercontent.com/u/1998403?v=4" width="100px;" alt=""/><br /><sub><b>007design</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=007design" title="Code">💻</a></td>
|
232 | <td align="center"><a href="https://github.com/tobaccoplaybook"><img src="https://avatars2.githubusercontent.com/u/21124900?v=4" width="100px;" alt=""/><br /><sub><b>tobaccoplaybook</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=tobaccoplaybook" title="Code">💻</a></td>
|
233 | <td align="center"><a href="http://nicola.io"><img src="https://avatars1.githubusercontent.com/u/1424850?v=4" width="100px;" alt=""/><br /><sub><b>Nicola</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=nicola" title="Code">💻</a></td>
|
234 | <td align="center"><a href="http://bluelovers.net"><img src="https://avatars0.githubusercontent.com/u/167966?v=4" width="100px;" alt=""/><br /><sub><b>bluelovers</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=bluelovers" title="Code">💻</a></td>
|
235 | </tr>
|
236 | <tr>
|
237 | <td align="center"><a href="https://github.com/afram"><img src="https://avatars0.githubusercontent.com/u/2238230?v=4" width="100px;" alt=""/><br /><sub><b>Marwan Butrous</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=afram" title="Code">💻</a></td>
|
238 | <td align="center"><a href="https://github.com/FishOrBear"><img src="https://avatars0.githubusercontent.com/u/19372111?v=4" width="100px;" alt=""/><br /><sub><b>FishOrBear</b></sub></a><br /><a href="https://github.com/domharrington/node-gitlog/commits?author=FishOrBear" title="Code">💻</a></td>
|
239 | </tr>
|
240 | </table>
|
241 |
|
242 |
|
243 |
|
244 |
|
245 |
|
246 |
|
247 | This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
|