Currently, our headers need to leak some implementation details of maps due to
their direct use of indices in the implementation of their foreach macros. This
makes it impossible to completely hide the map structures away, and also makes
it impossible to include the khash implementation header in the C files of the
respective map only.

This is now being fixed by providing a high-level iteration interface
`map_iterate`, which takes as inputs the map that shall be iterated over, an
iterator as well as the locations where keys and values shall be put into. For
simplicity's sake, the iterator is a simple `size_t` that shall initialized to
`0` on the first call. All existing foreach macros are then adjusted to make use
of this new function.

Some callers were still using the tightly-coupled pattern of `lookup_index` and
`valid_index` to verify that an entry exists in a map. Instead, use the more
high-level `exists` functions to decouple map users from its implementation.

Currently, the delete functions of maps do not provide a return value. Like
this, it is impossible to tell whether the entry has really been deleted or not.
Change the implementation to provide either a return value of zero if the entry
has been successfully deleted or `GIT_ENOTFOUND` if the key could not be found.

Convert callers to the `delete_at` functions to instead use this higher-level
interface.

The currently existing function `git_idxmap_resize` and
`git_idxmap_icase_resize` do not return any error codes at all due to their
previous implementation making use of a macro. Due to that, it is impossible to
see whether the resize operation might have failed due to an out-of-memory
situation.

Fix this by providing a proper error code. Adjust callers to make use of it.

Currently, one would use the function `git_idxmap_insert` to insert key/value
pairs into a map. This function has historically been a macro, which is why its
syntax is kind of weird: instead of returning an error code directly, it instead
has to be passed a pointer to where the return value shall be stored. This does
not match libgit2's common idiom of directly returning error codes.

Introduce a new function `git_idxmap_set`, which takes as parameters the map,
key and value and directly returns an error code. Convert all callers of
`git_idxmap_insert` to make use of it.

The current way of looking up an entry from a map is tightly coupled with the
map implementation, as one first has to look up the index of the key and then
retrieve the associated value by using the index. As a caller, you usually do
not care about any indices at all, though, so this is more complicated than
really necessary. Furthermore, it invites for errors to happen if the correct
error checking sequence is not being followed.

Introduce new high-level functions `git_idxmap_get` and `git_idxmap_icase_get`
that take a map and a key and return a pointer to the associated value if such a
key exists. Otherwise, a `NULL` pointer is returned. Adjust all callers that can
trivially be converted.

Currently, there is only one caller that adds entries into an offset map, and
this caller first uses `git_offmap_put` to add a key and then set the value at
the returned index by using `git_offmap_set_value_at`. This is just too tighlty
coupled with implementation details of the map as it exposes the index of
inserted entries, which we really do not care about at all.

Introduce a new function `git_offmap_set`, which takes as parameters the map,
key and value and directly returns an error code. Convert the caller to make use
of it instead.

The current way of looking up an entry from a map is tightly coupled with the
map implementation, as one first has to look up the index of the key and then
retrieve the associated value by using the index. As a caller, you usually do
not care about any indices at all, though, so this is more complicated than
really necessary. Furthermore, it invites for errors to happen if the correct
error checking sequence is not being followed.

Introduce a new high-level function `git_offmap_get` that takes a map and a key
and returns a pointer to the associated value if such a key exists. Otherwise,
a `NULL` pointer is returned. Adjust all callers that can trivially be
converted.

Currently, one would use either `git_oidmap_insert` to insert key/value pairs
into a map or `git_oidmap_put` to insert a key only. These function have
historically been macros, which is why their syntax is kind of weird: instead of
returning an error code directly, they instead have to be passed a pointer to
where the return value shall be stored. This does not match libgit2's common
idiom of directly returning error codes.Furthermore, `git_oidmap_put` is tightly
coupled with implementation details of the map as it exposes the index of
inserted entries.

Introduce a new function `git_oidmap_set`, which takes as parameters the map,
key and value and directly returns an error code. Convert all trivial callers of
`git_oidmap_insert` and `git_oidmap_put` to make use of it.

The current way of looking up an entry from a map is tightly coupled with the
map implementation, as one first has to look up the index of the key and then
retrieve the associated value by using the index. As a caller, you usually do
not care about any indices at all, though, so this is more complicated than
really necessary. Furthermore, it invites for errors to happen if the correct
error checking sequence is not being followed.

Introduce a new high-level function `git_oidmap_get` that takes a map and a key
and returns a pointer to the associated value if such a key exists. Otherwise,
a `NULL` pointer is returned. Adjust all callers that can trivially be
converted.

Currently, one would use the function `git_strmap_insert` to insert key/value
pairs into a map. This function has historically been a macro, which is why its
syntax is kind of weird: instead of returning an error code directly, it instead
has to be passed a pointer to where the return value shall be stored. This does
not match libgit2's common idiom of directly returning error codes.

Introduce a new function `git_strmap_set`, which takes as parameters the map,
key and value and directly returns an error code. Convert all callers of
`git_strmap_insert` to make use of it.

The current way of looking up an entry from a map is tightly coupled with the
map implementation, as one first has to look up the index of the key and then
retrieve the associated value by using the index. As a caller, you usually do
not care about any indices at all, though, so this is more complicated than
really necessary. Furthermore, it invites for errors to happen if the correct
error checking sequence is not being followed.

Introduce a new high-level function `git_strmap_get` that takes a map and a key
and returns a pointer to the associated value if such a key exists. Otherwise,
a `NULL` pointer is returned. Adjust all callers that can trivially be
converted.

There currently exist two different function names for getting the entry count
of maps, where offmaps offset and string maps use `num_entries` and OID maps use
`size`. In most programming languages with built-in map types, this is simply
called `size`, which is also shorter to type. Thus, this commit renames the
other two functions `num_entries` to match the common way and adjusts all
callers.

Currently, the lifecycle functions for maps (allocation, deallocation, resize)
are not named in a uniform way and do not have a uniform function signature.
Rename the functions to fix that, and stick to libgit2's naming scheme of saying
`git_foo_new`. This results in the following new interface for allocation:

- `int git_<t>map_new(git_<t>map **out)` to allocate a new map, returning an
  error code if we ran out of memory

- `void git_<t>map_free(git_<t>map *map)` to free a map

- `void git_<t>map_clear(git<t>map *map)` to remove all entries from a map

This commit also fixes all existing callers.

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.