Skip to content

Commit 8e12b06

Browse files
technoweenietechnoweenie
committed
refspec docs
1 parent 96cfc0e commit 8e12b06

2 files changed

Lines changed: 74 additions & 12 deletions

File tree

‎docs/api/batch.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ some objects:
3131
* `transfers` - An optional Array of String identifiers for transfer adapters
3232
that the client has configured. If omitted, the `basic` transfer adapter MUST
3333
be assumed by the server.
34+
* `ref` - Optional object describing the server ref that the objects belong to. Note: Added in v2.4.
35+
* `name` - Fully-qualified server refspec.
3436
* `objects` - An Array of objects to download.
3537
* `oid` - String OID of the LFS object.
3638
* `size` - Integer byte size of the LFS object. Must be at least zero.
@@ -48,6 +50,7 @@ transfer adapters.
4850
{
4951
"operation": "download",
5052
"transfers": [ "basic" ],
53+
"ref": { "name": "refs/heads/master" },
5154
"objects": [
5255
{
5356
"oid": "12345678",
@@ -57,6 +60,62 @@ transfer adapters.
5760
}
5861
```
5962

63+
#### Ref Property
64+
65+
The Batch API added the `ref` property in LFS v2.4 to support Git server authentication schemes that take the refspec into account. Since this is
66+
a new addition to the API, servers should be able to operate with a missing or null `ref` property.
67+
68+
Some examples will illustrate how the `ref` property can be used.
69+
70+
* User `owner` has full access to the repository.
71+
* User `contrib` has readonly access to the repository, and write access to `refs/heads/contrib`.
72+
73+
```js
74+
{
75+
"operation": "download",
76+
"transfers": [ "basic" ],
77+
"objects": [
78+
{
79+
"oid": "12345678",
80+
"size": 123,
81+
}
82+
]
83+
}
84+
```
85+
86+
With this payload, both `owner` and `contrib` can download the requested object, since they both have read access.
87+
88+
```js
89+
{
90+
"operation": "upload",
91+
"transfers": [ "basic" ],
92+
"objects": [
93+
{
94+
"oid": "12345678",
95+
"size": 123,
96+
}
97+
]
98+
}
99+
```
100+
101+
With this payload, only `owner` can upload the requested object.
102+
103+
```js
104+
{
105+
"operation": "upload",
106+
"transfers": [ "basic" ],
107+
"ref": { "name": "refs/heads/contrib" },
108+
"objects": [
109+
{
110+
"oid": "12345678",
111+
"size": 123,
112+
}
113+
]
114+
}
115+
```
116+
117+
Both `owner` and `contrib` can upload the request object.
118+
60119
### Successful Responses
61120

62121
The Batch API should always return with a 200 status, unless there are some

‎docs/api/locking.md‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ simplest use case: single branch locking. The API is designed to be extensible
2626
as we experiment with more advanced locking scenarios, as defined in the
2727
[original proposal](/docs/proposals/locking.md).
2828

29+
The [Batch API's `ref` property docs](./batch.md#ref-property) describe how the `ref` property can be used to support auth schemes that include the server ref. Locking API implementations should also only use it for authentication, until advanced locking scenarios have been developed.
30+
2931
## Create Lock
3032

3133
The client sends the following to create a lock by sending a `POST` to `/locks`
@@ -35,9 +37,8 @@ to one user.
3537

3638
* `path` - String path name of the file that is locked. This should be
3739
relative to the root of the repository working directory.
38-
* `ref` - The fully-qualified reference from which the client is locking the
39-
file. It is the responsibility of the server implementing this specification
40-
to decide on the semantic meaning of this.
40+
* `ref` - Optional object describing the server ref that the locks belong to. Note: Added in v2.4.
41+
* `name` - Fully-qualified server refspec.
4142

4243
```js
4344
// POST https://lfs-server.com/locks
@@ -47,7 +48,7 @@ to decide on the semantic meaning of this.
4748
{
4849
"path": "foo/bar.zip",
4950
"ref": {
50-
"name": "refs/heads/my-feature
51+
"name": "refs/heads/my-feature"
5152
}
5253
}
5354
```
@@ -157,8 +158,8 @@ The properties are sent as URI query values, instead of through a JSON body:
157158
should be the `next_cursor` from a previous request.
158159
* `limit` - The integer limit of the number of locks to return. The server
159160
should have its own upper and lower bounds on the supported limits.
160-
* `ref` - Optional reference representing the reference from which the client
161-
is searching for looks.
161+
* `ref` - Optional fully qualified server refspec
162+
from which to search for locks.
162163

163164
```js
164165
// GET https://lfs-server.com/locks?path=&id=&cursor=&limit=
@@ -251,8 +252,11 @@ LFS Servers should ensure that users have push access to the repository.
251252
Clients send the following to list locks for verification by sending a `POST`
252253
to `/locks/verify` (appended to the LFS server url, as described above):
253254

254-
* `cursor`
255-
* `limit`
255+
* `ref` - Optional object describing the server ref that the locks belong to. Note: Added in v2.4.
256+
* `name` - Fully-qualified server refspec.
257+
* `cursor` - Optional cursor to allow pagination. Servers can determine how cursors are formatted based on how they are stored internally.
258+
* `limit` - Optional limit to how many locks to
259+
return.
256260

257261
```js
258262
// POST https://lfs-server.com/locks/verify
@@ -385,9 +389,8 @@ Properties:
385389

386390
* `force` - Optional boolean specifying that the user is deleting another user's
387391
lock.
388-
* `ref` - Optional reference object specifying the reference from which the
389-
client is deleting the lock. It is the responsibility of the server implementing
390-
this specification to decide upon the semantic meaning of this.
392+
* `ref` - Optional object describing the server ref that the locks belong to. Note: Added in v2.4.
393+
* `name` - Fully-qualified server refspec.
391394

392395
```js
393396
// POST https://lfs-server.com/locks/:id/unlock
@@ -398,7 +401,7 @@ this specification to decide upon the semantic meaning of this.
398401
{
399402
"force": true,
400403
"ref": {
401-
"name": "refs/heads/my-feature
404+
"name": "refs/heads/my-feature"
402405
}
403406
}
404407
```

0 commit comments

Comments
 (0)