Skip to content

Commit 5851a26

Browse files
authored
Doc the fields of some libgit2 types (#22543)
* Doc the fields of some libgit2 types
1 parent 37e911e commit 5851a26

File tree

2 files changed

+52
-0
lines changed

2 files changed

+52
-0
lines changed

base/libgit2/consts.jl

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,13 @@ These are used to select which global option to set or get and are used in `git_
351351
SET_SSL_CERT_LOCATIONS = 12)
352352

353353

354+
"""
355+
Option flags for `GitProxy`.
356+
357+
* `PROXY_NONE`: do not attempt the connection through a proxy.
358+
* `PROXY_AUTO`: attempt to figure out the proxy configuration from the git configuration.
359+
* `PROXY_SPECIFIED`: connect using the URL given in the `url` field of this struct.
360+
"""
354361
@enum(GIT_PROXY, PROXY_NONE,
355362
PROXY_AUTO,
356363
PROXY_SPECIFIED)

base/libgit2/types.jl

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,33 @@ end
193193
Options for connecting through a proxy.
194194
195195
Matches the [`git_proxy_options`](https://libgit2.github.com/libgit2/#HEAD/type/git_proxy_options) struct.
196+
197+
The fields represent:
198+
* `version`: version of the struct in use, in case this changes later. For now, always `1`.
199+
* `proxytype`: an `enum` for the type of proxy to use.
200+
Defined in [`git_proxy_t`](https://libgit2.github.com/libgit2/#HEAD/type/git_proxy_t).
201+
The corresponding Julia enum is `GIT_PROXY` and has values:
202+
- `PROXY_NONE`: do not attempt the connection through a proxy.
203+
- `PROXY_AUTO`: attempt to figure out the proxy configuration from the git configuration.
204+
- `PROXY_SPECIFIED`: connect using the URL given in the `url` field of this struct.
205+
Default is to auto-detect the proxy type.
206+
* `url`: the URL of the proxy.
207+
* `credential_cb`: a pointer to a callback function which will be called if the remote
208+
requires authentication to connect.
209+
* `certificate_cb`: a pointer to a callback function which will be called if certificate
210+
verification fails. This lets the user decide whether or not to keep connecting. If
211+
the function returns `1`, connecting will be allowed. If it returns `0`, the connection
212+
will not be allowed. A negative value can be used to return errors.
213+
* `payload`: the payload to be provided to the two callback functions.
214+
215+
# Examples
216+
```julia-repl
217+
julia> fo = LibGit2.FetchOptions();
218+
219+
julia> fo.proxy_opts = LibGit2.ProxyOptions(url=Cstring("https://my_proxy_url.com"))
220+
221+
julia> fetch(remote, "master", options=fo)
222+
```
196223
"""
197224
@kwdef struct ProxyOptions
198225
version::Cuint = 1
@@ -287,6 +314,12 @@ end
287314
LibGit2.DescribeFormatOptions
288315
289316
Matches the [`git_describe_format_options`](https://libgit2.github.com/libgit2/#HEAD/type/git_describe_format_options) struct.
317+
318+
The fields represent:
319+
* `version`: version of the struct in use, in case this changes later. For now, always `1`.
320+
* `abbreviated_size`: lower bound on the size of the abbreviated `GitHash` to use, defaulting to `7`.
321+
* `always_use_long_format`: set to `1` to use the long format for strings even if a short format can be used.
322+
* `dirty_suffix`: if set, this will be appended to the end of the description string if the [`workdir`](@ref) is dirty.
290323
"""
291324
@kwdef struct DescribeFormatOptions
292325
version::Cuint = 1
@@ -300,6 +333,18 @@ end
300333
301334
Description of one side of a delta.
302335
Matches the [`git_diff_file`](https://libgit2.github.com/libgit2/#HEAD/type/git_diff_file) struct.
336+
337+
The fields represent:
338+
* `id`: the [`GitHash`](@ref) of the item in the diff. If the item is empty on this
339+
side of the diff (for instance, if the diff is of the removal of a file), this will
340+
be `GitHash(0)`.
341+
* `path`: a `NULL` terminated path to the item relative to the working directory of the repository.
342+
* `size`: the size of the item in bytes.
343+
* `flags`: a combination of the [`git_diff_flag_t`](https://libgit2.github.com/libgit2/#HEAD/type/git_diff_flag_t)
344+
flags. The `i`th bit of this integer sets the `i`th flag.
345+
* `mode`: the [`stat`](@ref) mode for the item.
346+
* `id_abbrev`: only present in LibGit2 versions newer than or equal to `0.25.0`.
347+
The length of the `id` field when converted using [`hex`](@ref). Usually equal to `OID_HEXSZ` ($OID_HEXSZ).
303348
"""
304349
struct DiffFile
305350
id::GitHash

0 commit comments

Comments
 (0)