While the OpenSSL library provides all means to work safely in a
multi-threaded application, we fail to do so correctly. Quoting from
crypto_lock(3):

    OpenSSL can safely be used in multi-threaded applications provided
    that at least two callback functions are set, locking_function and
    threadid_func.

We do in fact provide the means to set up the locking function via
`git_openssl_set_locking()`, where we initialize a set of locks by using
the POSIX threads API and set the correct callback function to lock and
unlock them.

But what we do not do is setting the `threadid_func` callback. This
function is being used to correctly locate thread-local data of the
OpenSSL library and should thus return per-thread identifiers. Digging
deeper into OpenSSL's documentation, the library does provide a fallback
in case that locking function is not provided by the user. On Windows
and BeOS we should be safe, as it simply "uses the system's default
thread identifying API". On other platforms though OpenSSL will fall
back to using the address of `errno`, assuming it is thread-local.

While this assumption holds true for glibc-based systems, POSIX in fact
does not specify whether it is thread-local or not. Quoting from
errno(3p):

    It is unspecified whether errno is a macro or an identifier declared
    with external linkage.

And in fact, with musl there is at least one libc implementation which
simply declares `errno` as a simple `int` without being thread-local. On
those systems, the fallback threadid function of OpenSSL will not be
thread-safe.

Fix this by setting up our own callback for this setting. As users of
libgit2 may want to set it themselves, we obviously cannot always set
that function on initialization. But as we already set up primitives for
threading in `git_openssl_set_locking()`, this function becomes the
obvious choice where to implement the additional setup.

CONTRIBUTING: add documentation of our commit message style

Include git2/worktree.h in git2.h

I'm not sure if worktree.h was intentionally left out of git2.h. Looks like an oversight since it is in fact documented.

Getting started README improvements

Introduce a simple FAQ for common errors for people getting started with
the project.

Since we recommend `ctest -V`, it's not clear why somebody would want to
run `libgit2_clar`.  Indicate that it's helpful when running individual
tests or suites.

Provide a very simple quick start paragraph that highlights how easy it
is to get started, and points people toward common problems.

Users should not be advised to use the VS command prompt; instead, they
should let cmake find their Visual Studio installation.

Suggest that users run `ctest -V` instead of `make test` when getting
started.  `ctest -V` is superior over alternatives as:

1. Unlike `make test`, it gives output.  Users getting started with
   the library believe that it is hung.
2. `ctest -V` shows verbose output; showing suite names is helpful for
   giving users more feedback immediately.

While we try to conform to a certain commit message style, this style
has never been documented anywhere. Document it such that new
contributors do not have to go through another needless iteration of
their pull requests just to fix up commit messages.

Gather the reflog entry content tests

diff: expose the "indent heuristic" in the diff options

We default to off, but we might want to consider changing `GIT_DIFF_NORMAL` to
include it.

refcount: make refcounting conform to aliasing rules

Strict aliasing rules dictate that for most data types, you are not
allowed to cast them to another data type and then access the casted
pointers. While this works just fine for most compilers, technically we
end up in undefined behaviour when we hurt that rule.

Our current refcounting code makes heavy use of casting and thus
violates that rule. While we didn't have any problems with that code,
Travis started spitting out a lot of warnings due to a change in their
toolchain. In the refcounting case, the code is also easy to fix:
as all refcounting-statements are actually macros, we can just access
the `rc` field directly instead of casting.

There are two outliers in our code where that doesn't work. Both the
`git_diff` and `git_patch` structures have specializations for generated
and parsed diffs/patches, which directly inherit from them. Because of
that, the refcounting code is only part of the base structure and not of
the children themselves. We can help that by instead passing their base
into `GIT_REFCOUNT_INC`, though.

add test status codes legend to the 'Started' test trace

motivation: (for someone new to the tests) it's puzzling to find the odd 'S' interspersed in the test output

proposed alternative test output (extract):

$ cmake --build . && ./libgit2_clar -srepo -v
...
Loaded 340 suites:
Started (test status codes: OK='.' FAILURE='F' SKIPPED='S')

repo::config...
repo::discover..........
repo::env.
repo::getters...
repo::hashfile..
repo::head......................
repo::headtree....
repo::init.........................S
repo::message..
repo::new..
repo::open.............
repo::pathspec..........
repo::reservedname.....
repo::setters.....
repo::shallow....
repo::state.............

s/Init/Index comment tweak for test_repo_init__init_with_initial_commit

signature: distinguish +0000 and -0000 UTC offsets

Git considers '-0000' a valid offset for signature lines.  They need to
be treated as _not_ equal to a '+0000' signature offset.  Parsing a
signature line stores the offset in a signed integer which does not
distinguish between `+0` and `-0`.

This patch adds an additional flag `sign` to the `git_time` in the
`signature` object which is populated with the sign of the offset.  In
addition to exposing this information to the user, this information is
also used to compare signatures.

/cc @pks-t @ethomson

Fix clar to verify command line arguments before execute

Common parser interface

When executing `libgit2_clar -smerge -invalid_option`, it will first execute
the merge test suite and afterwards output help because of the invalid option.

With this changa, it verifies all options before execute. If there are any
invalid options, it will output help and exit without actually executing
the test suites.

cmake: Allow user to select bundled zlib

As the config parser is now cleanly separated from the config file code,
we can easily refactor the code and make use of the common parser
module. This removes quite a lot of duplicated functionality previously
used for handling the actual parser state and replaces it with the
generic interface provided by the parser context.

The configuration file code grew quite big and intermingles both actual
configuration logic as well as the parsing logic of the configuration
syntax. This makes it hard to refactor the parsing logic on its own and
convert it to make use of our new parsing context module.

Refactor the code and split it up into two parts. The config file code
will only handle actual handling of configuration files, includes and
writing new files. The newly created config parser module is then only
responsible for parsing the actual contents of a configuration file,
leaving everything else to callbacks provided to its provided function
`git_config_parse`.

Upon initializing the parser context, we do not currently initialize the
current line, line length and line number. Do so in order to make the
interface easier to use and more obvious for future consumers of the
parsing API.

Some code parts need to inspect the next few bytes without actually
consuming it yet, for example to examine what content it has to expect
next. Create a new function `git_parse_peek` which returns the next byte
without modifying the parsing context and use it at multiple call sites.

The patch parsing code has multiple recurring patterns where we want to
parse an actual number. Create a new function `git_parse_advance_digit`
and use it to avoid code duplication.

Instead of manually checking the parsing context's remaining length and
comparing the leading bytes with a specific string, we can simply re-use
the function `git_parse_ctx_contains_s`. Do so to avoid code duplication
and to further decouple patch parsing from the parsing context's struct
members.

The `git_patch_parse_ctx` encapsulates both parser state as well as
options specific to patch parsing. To advance this state and keep it
consistent, we provide a few functions which handle advancing the
current position and accessing bytes of the patch contents. In fact,
these functions are quite generic and not related to patch-parsing by
themselves. Seeing that we have similar logic inside of other modules,
it becomes quite enticing to extract this functionality into its own
parser module.

To do so, we create a new module `parse` with a central struct called
`git_parse_ctx`. It encapsulates both the content that is to be parsed
as well as its lengths and the current position. `git_patch_parse_ctx`
now only contains this `parse_ctx` only, which is then accessed whenever
we need to touch the current parser. This is the first step towards
re-using this functionality across other modules which require parsing
functionality and remove code-duplication.