ci: don't use ninja on macOS

Ninja is not installed by default on the macOS machines; stop trying to
use it.  Instead use `make -j` which should be roughly equivalent in
performance but supported everywhere.

midx: Fix a bug in `git_midx_needs_refresh()`

clone: set refs/remotes/origin/HEAD when branch is specified

When a branch is specified to check out in clone, update the remote
tracking `HEAD` to point to it.  This mimics git's behavior, when
`git clone -b <name>` is used.

Use `p_pwrite`/`p_pread` consistently throughout the codebase

README: instructions for using libgit2 without compiling

Cope with empty default branch

This change stops using the seek+read/write combo to perform I/O with an
offset, since this is faster by one system call (and also more atomic
and therefore safer).

The very last check in the freshness check for the midx was wrong ><
This was also because this function was not tested.

github-actions: Also rename the main branch here

This should fix the CI.

The init.defaultbranch option may be set, but empty.  In this case, we
should ignore it instead of trying to set our default branch to
`refs/heads/`.

If a symbolic reference points to something invalid, then do not try to
update it.

When HEAD points to a nonexistent or invalid branch - for example, to
`refs/heads/` - the fetch should be permitted to continue, but we should
not use it when creating the `for merge` option in the FETCH_HEAD file.

(This emulates git's behavior.)

blob: fix name of `GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD`

Add documentation for git_blob_filter_options.version

Adds info about initializing options with git_blob_filter_options_init

`GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD` is misspelled, it should be
`GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD`, and it would be if it were not
for the MacBook Pro keyboard and my inattentiveness.

The `git_blob_filter_options_init` function should be included, to allow
callers in FFI environments to let us initialize an options structure
for them.

Build with NO_MMAP

zlib: Add support for building with Chromium's zlib implementation

Removes doc comment on `git_blob_filter_options.version`, moves
information to `git_blob_filter_options` doc comment to remain
consistent with other options structures' documentation.

`git_blob_filter_options_init` still needed; should be added in another
commit/PR (it's out of the scope of this PR, #5759), update this
documentation again.

Now `USE_BUNDLED_ZLIB` can be set to the string `Chromium` to enable the
Chromium implementation of zlib.

Resolves #5756

    * Use pread/pwrite to avoid updating position in file descriptor
    * Emulate missing pread/pwrite on win32 using overlapped file IO

    * Emulated mmap based write without pagefault handling is not
    possible since IO happens outside of call to mmap and data is
    written to mapped memory
    * Potential emulation using userfaultfd() might be possible

This change builds libgit2 using Chromium's zlib implementation by
invoking cmake with `-DUSE_BUNDLED_ZLIB=ON -DUSE_CHROMIUM_ZLIB=ON`,
which is ~10% faster than the bundled zlib for the core::zstream suite.

This version of zlib has some optimizations:

a) Decompression (Intel+ARM): inflate_fast, adler32, crc32, etc.
b) Compression (Intel): fill_window, longest_match, hash function, etc.

Due to the introduction of SIMD optimizations, and to get the maximum
performance out of this fork of zlib, this requires an x86_64 processor
with SSE4.2 and CLMUL (anything Westmere or later, ~2010). The Chromium
zlib implementation also supports ARM with NEON, but it has not been
enabled in this patch.

Performance
===========

TL;DR: Running just `./libgit2_clar -score::zstream` 100 times in a loop
took 0:56.30 before and 0:50.67 after (~10% reduction!).

The bundled and system zlib implementations on an Ubuntu Focal system
perform relatively similar (the bundled one is marginally better due to
the compiler being able to inline some functions), so only the bundled
and Chromium zlibs were compared.

For a more balanced comparison (to ensure that nothing regressed
overall), `libgit2_clar` under `perf` was also run, and the zlib-related
functions were compared.

Bundled
-------

```shell
cmake \
  -DUSE_BUNDLED_ZLIB=ON \
  -DUSE_CHROMIUM_ZLIB=OFF \
  -DCMAKE_BUILD_TYPE="RelWithDebInfo" \
  -DCMAKE_C_FLAGS="-fPIC -fno-omit-frame-pointer" \
  -GNinja \
  ..
ninja
perf record --call-graph=dwarf ./libgit2_clar
perf report --children
```

```
Samples: 87K of event 'cycles', Event count (approx.): 75923450603
  Children      Self  Command       Shared Objec  Symbol
+    4.14%     0.01%  libgit2_clar  libgit2_clar  [.] git_zstream_get_output_chunk
+    2.91%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_get_output
+    0.69%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_get_output (inlined)
     0.17%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_init
     0.02%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_reset
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_eos
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_done
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_free (inlined)

Samples: 87K of event 'cycles', Event count (approx.): 75923450603
  Children      Self  Command       Shared Objec  Symbol
+    3.12%     0.01%  libgit2_clar  libgit2_clar  [.] deflate
+    2.65%     1.48%  libgit2_clar  libgit2_clar  [.] deflate_slow
+    1.60%     0.55%  libgit2_clar  libgit2_clar  [.] inflate
+    0.53%     0.00%  libgit2_clar  libgit2_clar  [.] write_deflate
     0.49%     0.36%  libgit2_clar  libgit2_clar  [.] inflate_fast
     0.46%     0.02%  libgit2_clar  libgit2_clar  [.] deflate_fast
     0.19%     0.19%  libgit2_clar  libgit2_clar  [.] inflate_table
     0.16%     0.01%  libgit2_clar  libgit2_clar  [.] inflateInit_
     0.15%     0.00%  libgit2_clar  libgit2_clar  [.] inflateInit2_ (inlined)
     0.10%     0.00%  libgit2_clar  libgit2_clar  [.] deflateInit_
     0.10%     0.00%  libgit2_clar  libgit2_clar  [.] deflateInit2_
     0.03%     0.00%  libgit2_clar  libgit2_clar  [.] deflateReset (inlined)
     0.02%     0.00%  libgit2_clar  libgit2_clar  [.] deflateReset
     0.02%     0.00%  libgit2_clar  libgit2_clar  [.] inflateEnd
     0.02%     0.00%  libgit2_clar  libgit2_clar  [.] deflateEnd
     0.01%     0.00%  libgit2_clar  libgit2_clar  [.] deflateResetKeep
     0.01%     0.01%  libgit2_clar  libgit2_clar  [.] inflateReset2
     0.01%     0.00%  libgit2_clar  libgit2_clar  [.] deflateReset (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] inflateStateCheck (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] inflateReset (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] inflateStateCheck (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] deflateStateCheck (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] inflateResetKeep (inlined)
```

Chromium
--------

```shell
cmake \
  -DUSE_BUNDLED_ZLIB=ON \
  -DUSE_CHROMIUM_ZLIB=ON \
  -DCMAKE_BUILD_TYPE="RelWithDebInfo" \
  -DCMAKE_C_FLAGS="-fPIC -fno-omit-frame-pointer" \
  -GNinja \
  ..
ninja
perf record --call-graph=dwarf ./libgit2_clar
perf report --children
```

```
Samples: 97K of event 'cycles', Event count (approx.): 80862210917
  Children      Self  Command       Shared Objec  Symbol
+    3.31%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_get_output_chunk
+    2.27%     0.01%  libgit2_clar  libgit2_clar  [.] git_zstream_get_output
+    0.55%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_get_output (inlined)
     0.18%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_init
     0.02%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_reset
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_free (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_done
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] git_zstream_free

Samples: 97K of event 'cycles', Event count (approx.): 80862210917
  Children      Self  Command       Shared Objec  Symbol
+    2.55%     0.01%  libgit2_clar  libgit2_clar  [.] deflate
+    2.25%     1.41%  libgit2_clar  libgit2_clar  [.] deflate_slow
+    1.10%     0.52%  libgit2_clar  libgit2_clar  [.] inflate
     0.36%     0.00%  libgit2_clar  libgit2_clar  [.] write_deflate
     0.30%     0.03%  libgit2_clar  libgit2_clar  [.] deflate_fast
     0.28%     0.15%  libgit2_clar  libgit2_clar  [.] inflate_fast_chunk_
     0.19%     0.19%  libgit2_clar  libgit2_clar  [.] inflate_table
     0.17%     0.01%  libgit2_clar  libgit2_clar  [.] inflateInit_
     0.16%     0.00%  libgit2_clar  libgit2_clar  [.] inflateInit2_ (inlined)
     0.15%     0.00%  libgit2_clar  libgit2_clar  [.] deflateInit_
     0.15%     0.00%  libgit2_clar  libgit2_clar  [.] deflateInit2_
     0.11%     0.01%  libgit2_clar  libgit2_clar  [.] adler32_z
     0.09%     0.09%  libgit2_clar  libgit2_clar  [.] adler32_simd_
     0.05%     0.00%  libgit2_clar  libgit2_clar  [.] deflateReset (inlined)
     0.05%     0.00%  libgit2_clar  libgit2_clar  [.] deflate_read_buf
     0.03%     0.00%  libgit2_clar  libgit2_clar  [.] inflateEnd
     0.02%     0.00%  libgit2_clar  libgit2_clar  [.] deflateReset
     0.01%     0.00%  libgit2_clar  libgit2_clar  [.] deflateEnd
     0.01%     0.01%  libgit2_clar  libgit2_clar  [.] inflateReset2
     0.01%     0.00%  libgit2_clar  libgit2_clar  [.] inflateReset (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] adler32
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] inflateResetKeep (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] deflateResetKeep
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] inflateStateCheck (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] inflateStateCheck (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] inflateStateCheck (inlined)
     0.00%     0.00%  libgit2_clar  libgit2_clar  [.] deflateStateCheck (inlined)
```

Handle ipv6 addresses

Add support for additional SSH hostkey types.

IPv6 addresses should be used identically internally; we should not
denote them with brackets in one operating system and without them in
another.

Fix the `-DENABLE_WERROR=ON` build for gcc 10.2