Right now, we first load the packed refs cache and only afterwards load the
loose references. This is susceptible to a race when the loose ref is being
migrated to a packed cache by e.g. git-pack-refs(1):

                libgit2                             git-pack-refs

   1. We load the packed ref, which
      does not yet have the migrated
      reference.

                                      2. git-pack-refs updates the packed ref
                                         file to have the migrated ref.

                                      3. git-pack-refs deletes the old loose
                                         ref.

   4. We look up the loose ref.

So we now do not find the reference at all and will never iterate over it.

Fix the issue by reversing the order: instead of first loading the packed refs,
we will now look up the loose reference first. If it has already been deleted,
then it must already be present in the packed-refs by definition, as git.git
will only delete the reference after updating the packed refs file.

Right now, loading loose refs has the side-effect of setting the
`PACKREF_SHADOWED` flag for references that exist both in the loose and the
packed refs. Because of this, we are force do first look up packed refs and only
afterwards loading the packed refs. This is susceptible to a race, though, when
refs are being repacked: when first loading the packed cache, then it may not
yet have the migrated loose ref. But when now trying to look up the loose
reference afterwards, then it may already have been migrated. Thus, we would
fail to find this reference in this scenario.

Remove this ordering dependency to allow fixing the above race. Instead of
setting the flag when loading loose refs, we will now instead set it lazily when
iterating over the loose refs. This even has the added benefit of not requiring
us to lock the packed refs cache, as we already have an owned copy of it.

When creating a new iterator, we eagerly load loose refs but only lazily create
a copy of packed refs. The lazy load only happens as soon as we have iterated
over all loose refs, opening up a potentially wide window for races. This
may lead to an inconsistent view e.g. when the caller decides to reload packed
references somewhen between iterating the loose refs, which is unexpected.

Fix the issue by eagerly copying the sorted cache. Note that right now, we are
heavily dependent on ordering here: we first need to reload packed refs, then we
have to load loose refs and only as a last step are we allowed to copy the
cache. This is because loading loose refs has the side-effect of setting the
`PACKED_SHADOWED` flag in the packed refs cache, which we require to avoid
outputting packed refs that already exist as loose refs.

Refactor the error handling in `refdb_fs_backend__iterator` to always return the
correct error code returned by the failing function.

When repacking references, git.git will first update the packed refs and only
afterwards delete any existing loose references that have now been moved to the
new packed refs file. Due to this, there is a potential for racing if one first
reads the packfile (which has not been updated yet) and only then trying to read
the loose reference (which has just been deleted). In this case, one will
incorrectly fail to lookup the reference and it will be reported as missing.
Naturally, this is exactly what we've been doing in `refdb_fs_backend__exists`.

Fix the race by reversing the lookup: we will now first check if the loose
reference exists and only afterwards refresh the packed file.

Enable creation of worktree from bare repo's default branch

Allow bypassing check for '.keep' file

Deprecation: export the deprecated functions properly

In a bare repository, HEAD usually points to the branch that is
considered the "default" branch. As the current implementation for
`git_branch_is_checked_out` only does a comparison of HEAD with the
branch that is to be checked, it will say that the branch pointed to by
HEAD in such a bare repo is checked out.

Fix this by skipping the main repo's HEAD when it is bare.

Right now, the function `git_repository_foreach_head` will always
iterate over all HEADs of the main repository and its worktrees. In some
cases, it might be required to skip either of those, though. Add a flag
in preparation for the following commit that enables this behaviour.

Libraries should use assert(3P) only very scarcely. First, we usually
shouldn't cause the caller of our library to abort in case where the
assert fails. Second, if code is compiled with -DNDEBUG, then the assert
will not be included at all.

In our `git_branch_is_checked_out` function, we have an assert that
verifies that the given reference parameter is non-NULL and in fact a
branch. While the first check is fine, the second is not. E.g. when
compiled with -DNDEBUG, we'd proceed and treat the given reference as a
branch in all cases.

Fix the issue by instead treating a non-branch reference as not being
checked out. This is the obvious solution, as references other than
branches cannot be directly checked out.

We currently do not have any tests at all for the
`git_branch_is_checked_out` function. Add some basic ones.

When adding a new worktree, we only verify that an optionally given
reference is valid half-way through the function. At this point, some
data structures have already been created on-disk. If we bail out due to
an invalid reference, these will be left behind and need to be manually
cleaned up by the user.

Improve the situation by moving the reference checks to the function's
preamble. Like this, we error out as early as possible and will not
leave behind any files.

Enable hard deprecation in our builds to ensure that we do not call
deprecated functions internally.

Add a CMake option to enable hard deprecation; the resultant library
will _not_ include any deprecated functions.  This may be useful for
internal CI builds that create libraries that are not shared with
end-users to ensure that we do not use deprecated bits internally.

Although the error functions were deprecated, we did not properly mark
them as deprecated.  We need to include the `deprecated.h` file in order
to ensure that the functions get their export attributes.

Similarly, do not define `GIT_DEPRECATE_HARD` within the library, or
those functions will also not get their export attributes.  Define that
only on the tests and examples.

ci: skip ssh tests on macOS nightly

Like 811c1c0f, disable the SSH tests on
macOS until we can resolve the newly introduced infrastructure issues.

CI build fixups

SSH tests on macOS have begun failing for an unknown reason after an
infrastructure upgrade to macOS 10.13.6.  Disable those tests
temporarily, until we can resolve it.

Subtle changes in the host OS can have impacts in the CI system that
may be hard to debug.  We previously showed the results of `uname` which
can be difficult to interpret.  Provide more information where
available.

The URL was incorrect for the nightly badge image; it was erroneously
showing the master branch continuous integration build badge.

Include a build badge for `maint/v0.28` builds.

v0.28 rc1

Docs

The mbedtls library uses a callback mechanism to allow downstream users
to plug in their own receive and send functions. We implement `bio_read`
and `bio_write` functions, which simply wrap the `git_stream_read` and
`git_stream_write` functions, respectively.

The problem arises due to the return value of the callback functions:
mbedtls expects us to return an `int` containing the actual number of
bytes that were read or written. But this is in fact completely
misdesigned, as callers are allowed to pass in a buffer with length
`SIZE_MAX`. We thus may be unable to represent the number of bytes
written via the return value.

Fix this by only ever reading or writing at most `INT_MAX` bytes.

The mbedtls stream implementation makes use of some global variables
which are not marked as `static`, even though they're only used in this
compilation unit. Fix this and remove a duplicate declaration.

Our `openssl_write` function calls `SSL_write` by passing in both `data`
and `len` arguments directly. Thing is, our `len` parameter is of type
`size_t` and theirs is of type `int`. We thus need to clamp our length
to be at most `INT_MAX`.

Now that the function `git_stream__write_full` exists and callers of
`git_stream_write` have been adjusted, we can lift logic for short
writes out of the stream implementations. Instead, this is now handled
either by `git_stream__write_full` or by callers of `git_stream_write`
directly.

Similar to the write(3) function, implementations of `git_stream_write`
do not guarantee that all bytes are written. Instead, they return the
number of bytes that actually have been written, which may be smaller
than the total number of bytes. Furthermore, due to an interface design
issue, we cannot ever write more than `SSIZE_MAX` bytes at once, as
otherwise we cannot represent the number of bytes written to the caller.

Unfortunately, no caller of `git_stream_write` ever checks the return
value, except to verify that no error occurred. Due to this, they are
susceptible to the case where only partial data has been written.

Fix this by introducing a new function `git_stream__write_full`. In
contrast to `git_stream_write`, it will always return either success or
failure, without returning the number of bytes written. Thus, it is able
to write all `SIZE_MAX` bytes and loop around `git_stream_write` until
all data has been written. Adjust all callers except the BIO callbacks
in our mbedtls and OpenSSL streams, which already do the right thing and
require the amount of bytes written.

The callback functions that implement the `git_stream` structure are
only used inside of their respective implementation files, but they are
not marked as `static`. Fix this.

Documentation fixes

ci: add an individual coverity pipeline

Coverity is back but it's only read-only!  Agh.  Just allow it to fail
and not impact the overall job run.