Skip to content

Commit 00f66c8

Browse files
committed
Update README
1 parent 809b091 commit 00f66c8

File tree

1 file changed

+17
-18
lines changed

1 file changed

+17
-18
lines changed

README.md

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ cargo install gitoxide --no-default-features --features lean
160160
* **async as opt-in**
161161
* Making certain capabilities available through `async` APIs allows for abortable operations, which
162162
may be interesting for interactive user interfaces. Thus it is something worth considering, but only
163-
behind a feature flag and once the need transpire.
163+
behind a feature flag and once the need transpires.
164164
* Ideally many operations powered by implementors of `std::io::{Read, Write}` and `std::iter::Iterator`,
165165
which makes unblocking them trivial using the fantastic `blocking` crate. Only when these are used internally,
166166
providing a separate async version of these operations can be beneficial to make them abortable.
@@ -178,8 +178,6 @@ cargo install gitoxide --no-default-features --features lean
178178

179179
## Roadmap to Future
180180

181-
As you can see from the version numbers, this project dispenses major version generously.
182-
183181
### Roadmap to 1.0
184182

185183
Provide a CLI to for the most basic user journey:
@@ -199,31 +197,31 @@ This guide documents which features are available for each of the crates provide
199197

200198
The top-level command-line interface.
201199

202-
* **fast** _(default)_
200+
* **fast**
203201
* Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions
204202
as well as fast, hardware accelerated hashing.
205203
* If disabled, the binary will be visibly smaller.
206204
* _(mutually exclusive)_
207-
* **pretty-cli** _(default)_
205+
* **pretty-cli**
208206
* Use `clap` + `structopt` to build the prettiest, best documented and most user-friendly CLI at the expense of file size.
209207
* provides a terminal user interface for detailed and exhaustive progress.
210208
* provides a line renderer for log-like progress
211209
* **lean-cli**
212210
* Use `argh` to produce a usable binary with decent documentation that is smallest in size, usually 300kb less than `pretty-cli`.
213-
* If `pretty-cli` is enabled as well, `small-cli` will take precedence, and you pay for building unnecessary dependencies.
211+
* If `pretty-cli` is enabled as well, `lean-cli` will take precedence, and you pay for building unnecessary dependencies.
214212
* provides a line renderer for log-like progress
215213
* **prodash-line-renderer-crossterm** or **prodash-line-renderer-termion** _(mutually exclusive)_
216214
* The `--verbose` flag will be powered by an interactive progress mechanism that doubles as log as well as interactive progress
217215
that appears after a short duration.
218216

219217
There are **convenience features**, which combine common choices of the above into one name
220218

221-
* **max** = *pretty-cli* + *fast* + *prodash/tui-renderer-crossterm*
219+
* **max** = *pretty-cli* + *fast* + *prodash-tui-renderer-crossterm*
222220
* _default_, for unix and windows
223-
* **max-termion** = *pretty-cli* + *fast* + *prodash/tui-renderer-termion*
221+
* **max-termion** = *pretty-cli* + *fast* + *prodash-tui-renderer-termion*
224222
* for unix only, faster compile times, a little smaller
225223
* **lean** = *lean-cli* + *fast* + *prodash-line-renderer-crossterm*
226-
* for unix and windows
224+
* for unix and windows, significantly smaller than _max_, but without `--progress` terminal user interface.
227225
* **lean-termion** = *lean-cli* + *fast* + *prodash-line-renderer-termion*
228226
* for unix only, faster compile times, a little smaller
229227
* **light** = *lean-cli* + *fast*
@@ -237,21 +235,19 @@ A crate to help controlling which capabilities are available from the top-level
237235
`gitoxide` crate that uses `git-features`.
238236
All feature toggles are additive.
239237

240-
* **parallel** _(optional)_
238+
* **parallel**
241239
* Use scoped threads and channels to parallelize common workloads on multiple objects. If enabled, it is used everywhere
242240
where it makes sense.
243241
* As caches are likely to be used and instantiated per thread, more memory will be used on top of the costs for threads.
244242
* **fast-sha1**
245243
* a multi-crate implementation that can use hardware acceleration, thus bearing the potential for up to 2Gb/s throughput on
246-
CPUs that support it, like AMD Ryzen.
244+
CPUs that support it, like AMD Ryzen or Intel Core i3.
247245
* **progress-log**
248-
* Implement the `Progress` trait using the `log` crate. Throttle progress output to one every 0.5 seconds unless messsages
246+
* Implement the `Progress` trait using the `log` crate. Throttle progress output to one every 0.5 seconds unless messages
249247
are sent manually.
250248
* **progress-prodash**
251249
* Implement the `Progress` trait for the tree data structures provided by `prodash`, which enables using a terminal user
252250
interface for progress.
253-
* This is by far the most expensive progress option, as it pulls in an `async` TUI along with supporting infrastructure,
254-
which is kept minimal but has quite a footprint nonetheless.
255251

256252
### Serialization Support
257253

@@ -289,13 +285,13 @@ All feature toggles are additive.
289285

290286
Both terms are coming from the `git` implementation itself, even though it won't necessarily point out which commands are plumbing and which
291287
are porcelain.
292-
The term *plumbing* refers to lower-level, more rarely used commands that complement porcelain by being invoked by it or for special use
288+
The term *plumbing* refers to lower-level, more rarely used commands that complement porcelain by being invoked by it or for certain use
293289
cases.
294290
The term *porcelain* refers to those with a decent user experience, they are primarily intended for use by humans.
295291

296292
In any case, both types of programs must self-document their capabilities using through the `--help` flag.
297293

298-
From there, we can derive a few rules to try to adhere to:
294+
From there, we can derive a few rules to try adhere to:
299295

300296
### Plumbing
301297

@@ -311,7 +307,8 @@ From there, we can derive a few rules to try to adhere to:
311307

312308
## Maintenance Guide
313309

314-
Utilities to aid in keeping the project fresh and in sync can be found in the `Maintenance` section of the `makefile`.
310+
Utilities to aid in keeping the project fresh and in sync can be found in the `Maintenance` section of the `makefile`. Run `make` to
311+
get an overview.
315312

316313
### Creating a release
317314

@@ -363,4 +360,6 @@ Thus one has to post-process the file by reducing its size by one using `truncat
363360

364361
* Originally I was really fascinated by [this problem](https://github.com/gitpython-developers/GitPython/issues/765#issuecomment-396072153)
365362
and believe that with `gitoxide` it will be possible to provide the fastest solution for it.
366-
363+
* I have been absolutely blown away by `git` from the first time I experienced git more than 13 years ago, and
364+
tried to implement it in [various shapes](https://github.com/gitpython-developers/GitPython/pull/1028) and [forms](https://github.com/byron/gogit)
365+
multiple [times](https://github.com/Byron/gitplusplus). Now with Rust I finally feel to have found the right tool for the job!

0 commit comments

Comments
 (0)