Copyedit a few top-level Markdown files

README.md

@@ -177,17 +177,19 @@ on your needs, for _Linux_, _MacOS_ and _Windows_.
 
 [releases]: https://github.com/GitoxideLabs/gitoxide/releases
 
-### Download from Arch-Repository
+### Download from Arch Linux repository
 
 For Arch Linux you can download `gitoxide` from `community` repository:
-```
+
+```sh
 pacman -S gitoxide
 ```
 
 ### Download from Exherbo Linux Rust repository
 
 For Exherbo Linux you can download `gitoxide` from the [Rust](https://gitlab.exherbo.org/exherbo/rust/-/tree/master/packages/dev-scm/gitoxide) repository:
-```
+
+```sh
 cave resolve -x repository/rust
 cave resolve -x gitoxide
 ```
@@ -203,7 +205,7 @@ the latest stable one will work as well.
 There are various build configurations, all of them are [documented here](https://docs.rs/crate/gitoxide/latest). The documentation should also be useful
 for packagers who need to tune external dependencies.
 
-```
+```sh
 # A way to install `gitoxide` with just Rust and a C compiler installed.
 # If there are problems with SSL certificates during clones, try to omit `--locked`.
 cargo install gitoxide --locked --no-default-features --features max-pure
@@ -220,19 +222,25 @@ cargo install gitoxide --locked --no-default-features --features lean
 The following installs the latest unpublished `max` release directly from git:
 
 ```sh
-cargo install --git https://github.com/GitoxideLabs/gitoxide  gitoxide
+cargo install --git https://github.com/GitoxideLabs/gitoxide gitoxide
 ```
 
 #### How to deal with build failures
 
-On some platforms, installation may fail due to lack of tools required by `C` toolchains. This can generally be avoided by installation
-with `cargo install gitoxide --no-default-features --features max-pure`.
+On some platforms, installation may fail due to lack of tools required by *C* toolchains. This can generally be avoided by installation with:
+
+```sh
+cargo install gitoxide --no-default-features --features max-pure
+```
 
 What follows is a list of known failures.
 
-- On Fedora, `perl` needs to be installed for `OpenSSL` to build properly. This can be done with the following command:
-  `dnf install perl` (see [this issue](https://github.com/GitoxideLabs/gitoxide/issues/592)).
--
+- On Fedora, `perl` needs to be installed for `OpenSSL` to build properly. This can be done with the following command (see [issue #592](https://github.com/GitoxideLabs/gitoxide/issues/592)):
+
+  ```sh
+  dnf install perl
+  ```
+
 ### Using Docker
 
 Some CI/CD pipelines leverage repository cloning. Below is a copy-paste-able example to build docker images for such workflows.

SHORTCOMINGS.md

@@ -1,37 +1,39 @@
-This file is for tracking features that are less well implemented or less powerful than their `git` counterparts for one reason or another.
+# Shortcomings
 
-#### `gix`
+This file is for tracking features that are less well implemented or less powerful than their Git counterparts for one reason or another.
 
 ### gix-index
 
-* The `link` extension can be read, but won't be written. This effectively disables the use of a split index once a mutating operation is run on it with `gitixode`.
+* The `link` extension can be read, but won't be written. This effectively disables the use of a split index once a mutating operation is run on it with `gitoxide`.
 
 ### gix-protocol
-* **fetches using protocol V1 and stateful connections, i.e. ssh, git, file, may hang**
+
+* **Fetches using protocol V1 and stateful connections, i.e. ssh, git, file, may hang**
     * This can be fixed by making response parsing.
     * Note that this does not affect cloning, which works fine.
 
-### `gix-pack`
+### gix-pack
+
 * **Packfiles use memory maps**
     * Even though they are comfortable to use and fast, they squelch IO errors.
-    * _potential remedy_: We could generalize the Pack to make it possible to work on in-memory buffers directly. That way, one
-      would initialize a Pack by reading the whole file into memory, thus not squelching IO errors at the expense of latency as well
+    * _Potential remedy_: We could generalize the `Pack` to make it possible to work on in-memory buffers directly. That way, one
+      would initialize a `Pack` by reading the whole file into memory, thus not squelching IO errors at the expense of latency as well
       as memory efficiency.
-* **Packfiles cannot load files bigger than 2^31 or 2^32 on 32 bit systems**
+* **Packfiles cannot load files bigger than 2^31 or 2^32 on 32-bit systems**
     * As these systems cannot address more memory than that.
-    * _potential remedy_: implement a sliding window to map and unmap portions of the file as needed.
-        * However, those who need to access big packs on these systems would rather resort to `git` itself, allowing
+    * _Potential remedy_: implement a sliding window to map and unmap portions of the file as needed.
+        * However, those who need to access big packs on these systems would rather resort to Git itself, allowing
           our implementation to be simpler and potentially more performant.
-* **Objects larger than 32 bits cannot be loaded on 32 bit systems**
-    * in-memory representations objects cannot handle objects greater than the amount of addressable memory.
-    * This will not affect git LFS though.
+* **Objects larger than 32 bits cannot be loaded on 32-bit systems**
+    * In-memory representations objects cannot handle objects greater than the amount of addressable memory.
+    * This will not affect Git LFS though.
 
-### `gix`
+### gix
 
-* object replacements are read once upon opening the repository from their refs and changes to these won't be picked up.
+* Object replacements are read once upon opening the repository from their refs and changes to these won't be picked up.
 
-### `gix-url`
+### gix-url
 
-* **gix-url** _might_ be more restrictive than what git allows as for the most part, it uses a browser grade URL parser.
-    * Thus far there is no proof for this, and as _potential remedy_ we could certainly re-implement exactly what git does
+* **gix-url** _might_ be more restrictive than what Git allows as for the most part, it uses a browser grade URL parser.
+    * Thus far there is no proof for this, and as _potential remedy_ we could certainly re-implement exactly what Git does
       to handle its URLs.

STABILITY.md

@@ -14,21 +14,22 @@ Please note that this guide isn't stable itself and may be adjusted to fit chang
 - _workspace crate_
   - A crate which is a member of this workspace and hence is stored in this repository
 - _breaking change_
-  - A change in code that requires a `dependent crate` to adjust their code to fix compile errors.
+  - A change in code that requires a _dependent crate_ to adjust their code to fix compile errors.
 - _release_
   - A new version of a crate is published to crates.io
 - _development version_
   - A crate version whose _major_ version is 0.
 - _release version_
   - A crate version whose _major_ version is 1 or higher.
 - _initial development phase_ (IDP)
-  - The phase of development leading up to producing a crate with a major version of 1 or greater, as per `semver`.
+  - The phase of development leading up to producing a crate with a major version of 1 or greater, as per [semver].
   - Not to be confused with the term _pre-release_, which is used to indicate any release version prior to an actual release, like `1.1.0-beta.1`.
 
 ## Tiers
 
 The project uses three stability tiers for all of its crates, and all crates use [semver] for their version numbers.
-Tiers differ primarily in the time between breaking changes, which always have to be announced with `PRs` as per
+
+Tiers differ primarily in the time between breaking changes, which always have to be announced with *PRs* as per
 our [collaboration guide].
 
 The following schematic helps to visualize what follows.
@@ -108,10 +109,10 @@ If there are additional breaking changes without a release, these push back the
 ### Tier 1: released apps and application crates
 
 Released apps and application crates are marked with major version number 1 or above, like `2.3.0+21.06` and live in tier 1 _(->ST1)_,
-with the build identifiers for year (`21`) and month `06` appended, based on the actual release year and month.
+with the build identifiers for year (`21`) and month (`06`) appended, based on the actual release year and month.
 
 Breaking changes are collected and may be released no more often than every 6 months by incrementing the major version number. If there are additional breaking changes,
-these push bac the release date so that they can be tested at least for 3 months. For example, a breaking change happens in January 01, and another breaking change in February 15.
+these push back the release date so that they can be tested at least for 3 months. For example, a breaking change happens in January 01, and another breaking change in February 15.
 The earliest release date is July 1st. Had the second breaking change happened in April 01, the release date would have to be pushed to August 1st.
 
 Intermediate pre-releases may be created at most every 4 weeks by appending `-alpha.X` where `X` is the sequential release number. These should help testing

tasks.md

@@ -1,21 +1,23 @@
+# Tasks
+
 ## Tracking issues
 
-* [repository clone](https://github.com/GitoxideLabs/gitoxide/issues/303)
-* [repository FSCK](https://github.com/GitoxideLabs/gitoxide/issues/304)
+* [Repository clone](https://github.com/GitoxideLabs/gitoxide/issues/303)
+* [Repository FSCK](https://github.com/GitoxideLabs/gitoxide/issues/304)
 * [Show changes in various forms](https://github.com/GitoxideLabs/gitoxide/issues/305)
 * [Client side push (client to server)](https://github.com/GitoxideLabs/gitoxide/issues/306)
 * [Server fetch/pull (server to client)](https://github.com/GitoxideLabs/gitoxide/issues/307)
 
-## Smaller Tasks
+## Smaller tasks
 
 …to not forget. Might get reorganized.
 
 ### gix organize
 
-* [ ] Add journey test to cover case with non-bare repository. Try to only read `non-bare` git config files and see the journey test fail.
+* [ ] Add journey test to cover case with non-bare repository. Try to only read *non-bare* git config files and see the journey test fail.
 
 ### gix cat
 
-* A program to cat objects and pretty-print them, similar to git cat-file. Useful to get a feel for
-  'locate(…)' performance and stress test it a little.
-* Be sure to escape terminal escape codes
+* A program to cat objects and pretty-print them, similar to `git cat-file`. Useful to get a feel for
+  `locate(…)` performance and stress test it a little.
+* Be sure to escape terminal escape codes.