add example for git commit
fix example for git add
add example for git push

Fix #5410: fix installing libgit2.pc in wrong location

Fix typo on GIT_USE_NEC

Signed-off-by: Sven Strickroth <email@cs-ware.de>

tests: diff: verify that we are able to diff with empty subtrees

README: update our build matrix to reflect current releases

azure: docker: set up HOME variable to fix Coverity builds

Remove using custom PKG_BUILD_PREFIu, PKG_BUILD_LIBDIR and
PKG_BUILD_INCLUDEDIR variables.
Use cmake CMAKE_INSTALL_PREFIX, LIB_INSTALL_DIR, INCLUDE_INSTALL_DIR instead.
This patch fixes install libgit2.pc file in correct location and simpifies
cmake module.

sha1_lookup: inline its only function into "pack.c"

Coverity fixes

In commit 01a83406 (azure: docker: fix ARM builds by replacing gosu(1),
2020-02-18), we've switched our entrypoint from gosu(1) to use sudo(1)
instead to fix our ARM builds. The switch introduced an incompatibility
that now causes our Coverity builds to fail, as the "--preserve-env"
switch will also keep HOME at its current value. As a result, Coverity
now tries to set up its configuration directory in root's home
directory, which it naturally can't write to.

Fix the issue by adding the "--set-home" flag to sudo(1).

As noted in docs/release.md, we only provide security updates for the
latest two releases. Let's thus drop the build status of both v0.27 and
v0.26 branches, adding the new v0.99 branch instead.

Release 0.99

Release script

This commit also switches our SOVERSION to be "$MAJOR.$MINOR" instead of
"$MINOR", only. This is in preparation of v1.0, where the previous
scheme would've stopped working in an obvious way.

Give the release a name, "Torschlusspanik" (the fear that time is
running out to act).  Indeed, the time is running out for changes to be
included in v1.0.

azure: fix ARM32 builds by replacing gosu(1)

openssl: fix Valgrind issues in nightly builds

fuzzers: Fix the documentation

In our test case object::cache::fast_thread_rush, we're creating 100
concurrent threads opening a repository and reading objects from it.
This test actually fails on ARM32 with an out-of-memory error, which
isn't entirely unexpected.

Work around the issue by halving the number of threads.

Our nightly builds are currently failing due to our ARM-based jobs.
These jobs crash immediately when entering the Docker container with a
exception thrown by Go's language runtime. As we're able to successfully
builds the Docker images in previous steps, it's unlikely to be a bug in
Docker itself. Instead, this exception is thrown by gosu(1), which is a
Go-based utility to drop privileges and run by our entrypoint.

Fix the issue by dropping gosu(1) in favor of sudo(1).

Our two Docker build instructions for Xenial and Bionic have diverged a
bit. Let's re-synchronize them with each other to make them as similar
as possible.

The build step for our Docker images currently succeeds even if building
the Docker image fails due to missing && chains in the build script. Fix
this by adding them in.

Since migrating to Docker containings for our build and test
infrastructure, we do not use the "setup-linux.sh" script anymore.
Remove it to avoid any confusion.

Some of the commands are now out of date.

As OpenSSL loves using uninitialized bytes as another source of entropy,
we need to mark them as defined so that Valgrind won't complain about
use of these bytes. Traditionally, we've been using the macro
`VALGRIND_MAKE_MEM_DEFINED` provided by Valgrind, but starting with
OpenSSL 1.1 the code doesn't compile anymore due to `struct SSL` having
become opaque. As such, we also can't set it as defined anymore, as we
have no way of knowing its size.

Let's change gears instead by just swapping out the allocator functions
of OpenSSL with our own ones. The twist is that instead of calling
`malloc`, we just call `calloc` to have the bytes initialized
automatically. Next to soothing Valgrind, this approach has the benefit
of being completely agnostic of the memory sanitizer and is neatly
contained at a single place.

Note that we shouldn't do this for non-Valgrind builds. As we cannot
set up memory functions for a given SSL context, only, we need to swap
them at a global context. Furthermore, as it's possible to call
`OPENSSL_set_mem_functions` once only, we'd prevent users of libgit2 to
set up their own allocators.

OpenSSL doesn't initialize bytes on purpose in order to generate
additional entropy. Valgrind isn't too happy about that though, causing
it to generate warninings about various issues regarding use of
uninitialized bytes.

We traditionally had some infrastructure to silence these errors in our
OpenSSL stream implementation, where we invoke the Valgrind macro
`VALGRIND_MAKE_MEMDEFINED` in various callbacks that we provide to
OpenSSL. Naturally, we only include these instructions if a preprocessor
define "VALGRIND" is set, and that in turn is only set if passing
"-DVALGRIND" to CMake. We do that in our usual Azure pipelines, but we
in fact forgot to do this in our nightly build. As a result, we get a
slew of warnings for these nightly builds, but not for our normal
builds.

To fix this, we could just add "-DVALGRIND" to our nightly builds. But
starting with commit d827b11b (tests: execute leak checker via CTest
directly, 2019-06-28), we do have a secondary variable that directs
whether we want to use memory sanitizers for our builds. As such, every
user wishing to use Valgrind for our tests needs to pass both options
"VALGRIND" and "USE_LEAK_CHECKER", which is cumbersome and error prone,
as can be seen by our own builds.

Instead, let's consolidate this into a single option, removing the old
"-DVALGRIND" one. Instead, let's just add the preprocessor directive if
USE_LEAK_CHECKER equals "valgrind" and remove "-DVALGRIND" from our own
pipelines.

azure: fix misleading messages printed to stderr being

tests: iterator: fix iterator expecting too few items

The current release process is not documented in any way. As a result,
it's not obvious how releases should be done at all, like e.g. which
locations need adjusting.

To fix this, let's introduce a new script that shall from now on be used
to do all releases. As input it gets the tree that shall be released,
the repository in which to do the release, credentials to
authenticate against GitHub and the new version. E.g. executing the
following will create a new release v0.32:

    $ ./script/release.py 0.32.0 --user pks-t --password ****

While the password may currently be your usual GitLab password, it's
recommended to use a personal access token intead.

The script will then perform the following steps:

    1. Verify that "include/git2/version.h" matches the new version.

    2. Verify that "docs/changelog.md" has a section for that new
       version.

    3. Extract the changelog entries for the current release from
       "docs/changelog.md".

    4. Generate two archives in "tar.gz" and "zip" format via "git
       archive" from the tree passed by the user. If no tree was passed,
       we will use "HEAD".

    5. Create the GitHub release using the extracted changelog entries
       as well as tag and name information derived from the version
       passed by the used.

    6. Upload both code archives to that release.

This should cover all steps required for a new release and thus ensures
that nothing is missing that shouldn't be.

Python's PEP 8 specifies that one shall use spaces instead of tabs as
coding style, and we actually honor that currently. Our EditorConfig
does not special-case Python scripts, though, which is why we end up
with our C coding style and thus with tabs.

Special-case "*.py" files to override that default with spaces to fix
this.

It was reported that, given a file "abc.txt", a diff will be shown if an
empty directory "abb/" is created, but not if "abd/" is created. Add a
test to verify that we do the right thing here and do not depend on any
ordering.

While it is not allowed for a tree to have an empty tree as child (e.g.
an empty directory), libgit2's tree builder makes it easy to create such
trees. As a result, some applications may inadvertently end up with such
an invalid tree, and we should try our best and handle them.

One such case is when diffing two trees, where one of both trees has
such an empty subtree. It was reported that this will cause our diff
code to fail. While I wasn't able to reproduce this error, let's still
add a test that verifies we continue to handle them correctly.

The testcase iterator::workdir::filesystem_gunk sets up quite a lot of
directories, which is why it only runs in case GITTEST_INVASIVE_SPEED is
set in the environment. Because we do not run our default CI with this
variable, we didn't notice commit 852c83ee (refs: refuse to delete
HEAD, 2020-01-15) breaking the test as it introduced a new reference to
the "testrepo" repository.

Fix the oversight by increasing the number of expected iterator items.

In order to properly tear down the test environment, we will kill
git-daemon(1) if we've exercised it. As git-daemon(1) is spawned as a
background process, it is still owned by the shell and thus killing it
later on will print a termination message to the shell's stderr, causing
Azure to report it as an error.

Fix this by disowning the background process.

The Docker entrypoint currently creates the libgit2 user with "useradd
--create-home". As we start the Docker container with two volumes
pointing into "/home/libgit2/", the home directory will already exist.
While useradd(1) copes with this just fine, it will print error messages
to stderr which end up as failures in our Azure pipelines.

Fix this by simply removing the "--create-home" parameter.

Without the "--silent" parameter, curl will print a progress meter to
stderr. Azure has the nice feature of interpreting any output to stderr
as errors with a big red warning towards the end of the build. Let's
thus silence curl to not generate any misleading messages.

When building dependencies for our Docker images, we first download the
sources to disk first, unpack them and finally remove the archive again.
This can be sped up by piping the downloading archive into tar(1)
directly to parallelize both tasks. Furthermore, let's silence curl(1)
to not print to status information to stderr, which tends to be
interpreted as errors by Azure Pipelines.

OpenSSL pre-v1.1 required us to set up a locking function to properly
support multithreading. The locking function signature cannot return any
error codes, and as a result we can't do anything if `git_mutex_lock`
fails. To silence static analysis tools, let's just explicitly ignore
its return value by casting it to `void`.

When adding a new entry to our cache where an entry with the same OID
exists already, then we only update the existing entry in case it is
unparsed and the new entry is parsed. Currently, we do not check the
return value of `git_oidmap_set` though when updating the existing
entry. As a result, we will _not_ have updated the existing entry if
`git_oidmap_set` fails, but have decremented its refcount and
incremented the new entry's refcount. Later on, this may likely lead to
dereferencing invalid memory.

Fix the issue by checking the return value of `git_oidmap_set`. In case
it fails, we will simply keep the existing stored instead, even though
it's unparsed.