The current signature of `git_worktree_prune` accepts a flags field to
alter its behavior. This is not as flexible as we'd like it to be when
we want to enable passing additional options in the future. As the
function has not been part of any release yet, we are still free to
alter its current signature. This commit does so by using our usual
pattern of an options structure, which is easily extendable without
breaking the API.

When creating a new worktree, we do have a potential race with us
creating the worktree and another process trying to delete the same
worktree as it is being created. As such, the upstream git project has
introduced a flag `git worktree add --locked`, which will cause the
newly created worktree to be locked immediately after its creation. This
mitigates the race condition.

We want to be able to mirror the same behavior. As such, a new flag
`locked` is added to the options structure of `git_worktree_add` which
allows the user to enable this behavior.

The `git_worktree_add` function currently accepts only a path and name
for the new work tree. As we may want to expand these parameters in
future versions without adding additional parameters to the function for
every option, this commit introduces our typical pattern of an options
struct. Right now, this structure is still empty, which will change with
the next commit.

Branch renames with worktrees

socket_stream: continue to next addrinfo on socket creation failure

Honor read-only flag when writing to config backends

When connecting to a remote via socket stream, we first use getaddrinfo
to obtain the possible connection methods followed by creating and
connecting the socket. But when creating the socket, we error out as
soon as we get an invalid socket instead of trying out other address
hints returned by addrinfo.

Fix this by continuing on invalid socket instead of returning an error.
This fixes connection establishment with musl libc.

Configuration backends have a readonly-flag which is currently used to
distinguish configuration snapshots. But somewhat unexpectedly, we do
not use the flag to prevent writing to a readonly backend but happily
proceed to do so.

This commit modifies logic to also honor the readonly flag for
configuration setters. We will now traverse through all backends and
pick the first one which is not marked as read-only whenever we want to
write new configuration.

diff_parse: free object instead of its pointer

The config_file.h header provides some inline declarations accessing the
`git_config_backend`, but misses its declaration. Add the missing
include for "git2/sys/config.h" to add it.

In e7330016 (diff_parse: check return value of `git_diff_init_options`,
2017-03-20), we've introduced an error check whether we're able to
correctly initialize the diff options. This simple commit actually
introduced a segfault in that we now try to free the pointer to the
allocated diff in an error case, instead of the allocated diff itself.
This commit fixes the issue.

Misc fixes

The threads::diff test suite has a static variable `_retries`, which is
used on Windows platforms only. As it is unused on other systems, the
compiler throws a warning there. Fix the warning by wrapping the
declaration in an ifdef.

Refactor some of the win32 POSIX emulation

The `remediation` function is run in the retry loop in order to attempt
to fix any problems that the prior run encountered.  There is nothing
"cleaned up".  Clarify the name.

fileops: fix leaking fd in `mmap_ro_file`

When the `git_futils_mmap_ro_file` function encounters an error after
the file has been opened, it will do a simple returns. Instead, we
should close the opened file descriptor to avoid a leak. This commit
fixes the issue.

filter: only close filter if it's been initialized correctly

Fix building against OpenSSL v1.1

README: document our relation to changes in upstream

libgit2 is a mere consumer of changes which are trickling down from the
upstream git.git project. This commit documents the ramifications caused
by this relation.

Previous to OpenSSL version 1.1, the user had to initialize at least the error
strings as well as the SSL algorithms by himself. OpenSSL version 1.1 instead
provides a new function `OPENSSL_init_ssl`, which handles initialization of all
subsystems. As the new API call will by default load error strings and
initialize the SSL algorithms, we can safely replace these calls when compiling
against version 1.1 or later.

This fixes a compiler error when compiling against OpenSSL version 1.1 which has
been built without stubs for deprecated syntax.

Up to version 1.0, OpenSSL required us to provide a callback which implements
a locking mechanism. Due to problems in the API design though this mechanism was
inherently broken, especially regarding that the locking callback cannot report
errors in an obvious way. Due to this shortcoming, the locking initialization
has been completely removed in OpenSSL version 1.1. As the library has also been
refactored to not make any use of these callback functions, we can safely remove
all initialization of the locking subsystem if compiling against OpenSSL version
1.1 or higher.

This fixes a compilation error when compiling against OpenSSL version 1.1 which
has been built without stubs for deprecated syntax.

In the function `git_filter_list_stream_data`, we initialize, write and
subesquently close the stream which should receive content processed by
the filter. While we skip writing to the stream if its initialization
failed, we still try to close it unconditionally -- even if the
initialization failed, where the stream might not be set at all, leading
us to segfault.

Semantics in this code is not really clear. The function handling the
same logic for files instead of data seems to do the right thing here in
only closing the stream when initialization succeeded. When stepping
back a bit, this is only reasonable: if a stream cannot be initialized,
the caller would not expect it to be closed again. So actually, both
callers of `stream_list_init` fail to do so. The data streaming function
will always close the stream and the file streaming function will not
close the stream if writing to it has failed.

The fix is thus two-fold:

- callers of `stream_list_init` now close the stream iff it has been
  initialized
- `stream_list_init` now closes the lastly initialized stream if
  the current stream in the chain failed to initialize

Add a test which segfaulted previous to these changes.

Coverity

pkgconfig: fix handling of prefixes containing whitespaces

Our libgit2.pc.in file is quoting the `libdir` variable in our declared
"Libs:" line. The intention is to handle whitespaces here, but pkgconfig
already does so by automatically escaping whitespace with backslashes.
The correct thing to do is to instead quote the prefix, as this is the
one which is being substituted by CMake upon installation. As both
libdir and includedir will be expanded to "${prefix}/lib" and
"${prefix}/include", respectively, pkgconfig will also correctly escape
whitespaces.

Note that this will actually break when a user manually wants to
override libdir and includedir with a path containing whitespace. But
actually, this cannot be helped, as always quoting these variables will
actuall break the common case of being prefixed with "${prefix}". So we
just bail out here and declare this as unsupported out of the box.

Whenever we rename a branch, we update the repository's symbolic HEAD
reference if it currently points to the branch that is to be renamed.
But with the introduction of worktrees, we also have to iterate over all
HEADs of linked worktrees to adjust them. Do so.

Previously, we have extracted the logic to find and iterate over all
HEADs of a repository. Use this function in `git_branch_is_checked_out`.

While we already provide functions to get the current repository's HEAD,
it is quite involved to iterate over HEADs of both the repository and
all linked work trees. This commit implements a function
`git_repository_foreach_head`, which accepts a callback which is then
called for all HEAD files.

The functions `git_repository_head_for_worktree` and
`git_repository_detached_head_for_worktree` both implement their
own logic to read the HEAD reference file. Use the new function
`git_reference__read_head` instead to unify the code paths.

The function `read_worktree_head` has the logic embedded to construct
the path to `HEAD` in the work tree's git directory, which is quite
useful for other callers. Extract the logic into its own function to
make it reusable by others.

If trying to set the HEAD of a repository to another reference, we have
to check whether this reference is already checked out in another linked
work tree. If it is, we will refuse setting the HEAD and return an
error, but do not set a meaningful error message. Add one.

Currently, we only provide functions to read references directly from a
repository's reference store via e.g. `git_reference_lookup`. But in
some cases, we may want to read files not connected to the current
repository, e.g. when looking up HEAD of connected work trees. This
commit implements `git_reference__read_head`, which will read out and
allocate a reference at an arbitrary path.

Instead of failing to set the timestamp of a read-only file (like any
object file), set it writable temporarily to update the timestamp.

When executing `git_futils_mmap_ro_file`, we first try to guess whether
the file is mmapable at all. Part of this check is whether the file is
too large to be mmaped, which can be true on systems with 32 bit
`size_t` types.

The check is performed by first getting the file size wtih
`git_futils_filesize` and then checking whether the returned size can be
represented as `size_t`, returning an error if so. While this test also
catches the case where the function returned an error (as `-1` is not
representable by `size_t`), we will set the misleading error message
"file too large to mmap". But in fact, a negative return value from
`git_futils_filesize` will be caused by the inability to fstat the file.

Fix the error message by handling negative return values separately and
not overwriting the error message in that case.