Skip to content

Commit c89c456

Browse files
tbranyentbranyen
committed
Update API and guides
1 parent ae4ddf1 commit c89c456

File tree

18 files changed

+482
-103
lines changed

18 files changed

+482
-103
lines changed

‎api/index.md‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1038,20 +1038,21 @@ sections:
10381038

10391039
| Class Methods | |
10401040
| --- | ---: |
1041-
| [<span>Pathspec.</span>matchListDiffEntry <span>(m, pos)</span>](/api/pathspec/#matchListDiffEntry) | <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span> |
1042-
| [<span>Pathspec.</span>matchListEntry <span>(m, pos)</span>](/api/pathspec/#matchListEntry) | <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span> |
1043-
| [<span>Pathspec.</span>matchListEntrycount <span>(m)</span>](/api/pathspec/#matchListEntrycount) | <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span> |
1044-
| [<span>Pathspec.</span>matchListFailedEntry <span>(m, pos)</span>](/api/pathspec/#matchListFailedEntry) | <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span> |
1045-
| [<span>Pathspec.</span>matchListFailedEntrycount <span>(m)</span>](/api/pathspec/#matchListFailedEntrycount) | <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span> |
1041+
| [<span>Pathspec.</span>create <span>(pathspec)</span>](/api/pathspec/#create) | <span class="tags"><span class="async">Async</span></span> |
1042+
| [<span>Pathspec.</span>matchListDiffEntry <span>(m, pos)</span>](/api/pathspec/#matchListDiffEntry) | <span class="tags"><span class="sync">Sync</span></span> |
1043+
| [<span>Pathspec.</span>matchListEntry <span>(m, pos)</span>](/api/pathspec/#matchListEntry) | <span class="tags"><span class="sync">Sync</span></span> |
1044+
| [<span>Pathspec.</span>matchListEntrycount <span>(m)</span>](/api/pathspec/#matchListEntrycount) | <span class="tags"><span class="sync">Sync</span></span> |
1045+
| [<span>Pathspec.</span>matchListFailedEntry <span>(m, pos)</span>](/api/pathspec/#matchListFailedEntry) | <span class="tags"><span class="sync">Sync</span></span> |
1046+
| [<span>Pathspec.</span>matchListFailedEntrycount <span>(m)</span>](/api/pathspec/#matchListFailedEntrycount) | <span class="tags"><span class="sync">Sync</span></span> |
10461047

10471048
| Instance Methods | |
10481049
| --- | ---: |
1049-
| [<span>Pathspec#</span>free <span>()</span>](/api/pathspec/#free) | <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span> |
1050-
| [<span>Pathspec#</span>matchDiff <span>(diff, flags)</span>](/api/pathspec/#matchDiff) | <span class="tags"><span class="async">Async</span><span class="experimental">Experimental</span></span> |
1051-
| [<span>Pathspec#</span>matchIndex <span>(index, flags)</span>](/api/pathspec/#matchIndex) | <span class="tags"><span class="async">Async</span><span class="experimental">Experimental</span></span> |
1052-
| [<span>Pathspec#</span>matchTree <span>(tree, flags)</span>](/api/pathspec/#matchTree) | <span class="tags"><span class="async">Async</span><span class="experimental">Experimental</span></span> |
1053-
| [<span>Pathspec#</span>matchWorkdir <span>(repo, flags)</span>](/api/pathspec/#matchWorkdir) | <span class="tags"><span class="async">Async</span><span class="experimental">Experimental</span></span> |
1054-
| [<span>Pathspec#</span>matchesPath <span>(flags, path)</span>](/api/pathspec/#matchesPath) | <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span> |
1050+
| [<span>Pathspec#</span>free <span>()</span>](/api/pathspec/#free) | <span class="tags"><span class="sync">Sync</span></span> |
1051+
| [<span>Pathspec#</span>matchDiff <span>(diff, flags)</span>](/api/pathspec/#matchDiff) | <span class="tags"><span class="async">Async</span></span> |
1052+
| [<span>Pathspec#</span>matchIndex <span>(index, flags)</span>](/api/pathspec/#matchIndex) | <span class="tags"><span class="async">Async</span></span> |
1053+
| [<span>Pathspec#</span>matchTree <span>(tree, flags)</span>](/api/pathspec/#matchTree) | <span class="tags"><span class="async">Async</span></span> |
1054+
| [<span>Pathspec#</span>matchWorkdir <span>(repo, flags)</span>](/api/pathspec/#matchWorkdir) | <span class="tags"><span class="async">Async</span></span> |
1055+
| [<span>Pathspec#</span>matchesPath <span>(flags, path)</span>](/api/pathspec/#matchesPath) | <span class="tags"><span class="sync">Sync</span></span> |
10551056

10561057
| ENUMS | |
10571058
| --- | ---: |
@@ -1224,7 +1225,6 @@ sections:
12241225
| [<span>Remote.</span>isValidName <span>(remote_name)</span>](/api/remote/#isValidName) | <span class="tags"><span class="sync">Sync</span></span> |
12251226
| [<span>Remote.</span>list <span>(repo)</span>](/api/remote/#list) | <span class="tags"><span class="async">Async</span></span> |
12261227
| [<span>Remote.</span>lookup <span>(repo, name, callback)</span>](/api/remote/#lookup) | <span class="tags"><span class="async">Async</span></span> |
1227-
| [<span>Remote.</span>push <span>(refSpecs, options, signature, message)</span>](/api/remote/#push) | <span class="tags"><span class="async">Async</span></span> |
12281228

12291229
| Instance Methods | |
12301230
| --- | ---: |
@@ -1243,11 +1243,12 @@ sections:
12431243
| [<span>Remote#</span>getFetchRefspecs <span>()</span>](/api/remote/#getFetchRefspecs) | <span class="tags"><span class="async">Async</span></span> |
12441244
| [<span>Remote#</span>getPushRefspecs <span>()</span>](/api/remote/#getPushRefspecs) | <span class="tags"><span class="async">Async</span></span> |
12451245
| [<span>Remote#</span>getRefspec <span>(n)</span>](/api/remote/#getRefspec) | <span class="tags"><span class="sync">Sync</span></span> |
1246+
| [<span>Remote#</span>ls <span>(size)</span>](/api/remote/#ls) | <span class="tags"><span class="async">Async</span></span> |
12461247
| [<span>Remote#</span>name <span>()</span>](/api/remote/#name) | <span class="tags"><span class="sync">Sync</span></span> |
12471248
| [<span>Remote#</span>owner <span>()</span>](/api/remote/#owner) | <span class="tags"><span class="sync">Sync</span></span> |
12481249
| [<span>Remote#</span>prune <span>()</span>](/api/remote/#prune) | <span class="tags"><span class="sync">Sync</span></span> |
12491250
| [<span>Remote#</span>pruneRefs <span>()</span>](/api/remote/#pruneRefs) | <span class="tags"><span class="sync">Sync</span></span> |
1250-
| [<span>Remote#</span>push <span>(refspecs, opts, signature, reflog_message)</span>](/api/remote/#push) | <span class="tags"><span class="async">Async</span></span> |
1251+
| [<span>Remote#</span>push <span>(refSpecs, options, signature, message)</span>](/api/remote/#push) | <span class="tags"><span class="async">Async</span></span> |
12511252
| [<span>Remote#</span>pushurl <span>()</span>](/api/remote/#pushurl) | <span class="tags"><span class="sync">Sync</span></span> |
12521253
| [<span>Remote#</span>refspecCount <span>()</span>](/api/remote/#refspecCount) | <span class="tags"><span class="sync">Sync</span></span> |
12531254
| [<span>Remote#</span>save <span>()</span>](/api/remote/#save) | <span class="tags"><span class="sync">Sync</span></span> |
@@ -1293,6 +1294,7 @@ sections:
12931294

12941295
| Instance Methods | |
12951296
| --- | ---: |
1297+
| [<span>Repository#</span>checkoutBranch <span>(branch, opts)</span>](/api/repository/#checkoutBranch) | <span class="tags"><span class="sync">Sync</span></span> |
12961298
| [<span>Repository#</span>config <span>()</span>](/api/repository/#config) | <span class="tags"><span class="async">Async</span></span> |
12971299
| [<span>Repository#</span>configSnapshot <span>()</span>](/api/repository/#configSnapshot) | <span class="tags"><span class="async">Async</span></span> |
12981300
| [<span>Repository#</span>createLightweightTag <span>(String, name)</span>](/api/repository/#createLightweightTag) | <span class="tags"><span class="async">Async</span></span> |
@@ -1326,7 +1328,7 @@ sections:
13261328
| [<span>Repository#</span>odb <span>()</span>](/api/repository/#odb) | <span class="tags"><span class="async">Async</span></span> |
13271329
| [<span>Repository#</span>path <span>()</span>](/api/repository/#path) | <span class="tags"><span class="sync">Sync</span></span> |
13281330
| [<span>Repository#</span>refdb <span>()</span>](/api/repository/#refdb) | <span class="tags"><span class="async">Async</span></span> |
1329-
| [<span>Repository#</span>setHead <span>(refname, signature, log_message)</span>](/api/repository/#setHead) | <span class="tags"><span class="sync">Sync</span></span> |
1331+
| [<span>Repository#</span>setHead <span>(refname, signature, log_message)</span>](/api/repository/#setHead) | <span class="tags"><span class="async">Async</span></span> |
13301332
| [<span>Repository#</span>setHeadDetached <span>(commitish, signature, log_message)</span>](/api/repository/#setHeadDetached) | <span class="tags"><span class="sync">Sync</span></span> |
13311333
| [<span>Repository#</span>setNamespace <span>(nmspace)</span>](/api/repository/#setNamespace) | <span class="tags"><span class="sync">Sync</span></span> |
13321334
| [<span>Repository#</span>setWorkdir <span>(workdir, update_gitlink)</span>](/api/repository/#setWorkdir) | <span class="tags"><span class="sync">Sync</span></span> |

‎api/pathspec/index.md‎

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ menu_item: api
77
return_to:
88
"API Documentation Index": /api/
99
sections:
10+
"create": "#create"
1011
"matchListDiffEntry": "#matchListDiffEntry"
1112
"matchListEntry": "#matchListEntry"
1213
"matchListEntrycount": "#matchListEntrycount"
@@ -21,7 +22,23 @@ sections:
2122
"FLAG": "#FLAG"
2223
---
2324

24-
## <a name="matchListDiffEntry"></a><span>Pathspec.</span>matchListDiffEntry <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span>
25+
## <a name="create"></a><span>Pathspec.</span>create <span class="tags"><span class="async">Async</span></span>
26+
27+
```js
28+
Pathspec.create(pathspec).then(function(pathspec) {
29+
// Use pathspec
30+
});
31+
```
32+
33+
| Parameters | Type | |
34+
| --- | --- | --- |
35+
| pathspec | [Strarray](/api/strarray/) | A git_strarray of the paths to match |
36+
37+
| Returns | |
38+
| --- | --- |
39+
| [Pathspec](/api/pathspec/) | Output of the compiled pathspec |
40+
41+
## <a name="matchListDiffEntry"></a><span>Pathspec.</span>matchListDiffEntry <span class="tags"><span class="sync">Sync</span></span>
2542

2643
```js
2744
var diffDelta = Pathspec.matchListDiffEntry(m, pos);
@@ -36,7 +53,7 @@ var diffDelta = Pathspec.matchListDiffEntry(m, pos);
3653
| --- | --- |
3754
| [DiffDelta](/api/diff_delta/) | The filename of the match |
3855

39-
## <a name="matchListEntry"></a><span>Pathspec.</span>matchListEntry <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span>
56+
## <a name="matchListEntry"></a><span>Pathspec.</span>matchListEntry <span class="tags"><span class="sync">Sync</span></span>
4057

4158
```js
4259
var string = Pathspec.matchListEntry(m, pos);
@@ -51,7 +68,7 @@ var string = Pathspec.matchListEntry(m, pos);
5168
| --- | --- |
5269
| String | The filename of the match |
5370

54-
## <a name="matchListEntrycount"></a><span>Pathspec.</span>matchListEntrycount <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span>
71+
## <a name="matchListEntrycount"></a><span>Pathspec.</span>matchListEntrycount <span class="tags"><span class="sync">Sync</span></span>
5572

5673
```js
5774
var result = Pathspec.matchListEntrycount(m);
@@ -65,7 +82,7 @@ var result = Pathspec.matchListEntrycount(m);
6582
| --- | --- |
6683
| Number | Number of items in match list |
6784

68-
## <a name="matchListFailedEntry"></a><span>Pathspec.</span>matchListFailedEntry <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span>
85+
## <a name="matchListFailedEntry"></a><span>Pathspec.</span>matchListFailedEntry <span class="tags"><span class="sync">Sync</span></span>
6986

7087
```js
7188
var string = Pathspec.matchListFailedEntry(m, pos);
@@ -80,7 +97,7 @@ var string = Pathspec.matchListFailedEntry(m, pos);
8097
| --- | --- |
8198
| String | The pathspec pattern that didn't match anything |
8299

83-
## <a name="matchListFailedEntrycount"></a><span>Pathspec.</span>matchListFailedEntrycount <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span>
100+
## <a name="matchListFailedEntrycount"></a><span>Pathspec.</span>matchListFailedEntrycount <span class="tags"><span class="sync">Sync</span></span>
84101

85102
```js
86103
var result = Pathspec.matchListFailedEntrycount(m);
@@ -94,13 +111,13 @@ var result = Pathspec.matchListFailedEntrycount(m);
94111
| --- | --- |
95112
| Number | Number of items in original pathspec that had no matches |
96113

97-
## <a name="free"></a><span>Pathspec#</span>free <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span>
114+
## <a name="free"></a><span>Pathspec#</span>free <span class="tags"><span class="sync">Sync</span></span>
98115

99116
```js
100117
pathspec.free();
101118
```
102119

103-
## <a name="matchDiff"></a><span>Pathspec#</span>matchDiff <span class="tags"><span class="async">Async</span><span class="experimental">Experimental</span></span>
120+
## <a name="matchDiff"></a><span>Pathspec#</span>matchDiff <span class="tags"><span class="async">Async</span></span>
104121

105122
```js
106123
pathspec.matchDiff(diff, flags).then(function(pathspecMatchList) {
@@ -117,7 +134,7 @@ pathspec.matchDiff(diff, flags).then(function(pathspecMatchList) {
117134
| --- | --- |
118135
| [PathspecMatchList](/api/pathspec_match_list/) | Output list of matches; pass NULL to just get return value |
119136

120-
## <a name="matchIndex"></a><span>Pathspec#</span>matchIndex <span class="tags"><span class="async">Async</span><span class="experimental">Experimental</span></span>
137+
## <a name="matchIndex"></a><span>Pathspec#</span>matchIndex <span class="tags"><span class="async">Async</span></span>
121138

122139
```js
123140
pathspec.matchIndex(index, flags).then(function(pathspecMatchList) {
@@ -134,7 +151,7 @@ pathspec.matchIndex(index, flags).then(function(pathspecMatchList) {
134151
| --- | --- |
135152
| [PathspecMatchList](/api/pathspec_match_list/) | Output list of matches; pass NULL to just get return value |
136153

137-
## <a name="matchTree"></a><span>Pathspec#</span>matchTree <span class="tags"><span class="async">Async</span><span class="experimental">Experimental</span></span>
154+
## <a name="matchTree"></a><span>Pathspec#</span>matchTree <span class="tags"><span class="async">Async</span></span>
138155

139156
```js
140157
pathspec.matchTree(tree, flags).then(function(pathspecMatchList) {
@@ -151,7 +168,7 @@ pathspec.matchTree(tree, flags).then(function(pathspecMatchList) {
151168
| --- | --- |
152169
| [PathspecMatchList](/api/pathspec_match_list/) | Output list of matches; pass NULL to just get return value |
153170

154-
## <a name="matchWorkdir"></a><span>Pathspec#</span>matchWorkdir <span class="tags"><span class="async">Async</span><span class="experimental">Experimental</span></span>
171+
## <a name="matchWorkdir"></a><span>Pathspec#</span>matchWorkdir <span class="tags"><span class="async">Async</span></span>
155172

156173
```js
157174
pathspec.matchWorkdir(repo, flags).then(function(pathspecMatchList) {
@@ -168,7 +185,7 @@ pathspec.matchWorkdir(repo, flags).then(function(pathspecMatchList) {
168185
| --- | --- |
169186
| [PathspecMatchList](/api/pathspec_match_list/) | Output list of matches; pass NULL to just get return value |
170187

171-
## <a name="matchesPath"></a><span>Pathspec#</span>matchesPath <span class="tags"><span class="sync">Sync</span><span class="experimental">Experimental</span></span>
188+
## <a name="matchesPath"></a><span>Pathspec#</span>matchesPath <span class="tags"><span class="sync">Sync</span></span>
172189

173190
```js
174191
var result = pathspec.matchesPath(flags, path);

‎api/remote/index.md‎

Lines changed: 27 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ sections:
1515
"isValidName": "#isValidName"
1616
"list": "#list"
1717
"lookup": "#lookup"
18-
"push": "#push"
1918
"#addFetch": "#addFetch"
2019
"#addPush": "#addPush"
2120
"#autotag": "#autotag"
@@ -31,6 +30,7 @@ sections:
3130
"#getFetchRefspecs": "#getFetchRefspecs"
3231
"#getPushRefspecs": "#getPushRefspecs"
3332
"#getRefspec": "#getRefspec"
33+
"#ls": "#ls"
3434
"#name": "#name"
3535
"#owner": "#owner"
3636
"#prune": "#prune"
@@ -189,28 +189,6 @@ Retrieves the remote by name
189189
| --- | --- |
190190
| [Remote](/api/remote/) | |
191191

192-
## <a name="push"></a><span>Remote.</span>push <span class="tags"><span class="async">Async</span></span>
193-
194-
```js
195-
Remote.push(refSpecs, options, signature, message).then(function(number) {
196-
// Use number
197-
});
198-
```
199-
200-
Pushes to a remote
201-
202-
203-
| Parameters | Type | |
204-
| --- | --- | --- |
205-
| refSpecs | Array | The ref specs that should be pushed |
206-
| options | [PushOptions](/api/push_options/) | Options for the checkout |
207-
| signature | [Signature](/api/signature/) | The identity to use for the reflog of the updated references |
208-
| message | String | The message to use for the update reflog messages |
209-
210-
| Returns | |
211-
| --- | --- |
212-
| Number | error code |
213-
214192
## <a name="addFetch"></a><span>Remote#</span>addFetch <span class="tags"><span class="sync">Sync</span></span>
215193

216194
```js
@@ -388,6 +366,22 @@ var refspec = remote.getRefspec(n);
388366
| --- | --- |
389367
| [Refspec](/api/refspec/) | the nth refspec |
390368
369+
## <a name="ls"></a><span>Remote#</span>ls <span class="tags"><span class="async">Async</span></span>
370+
371+
```js
372+
remote.ls(size).then(function(result) {
373+
// Use result
374+
});
375+
```
376+
377+
| Parameters | Type |
378+
| --- | --- | --- |
379+
| size | Number | the number of remote heads |
380+
381+
| Returns | |
382+
| --- | --- |
383+
| Number | 0 on success, or an error code |
384+
391385
## <a name="name"></a><span>Remote#</span>name <span class="tags"><span class="sync">Sync</span></span>
392386
393387
```js
@@ -431,21 +425,24 @@ var result = remote.pruneRefs();
431425
## <a name="push"></a><span>Remote#</span>push <span class="tags"><span class="async">Async</span></span>
432426
433427
```js
434-
remote.push(refspecs, opts, signature, reflog_message).then(function(result) {
435-
// Use result
428+
remote.push(refSpecs, options, signature, message).then(function(number) {
429+
// Use number
436430
});
437431
```
438432
433+
Pushes to a remote
434+
435+
439436
| Parameters | Type |
440437
| --- | --- | --- |
441-
| refspecs | [Strarray](/api/strarray/) | the refspecs to use for pushing. If none are passed, the configured refspecs will be used |
442-
| opts | [PushOptions](/api/push_options/) | the options |
443-
| signature | [Signature](/api/signature/) | signature to use for the reflog of updated references |
444-
| reflog_message | String | message to use for the reflog of upated references |
438+
| refSpecs | Array | The ref specs that should be pushed |
439+
| options | [PushOptions](/api/push_options/) | Options for the checkout |
440+
| signature | [Signature](/api/signature/) | The identity to use for the reflog of the updated references |
441+
| message | String | The message to use for the update reflog messages |
445442
446443
| Returns | |
447444
| --- | --- |
448-
| Number | |
445+
| Number | error code |
449446
450447
## <a name="pushurl"></a><span>Remote#</span>pushurl <span class="tags"><span class="sync">Sync</span></span>
451448

‎api/repository/index.md‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ sections:
1313
"openBare": "#openBare"
1414
"openExt": "#openExt"
1515
"wrapOdb": "#wrapOdb"
16+
"#checkoutBranch": "#checkoutBranch"
1617
"#config": "#config"
1718
"#configSnapshot": "#configSnapshot"
1819
"#createLightweightTag": "#createLightweightTag"
@@ -159,6 +160,21 @@ Repository.wrapOdb(odb).then(function(repository) {
159160
| --- | --- |
160161
| [Repository](/api/repository/) | |
161162

163+
## <a name="checkoutBranch"></a><span>Repository#</span>checkoutBranch <span class="tags"><span class="sync">Sync</span></span>
164+
165+
```js
166+
repository.checkoutBranch(branch, opts);
167+
```
168+
169+
This will set the HEAD to point to the local branch and then attempt
170+
to update the index and working tree to match the content of the
171+
latest commit on that branch
172+
173+
| Parameters | Type |
174+
| --- | --- | --- |
175+
| branch | String, [Reference](/api/reference/) | the branch to checkout |
176+
| opts | [Object](/api/object/), [CheckoutOptions](/api/checkout_options/) | the options to use for the checkout |
177+
162178
## <a name="config"></a><span>Repository#</span>config <span class="tags"><span class="async">Async</span></span>
163179

164180
```js
@@ -651,10 +667,12 @@ repository.refdb().then(function(refdb) {
651667
| --- | --- |
652668
| [Refdb](/api/refdb/) | |
653669
654-
## <a name="setHead"></a><span>Repository#</span>setHead <span class="tags"><span class="sync">Sync</span></span>
670+
## <a name="setHead"></a><span>Repository#</span>setHead <span class="tags"><span class="async">Async</span></span>
655671
656672
```js
657-
var result = repository.setHead(refname, signature, log_message);
673+
repository.setHead(refname, signature, log_message).then(function(result) {
674+
// Use result
675+
});
658676
```
659677
660678
| Parameters | Type |

0 commit comments

Comments
 (0)