gix 0.58.0

Interact with git repositories just like git would
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330

[package]
name = "gix"
repository = "https://github.com/Byron/gitoxide"
description = "Interact with git repositories just like git would"
license = "MIT OR Apache-2.0"
version = "0.58.0"
authors = ["Sebastian Thiel <sebastian.thiel@icloud.com>"]
edition = "2021"
include = ["src/**/*", "LICENSE-*"]
rust-version = "1.65"

[lib]
doctest = false
test = true

[[example]]
name = "clone"
path = "examples/clone.rs"
required-features = ["blocking-network-client"]

[features]

default = ["max-performance-safe", "comfort", "basic", "extras"]

#! There are various categories of features which help to optimize performance and build times. `gix` comes with 'batteries included' and everything is
#! enabled as long as it doesn't sacrifice compatibility. Most users will be fine with that but will pay with higher compile times than necessary as they
#! probably don't use all of these features.
#!
#! **Thus it's recommended to take a moment and optimize build times by choosing only those 'Components' that you require.** *'Performance' relevant features should
#! be chosen next to maximize efficiency.*
#!
#! #### Application Developers
#!
#! These are considered the end-users, all they need to tune is `Performance` features to optimize the efficiency of their app, assuming they don't use `gix`
#! directly. Otherwise, see the `Library Developers` paragraph.
#!
#! In order to configure a crate that isn't a direct dependency, one has to make it a direct dependency. We recommend
#! `gix-for-configuration = { package = "gix", version = "X.Y.Z", features = […] }` to make clear this dependency isn't used in code.
#!
#! #### Library Developers
#!
#! As a developer of a library, you should start out with `gix = { version = "X.Y.Z", default-features = false }` and add components as you see fit.
#! For best compatibility, **do not activate `max-performance-safe`** or any other performance options.
#!
#! #### Bundles
#!
#! A bundle is a set of related feature toggles which can be activated with a single name that acts as a group.
#! Bundles are for convenience only and bear no further meaning beyond the cargo manifest file.

## More fundamental components that most will be able to make good use of.
basic = ["blob-diff", "revision", "index"]

## Various additional features and capabilities that are not necessarily part of what most users would need.
extras = ["worktree-stream", "worktree-archive", "revparse-regex", "mailmap", "excludes", "attributes", "worktree-mutation", "credentials", "interrupt", "status"]

## Various progress-related features that improve the look of progress message units.
comfort = ["gix-features/progress-unit-bytes", "gix-features/progress-unit-human-numbers"]

#! #### Components
#!
#! A component is a distinct feature which may be comprised of one or more methods around a particular topic.
#! Providers of libraries should only activate the components they need.

## Provide a top-level `command` module that helps with spawning commands similarly to `git`.
command = ["dep:gix-command"]

## Obtain information similar to `git status`.
status = ["gix-status"]

## Utilities for interrupting computations and cleaning up tempfiles.
interrupt = ["dep:signal-hook", "gix-tempfile/signals"]

## Access to `.git/index` files.
index = ["dep:gix-index"]

## Access to credential helpers, which provide credentials for URLs.
# Note that `gix-negotiate` just piggibacks here, as 'credentials' is equivalent to 'fetch & push' right now.
credentials = ["dep:gix-credentials", "dep:gix-prompt", "dep:gix-negotiate"]

## Various ways to alter the worktree makeup by checkout and reset.
worktree-mutation = ["attributes", "dep:gix-worktree-state"]

## Retrieve a worktree stack for querying exclude information
excludes = ["dep:gix-ignore", "dep:gix-worktree", "index"]

## Query attributes and excludes. Enables access to pathspecs, worktree checkouts, filter-pipelines and submodules.
attributes = ["excludes", "dep:gix-filter", "dep:gix-pathspec", "dep:gix-attributes", "dep:gix-submodule", "gix-worktree?/attributes", "command"]

## Add support for mailmaps, as way of determining the final name of commmiters and authors.
mailmap = ["dep:gix-mailmap", "revision"]

## Make revspec parsing possible, as well describing revision.
revision = ["gix-revision/describe", "index"]

## If enabled, revspecs now support the regex syntax like `@^{/^.*x}`. Otherwise, only substring search is supported.
## This feature does increase compile time for niche-benefit, but is required for fully git-compatible revspec parsing.
revparse-regex = ["regex", "revision"]

## Make it possible to diff blobs line by line. Note that this feature is integral for implementing tree-diffs as well due to the handling of rename-tracking,
## which relies on line-by-line diffs in some cases.
blob-diff = ["gix-diff/blob", "attributes"]

## Make it possible to turn a tree into a stream of bytes, which can be decoded to entries and turned into various other formats.
worktree-stream = ["gix-worktree-stream", "attributes"]

## Create archives from a tree in the repository, similar to what `git archive` does.
##
## Note that we disable all default features which strips it off all container support, like `tar` and `zip`.
## Your application should add it as dependency and re-activate the desired features.
worktree-archive = ["gix-archive", "worktree-stream", "attributes"]

#! #### Mutually Exclusive Network Client
#!
#! Either `async-*` or `blocking-*` versions of these toggles may be enabled at a time.
#! For this reason, these must be chosen by the user of the library and can't be pre-selected.
#! Making a choice here also affects which crypto-library ends up being used.

## Make `gix-protocol` available along with an async client.
async-network-client = ["gix-protocol/async-client", "gix-pack/streaming-input", "attributes", "credentials"]
## Use this if your crate uses `async-std` as runtime, and enable basic runtime integration when connecting to remote servers via the `git://` protocol.
async-network-client-async-std = ["async-std", "async-network-client", "gix-transport/async-std"]
## Make `gix-protocol` available along with a blocking client, providing access to the `file://`, git://` and `ssh://` transports.
blocking-network-client = ["gix-protocol/blocking-client", "gix-pack/streaming-input", "attributes", "credentials"]
## Stacks with `blocking-network-client` to provide support for HTTP/S using **curl**, and implies blocking networking as a whole, making the `https://` transport available.
blocking-http-transport-curl = ["blocking-network-client", "gix-transport/http-client-curl"]
## Stacks with `blocking-http-transport-curl` and also enables the `rustls` backend to avoid `openssl`.
blocking-http-transport-curl-rustls = ["blocking-http-transport-curl", "dep:curl-for-configuration-only", "curl-for-configuration-only?/rustls"]
## Stacks with `blocking-network-client` to provide support for HTTP/S using **reqwest**, and implies blocking networking as a whole, making the `https://` transport available.
blocking-http-transport-reqwest = ["blocking-network-client", "gix-transport/http-client-reqwest"]
## Stacks with `blocking-http-transport-reqwest` and enables `https://` via the `rustls` crate.
blocking-http-transport-reqwest-rust-tls = ["blocking-http-transport-reqwest", "reqwest-for-configuration-only/rustls-tls" ]
## Stacks with `blocking-http-transport-reqwest` and enables `https://` via the `rustls` crate.
## This also makes use of `trust-dns` to avoid `getaddrinfo`, but note it comes with its own problems.
blocking-http-transport-reqwest-rust-tls-trust-dns = ["blocking-http-transport-reqwest", "reqwest-for-configuration-only/rustls-tls", "reqwest-for-configuration-only/trust-dns"]
## Stacks with `blocking-http-transport-reqwest` and enables `https://` via the `native-tls` crate.
blocking-http-transport-reqwest-native-tls = ["blocking-http-transport-reqwest", "reqwest-for-configuration-only/default-tls" ]


#! #### Performance
#!
#! The reason these features exist is to allow optimization for compile time and optimize for compatibility by default. This means that some performance options around
#! SHA1 and ZIP might not compile on all platforms, so it depends on the end-user who compiles the application to chose these based on their needs.

## Activate features that maximize performance, like using threads, but leave everything else that might affect compatibility out to allow users more fine-grained
## control over performance features like which `zlib*` implementation to use.
## No C toolchain is involved.
max-control = [
    "parallel",
    "pack-cache-lru-static",
    "pack-cache-lru-dynamic",
]

## Activate features that maximize performance, like usage of threads, `and access to caching in object databases, skipping the ones known to cause compile failures
## on some platforms.
## Note that this configuration still uses a pure Rust zlib implementation which isn't the fastest compared to its C-alternatives.
## No C toolchain is involved.
max-performance-safe = [
    "max-control",
    "parallel-walkdir"
]

## If set, walkdir iterators will be multi-threaded which affects the listing of loose objects and references.
## Note, however, that this will use `rayon` under the hood and spawn threads for each traversal to avoid a global rayon thread pool.
## Thus this option is more interesting to one-off client applications, rather than the server.
parallel-walkdir = ["gix-features/fs-walkdir-parallel"]

## The tempfile registry uses a better implementation of a thread-safe hashmap, relying on an external crate.
## This may be useful when tempfiles are created and accessed in a massively parallel fashion and you know that this is indeed faster than
## the simpler implementation that is the default.
hp-tempfile-registry = ["gix-tempfile/hp-hashmap"]

## Make certain data structure threadsafe (or `Sync`) to facilitate multithreading. Further, many algorithms will now use multiple threads by default.
##
## If unset, most of `gix` can only be used in a single thread as data structures won't be `Send` anymore.
parallel = ["gix-features/parallel"]

## Provide a fixed-size allocation-free LRU cache for packs. It's useful if caching is desired while keeping the memory footprint
## for the LRU-cache itself low.
pack-cache-lru-static = ["gix-pack/pack-cache-lru-static"]

## Provide a hash-map based LRU cache whose eviction is based a memory cap calculated from object data.
pack-cache-lru-dynamic = ["gix-pack/pack-cache-lru-dynamic"]

## Activate other features that maximize performance, like usage of threads, `zlib-ng` and access to caching in object databases.
## Note that some platforms might suffer from compile failures, which is when `max-performance-safe` should be used.
max-performance = [ "max-performance-safe", "zlib-ng", "fast-sha1" ]

## If enabled, use assembly versions of sha1 on supported platforms.
## This might cause compile failures as well which is why it can be turned off separately.
fast-sha1 = [ "gix-features/fast-sha1" ]

## Use the C-based zlib-ng backend, which can compress and decompress significantly faster.
## Note that this will cause duplicate symbol errors if the application also depends on `zlib` - use `zlib-ng-compat` in that case.
zlib-ng = ["gix-features/zlib-ng"]

## Use zlib-ng via its zlib-compat API. Useful if you already need zlib for C
## code elsewhere in your dependencies. Otherwise, use `zlib-ng`.
zlib-ng-compat = ["gix-features/zlib-ng-compat"]

## Use a slower C-based backend which can compress and decompress significantly faster than the rust version.
## Unlike `zlib-ng-compat`, this allows using dynamic linking with system `zlib` libraries and doesn't require cmake.
zlib-stock = ["gix-features/zlib-stock"]

#! #### Other
#!
#! The catch-all of feature toggles.

## When parsing objects by default errors will only be available on the granularity of success or failure, and with the above flag enabled
## details information about the error location will be collected.
## Use it in applications which expect broken or invalid objects or for debugging purposes.
## Incorrectly formatted objects aren't very common otherwise.
verbose-object-parsing-errors = ["gix-object/verbose-object-parsing-errors"]

## Data structures implement `serde::Serialize` and `serde::Deserialize`.
serde = [   "dep:serde",
    "gix-pack/serde",
    "gix-object/serde",
    "gix-protocol?/serde",
    "gix-transport?/serde",
    "gix-ref/serde",
    "gix-odb/serde",
    "gix-index?/serde",
    "gix-mailmap?/serde",
    "gix-url/serde",
    "gix-attributes?/serde",
    "gix-ignore?/serde",
    "gix-revision/serde",
    "gix-worktree?/serde",
    "gix-commitgraph/serde",
    "gix-credentials?/serde"]

## Re-export the progress tree root which allows to obtain progress from various functions which take `impl gix::Progress`.
## Applications which want to display progress will probably need this implementation.
progress-tree = ["prodash/progress-tree"]

## Print debugging information about usage of object database caches, useful for tuning cache sizes.
cache-efficiency-debug = ["gix-features/cache-efficiency-debug"]



[dependencies]
gix-macros = { version = "^0.1.3", path = "../gix-macros" }
gix-utils = { version = "^0.1.9", path = "../gix-utils" }
gix-fs = { version = "^0.10.0", path = "../gix-fs" }
gix-ref = { version = "^0.41.0", path = "../gix-ref" }
gix-discover = { version = "^0.29.0", path = "../gix-discover" }
gix-tempfile = { version = "^13.0.0", path = "../gix-tempfile", default-features = false }
gix-lock = { version = "^13.0.0", path = "../gix-lock" }
gix-validate = { version = "^0.8.3", path = "../gix-validate" }
gix-sec = { version = "^0.10.4", path = "../gix-sec" }
gix-date = { version = "^0.8.3", path = "../gix-date" }
gix-refspec = { version = "^0.22.0", path = "../gix-refspec" }
gix-filter = { version = "^0.9.0", path = "../gix-filter", optional = true }

gix-config = { version = "^0.34.0", path = "../gix-config" }
gix-odb = { version = "^0.57.0", path = "../gix-odb" }
gix-hash = { version = "^0.14.1", path = "../gix-hash" }
gix-object = { version = "^0.41.0", path = "../gix-object" }
gix-actor = { version = "^0.30.0", path = "../gix-actor" }
gix-pack = { version = "^0.47.0", path = "../gix-pack", default-features = false, features = ["object-cache-dynamic"] }
gix-revision = { version = "^0.26.0", path = "../gix-revision", default-features = false }
gix-revwalk = { version = "^0.12.0", path = "../gix-revwalk" }
gix-negotiate = { version = "^0.12.0", path = "../gix-negotiate", optional = true }

gix-path = { version = "^0.10.4", path = "../gix-path" }
gix-url = { version = "^0.27.0", path = "../gix-url" }
gix-traverse = { version = "^0.37.0", path = "../gix-traverse" }
gix-diff = { version = "^0.40.0", path = "../gix-diff", default-features = false }
gix-mailmap = { version = "^0.22.0", path = "../gix-mailmap", optional = true }
gix-features = { version = "^0.38.0", path = "../gix-features", features = ["progress", "once_cell"] }
gix-trace = { version = "^0.1.7", path = "../gix-trace" }

gix-glob = { version = "^0.16.0", path = "../gix-glob" }
gix-credentials = { version = "^0.24.0", path = "../gix-credentials", optional = true }
gix-prompt = { version = "^0.8.2", path = "../gix-prompt", optional = true }
gix-index = { version = "^0.29.0", path = "../gix-index", optional = true }
gix-attributes = { version = "^0.22.0", path = "../gix-attributes", optional = true }
gix-ignore = { version = "^0.11.0", path = "../gix-ignore", optional = true }
gix-worktree = { version = "^0.30.0", path = "../gix-worktree", optional = true, default-features = false }
gix-worktree-state = { version = "^0.7.0", path = "../gix-worktree-state", optional = true }
gix-hashtable = { version = "^0.5.1", path = "../gix-hashtable" }
gix-commitgraph = { version = "^0.24.0", path = "../gix-commitgraph" }
gix-pathspec = { version = "^0.6.0", path = "../gix-pathspec", optional = true }
gix-submodule = { version = "^0.8.0", path = "../gix-submodule", optional = true }
gix-status = { version = "^0.5.0", path = "../gix-status", optional = true }
gix-command = { version = "^0.3.3", path = "../gix-command", optional = true }

gix-worktree-stream = { version = "^0.9.0", path = "../gix-worktree-stream", optional = true }
gix-archive = { version = "^0.9.0", path = "../gix-archive", default-features = false, optional = true }

# For communication with remotes
gix-protocol = { version = "^0.44.0", path = "../gix-protocol", optional = true }
gix-transport = { version = "^0.41.0", path = "../gix-transport", optional = true }

# Just to get the progress-tree feature
prodash = { workspace = true, optional = true, features = ["progress-tree"] }
once_cell = "1.14.0"
signal-hook = { version = "0.3.9", default-features = false, optional = true }
thiserror = "1.0.26"
serde = { version = "1.0.114", optional = true, default-features = false, features = ["derive"]}
smallvec = "1.9.0"
async-std = { version = "1.12.0", optional = true }

# Must match the one in `gix-transport`.
curl-for-configuration-only = { package = "curl", version = "0.4", optional = true }

## For use in rev-parse, which provides searching commits by running a regex on their message.
##
## If disabled, the text will be search verbatim in any portion of the commit message, similar to
## how a simple unanchored regex of only 'normal' characters would work.
regex = { version = "1.6.0", optional = true, default-features = false, features = ["std"] }

# For internal use to allow pure-Rust builds without openssl.
reqwest-for-configuration-only = { package = "reqwest", version = "0.11.13", default-features = false, optional = true }

# for `interrupt` module
parking_lot = "0.12.1"

document-features = { version = "0.2.0", optional = true }

[dev-dependencies]
gix-testtools = { path = "../tests/tools" }
is_ci = "1.1.1"
anyhow = "1"
walkdir = "2.3.2"
serial_test = { version = "2.0.0", default-features = false }
async-std = { version = "1.12.0", features = ["attributes"] }

[package.metadata.docs.rs]
features = ["document-features", "max-performance", "blocking-network-client", "blocking-http-transport-curl", "serde"]