We used to hard-code the octothorpe as the comment character and the
documentation still mentions this even though we accept the comment character as
a parameter.

Update the line to indicate this and clean up the first paragraph a bit.

Implement message trailer parsing API

Memory leaks

The test refs::iterator::foreach_name iterates through every reference
and copies its name into a local vector. While the test makes sure to
free the vector afterwards, the copied reference names are not being
free'd. Fix that.

References passed to the callback function of `git_reference_foreach`
are expected to be owned by the callback. As such, they are never being
freed by `git_reference_foreach`, but will have to be freed by the
caller. This small detail is never mentioned in the function's
documentation, though, making it easy to get wrong. Document this to
make it discoverable.

Upon downloading the pack file, the local transport will iterate through
every reference using `git_reference_foreach`. The function is a bit
tricky though in that it requires the passed callback to free the
references, which does not currently happen.

Fix the memory leak by freeing all passed references in the callback.

Two tests in network::fetchlocal explicitly set a cleanup function to
free and remove the created sandbox repositories. This is not necessary,
though, as the cleanup function executed after each test already takes
care of cleaning up after them. Remove the code to avoid needless code
duplication.

travis: fetch trusty dependencies from Bintray

The VM on Travis apparently will still proceed, but it's good practice.

The trusty dependencies are now hosted on Bintray.

cmake: use a FEATURE_SUMMARY call compatible with 3.0.2

When we print features, we make an effort to support all the way back to
pre-3.0. However, in the code for versions from 3 onward we call
`FEATURE_SUMMARY` with multiple kinds of elements to print in the same line.
This is only supported in CMake 3.1 and later, making the rather popular CMake
3.0.2 unable to build the library.

Use a single kind of element per invocation. This means we need to provide a
"description" text, which CMake provides for us if provide multiple kinds of
elements.

Make sure to include 'openssl' as a dep when building statically with SHA1DC

We might want OpenSSL to be the implementation for SHA-1 and/or TLS. If we only
want it for TLS (e.g. we're building with the collision-detecting SHA-1
implementation) then we did not indicate this to the systems including us a
static library.

Add OpenSSL to the list also during the TLS decision to make sure we say we
should link to it if we use it for TLS.

It is indeed a list of dependencies for those which include the static archive.
This is in preparation for adding two possible places where we might add openssl
as a dependency.

cmake: move the rule to find static archives close to building clar

If we're building static libraries, we want to use that for building our clar
binary. This is done in 49551254 (2017-09-22; cmake: use static dependencies
when building static libgit2) but that commit included the rule too early,
making it affect the search for iconv, meaning we did not find it when we were
building a static libgit2.

Move the rule to just before building clar, after we've included the rules for
building the library itself. This lets us find and link to the dynamic libiconv.

cmake: allow explicitly choosing SHA1 backend

Right now, if SHA1DC is disabled, the SHA1 backend is mostly chosen
based on which system libgit2 is being compiled on and which libraries
have been found. To give developers and distributions more choice,
enable them to request specific backends by passing in a
`-DSHA1_BACKEND=<BACKEND>` option instead. This completely replaces the
previous auto-selection.

Upstream git.git has changed their default SHA1 implementation to the
collision-detection algorithm SHA1DC in commit e6b07da27 (Makefile: make
DC_SHA1 the default, 2017-03-17). To match upstream, align ourselves and
switch over to SHA1DC by default.

Execute stale tests

hash: openssl: check return values of SHA1_* functions

diff_generate: avoid excessive stats of .gitattribute files

When generating a diff between two trees, for each file that is to be
diffed we have to determine whether it shall be treated as text or as
binary files. While git has heuristics to determine which kind of diff
to generate, users can also that default behaviour by setting or
unsetting the 'diff' attribute for specific files.

Because of that, we have to query gitattributes in order to determine
how to diff the current files. Instead of hitting the '.gitattributes'
file every time we need to query an attribute, which can get expensive
especially on networked file systems, we try to cache them instead. This
works perfectly fine for every '.gitattributes' file that is found, but
we hit cache invalidation problems when we determine that an attribuse
file is _not_ existing. We do create an entry in the cache for missing
'.gitattributes' files, but as soon as we hit that file again we
invalidate it and stat it again to see if it has now appeared.

In the case of diffing large trees with each other, this behaviour is
very suboptimal. For each pair of files that is to be diffed, we will
repeatedly query every directory component leading towards their
respective location for an attributes file. This leads to thousands or
even hundreds of thousands of wasted syscalls.

The attributes cache already has a mechanism to help in that scenario in
form of the `git_attr_session`. As long as the same attributes session
is still active, we will not try to re-query the gitmodules files at all
but simply retain our currently cached results. To fix our problem, we
can create a session at the top-most level, which is the initialization
of the `git_diff` structure, and use it in order to look up the correct
diff driver. As the `git_diff` structure is used to generate patches for
multiple files at once, this neatly solves our problem by retaining the
session until patches for all files have been generated.

The fix has been tested with linux.git by calling
`git_diff_tree_to_tree` and `git_diff_to_buf` with v4.10^{tree} and
v4.14^{tree}.

                | time    | .gitattributes stats
    without fix | 33.201s | 844614
    with fix    | 30.327s | 4441

While execution only improved by roughly 10%, the stat(3) syscalls for
.gitattributes files decreased by 99.5%. The benchmarks were quite
simple with best-of-three timings on Linux ext4 systems. One can assume
that for network based file systems the performance gain will be a lot
larger due to a much higher latency.

cmake: create a dummy file for Xcode

The function `ERR_error_string` can be invoked without providing a
buffer, in which case OpenSSL will simply return a string printed into a
static buffer. Obviously and as documented in ERR_error_string(3), this
is not thread-safe at all. As libgit2 is a library, though, it is easily
possible that other threads may be using OpenSSL at the same time, which
might lead to clobbered error strings.

Fix the issue by instead using a stack-allocated buffer. According to
the documentation, the caller has to provide a buffer of at least 256
bytes of size. While we do so, make sure that the buffer will never get
overflown by switching to `ERR_error_string_n` to specify the buffer's
size.

The OpenSSL functions `SHA1_Init`, `SHA1_Update` and `SHA1_Final` all
return 1 for success and 0 otherwise, but we never check their return
values. Do so.

Some tests shall be run against our own SSH server we spin up in Travis.
As those need to be run separate from our previous tests which run
against git-daemon, we have to do this in a separate step. Instead of
bundling all that knowledge in the CI script, move it into the test
build instructions by creating a new test target.

Right now, we test our credential callback code twice, once via SSH on
localhost and once via a non-existent GitHub repository. While the first
URL makes sense to be configurable, it does not make sense to hard-code
the non-existing repository, which requires us to call tests multiple
times. Instead, we can just inline the URL into another set of tests.