The experimental function signature is only available when
`GIT_EXPERIMENTAL_SHA256` is enabled.

libgit2 can be built with optional, experimental sha256 support. This
allows consumers to begin testing and providing feedback for our sha256
support while we continue to develop it, and allows us to make API
breaking changes while we iterate on a final sha256 implementation.

The results will be `git2-experimental.dll` and installed as
`git2-experimental.h` to avoid confusion with a production libgit2.

Teach the loose object database how to cope with SHA256 objects.

Move the arguments to `git_odb_loose` into an options structure.

`git_oid`s now have a type, and we require the oid type when creating
the object id from creation functions.

In preparation for SHA256 support, `GIT_OID_RAWSZ` and `GIT_OID_HEXSZ`
need to indicate that they're the size of _SHA1_ OIDs.

Introduce `git_fs_path`, which operates on generic filesystem paths.
`git_path` will be kept for only git-specific path functionality (for
example, checking for `.git` in a path).

libgit2 has two distinct requirements that were previously solved by
`git_buf`.  We require:

1. A general purpose string class that provides a number of utility APIs
   for manipulating data (eg, concatenating, truncating, etc).
2. A structure that we can use to return strings to callers that they
   can take ownership of.

By using a single class (`git_buf`) for both of these purposes, we have
confused the API to the point that refactorings are difficult and
reasoning about correctness is also difficult.

Move the utility class `git_buf` to be called `git_str`: this represents
its general purpose, as an internal string buffer class.  The name also
is an homage to Junio Hamano ("gitstr").

The public API remains `git_buf`, and has a much smaller footprint.  It
is generally only used as an "out" param with strict requirements that
follow the documentation.  (Exceptions exist for some legacy APIs to
avoid breaking callers unnecessarily.)

Utility functions exist to convert a user-specified `git_buf` to a
`git_str` so that we can call internal functions, then converting it
back again.

This change:

* Initializes a few variables that were being read before being
  initialized.
* Includes https://github.com/madler/zlib/pull/393. As such,
  it only works reliably with `-DUSE_BUNDLED_ZLIB=ON`.

Instead of using a signed type (`off_t`) use a new `git_object_size_t`
for the sizes of objects.

Our file utils functions all have a "futils" prefix, e.g.
`git_futils_touch`. One would thus naturally guess that their
definitions and implementation would live in files "futils.h" and
"futils.c", respectively, but in fact they live in "fileops.h".

Rename the files to match expectations.

Quiet down a warning from MSVC about how we're potentially losing data.
This is safe since we've explicitly tested that it's positive and less
than SIZE_MAX.

Move to the `git_error` name in the internal API for error-related
functions.

We use the term "invalid" to refer to bad or malformed data, eg
`GIT_REF_INVALID` and `GIT_EINVALIDSPEC`.  Since we're changing the
names of the `git_object_t`s in this release, update it to be
`GIT_OBJECT_INVALID` instead of `BAD`.

If the routine exits with error before stream or hash_ctx is initialized, the
program will segfault when trying to free them.

Use the new object_type enumeration names within the codebase.

Return an error to the caller when we can't create an object header for
some reason (printf failure) instead of simply asserting.

`MAX_HEADER_LEN` is a more descriptive constant name.

When checking to see if a file has zlib deflate content, make sure that
we actually have read at least two bytes before examining the array.

Support `read_header` for "packlike loose objects", which were a
temporarily and uncommonly used format loose object format that encodes
the header before the zlib deflate data.

This will never actually be seen in the wild, but add support for it for
completeness and (more importantly) because our corpus of test data has
objects in this format, so it's easier to support it than to try to
special case it.

Make `read_header` use the common zstream implementation.
Remove the now unnecessary zlib wrapper in odb_loose.

Refactor packlike loose object reads to use `git_zstream` for
simplification.

A "packlike" loose object was a briefly lived loose object format where
the type and size were encoded in uncompressed space at the beginning of
the file, followed by the compressed object contents.  Handle these in a
streaming manner as well.

Provide a streaming loose object reader.

There are two streaming functions; one for reading, one for writing.

Disambiguate function names between `stream` and `writestream` to make
allowances for a read stream.

Check the size of objects being read from the loose odb backend and
reject those that would not fit in memory with an error message that
reflects the actual problem, instead of error'ing later with an
unintuitive error message regarding truncation or invalid hashes.

zlib will only inflate/deflate an `int`s worth of data at a time.
We need to loop through large files in order to ensure that we inflate
the entire file, not just an `int`s worth of data.  Thankfully, we
already have this loop in our `git_zstream` layer.  Handle large objects
using the `git_zstream`.

Next to including several files, our "common.h" header also declares
various macros which are then used throughout the project. As such, we
have to make sure to always include this file first in all
implementation files. Otherwise, we might encounter problems or even
silent behavioural differences due to macros or defines not being
defined as they should be. So in fact, our header and implementation
files should make sure to always include "common.h" first.

This commit does so by establishing a common include pattern. Header
files inside of "src" will now always include "common.h" as its first
other file, separated by a newline from all the other includes to make
it stand out as special. There are two cases for the implementation
files. If they do have a matching header file, they will always include
this one first, leading to "common.h" being transitively included as
first file. If they do not have a matching header file, they instead
include "common.h" as first file themselves.

This fixes the outlined problems and will become our standard practice
for header and source files inside of the "src/" from now on.

Initially, the setting has been solely used to enable the use of
`fsync()` when creating objects. Since then, the use has been extended
to also cover references and index files. As the option is not yet part
of any release, we can still correct this by renaming the option to
something more sensible, indicating not only correlation to objects.

This commit renames the option to `GIT_OPT_ENABLE_FSYNC_GITDIR`. We also
move the variable from the object to repository source code.

Rename `GIT_OPT_ENABLE_SYNCHRONIZED_OBJECT_CREATION` ->
`GIT_OPT_ENABLE_SYNCHRONOUS_OBJECT_CREATION`.