Depth of `0` should indicate full depth. Disallow negative values (they
may have a future meaning) and use `0` as the default.

Only allow the remote default branch checking to fail when the remote
default branch doesn't exist (`git_remote__default_branch` returns
`GIT_ENOTFOUND`). If there was any other type of error - for example, an
allocation failure - we should not swallow that and continue to fail.

This allows us to support the case when a remote has not advertised a
HEAD -- this is possible, for example, when the remote has constrained
the caller to a particular namespace. But other remote failures remain
as failures.

In commit 6bb35878 ("clone: set refs/remotes/origin/HEAD to default
branch when branch is specified, attempt 2") libgit2 was changed to set
the default remote branch when one was copied.

But it makes update_head_to_branch() return an error if the origin
doesn't even *have* a HEAD in the first place, since
git_remote_default_branch() will fail.

That's entirely wrong, and means that you cannot do "git_clone()" of a
particular branch on a remote repository when that remote doesn't have a
default branch at all.

So don't set the error code.

Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

Introduce `git_fs_path`, which operates on generic filesystem paths.
`git_path` will be kept for only git-specific path functionality (for
example, checking for `.git` in a path).

libgit2 has two distinct requirements that were previously solved by
`git_buf`.  We require:

1. A general purpose string class that provides a number of utility APIs
   for manipulating data (eg, concatenating, truncating, etc).
2. A structure that we can use to return strings to callers that they
   can take ownership of.

By using a single class (`git_buf`) for both of these purposes, we have
confused the API to the point that refactorings are difficult and
reasoning about correctness is also difficult.

Move the utility class `git_buf` to be called `git_str`: this represents
its general purpose, as an internal string buffer class.  The name also
is an homage to Junio Hamano ("gitstr").

The public API remains `git_buf`, and has a much smaller footprint.  It
is generally only used as an "out" param with strict requirements that
follow the documentation.  (Exceptions exist for some legacy APIs to
avoid breaking callers unnecessarily.)

Utility functions exist to convert a user-specified `git_buf` to a
`git_str` so that we can call internal functions, then converting it
back again.

Make some syntax change to follow coding style.

This reverts commit 487f2a82, reversing
changes made to c6cf7f0e.

When a branch is specified to check out in clone, update the remote
tracking `HEAD` to point to it.  This mimics git's behavior, when
`git clone -b <name>` is used.

Update `refs/remotes/origin/HEAD` as a symbolic link to the remote's
default branch.

We derive the branch name, even in our code, we shouldn't assume that
the branch will be "master".

When cloning an empty repository, we need to guess what the branch
structure should be; instead of hardcoding `master`, use the
`init.defaultBranch` setting it if it provided.

When compiling libgit2 with -DDEPRECATE_HARD, we add a preprocessor
definition `GIT_DEPRECATE_HARD` which causes the "git2/deprecated.h"
header to be empty. As a result, no function declarations are made
available to callers, but the implementations are still available to
link against. This has the problem that function declarations also
aren't visible to the implementations, meaning that the symbol's
visibility will not be set up correctly. As a result, the resulting
library may not expose those deprecated symbols at all on some platforms
and thus cause linking errors.

Fix the issue by conditionally compiling deprecated functions, only.
While it becomes impossible to link against such a library in case one
uses deprecated functions, distributors of libgit2 aren't expected to
pass -DDEPRECATE_HARD anyway. Instead, users of libgit2 should manually
define GIT_DEPRECATE_HARD to hide deprecated functions. Using "real"
hard deprecation still makes sense in the context of CI to test we don't
use deprecated symbols ourselves and in case a dependant uses libgit2 in
a vendored way and knows it won't ever use any of the deprecated symbols
anyway.

Our file utils functions all have a "futils" prefix, e.g.
`git_futils_touch`. One would thus naturally guess that their
definitions and implementation would live in files "futils.h" and
"futils.c", respectively, but in fact they live in "fileops.h".

Rename the files to match expectations.

In libgit2 nomenclature, when we need to verb a direct object, we name
a function `git_directobject_verb`.  Thus, if we need to init an options
structure named `git_foo_options`, then the name of the function that
does that should be `git_foo_options_init`.

The previous names of `git_foo_init_options` is close - it _sounds_ as
if it's initializing the options of a `foo`, but in fact
`git_foo_options` is its own noun that should be respected.

Deprecate the old names; they'll now call directly to the new ones.

Move to the `git_error` name in the internal API for error-related
functions.

Next to including several files, our "common.h" header also declares
various macros which are then used throughout the project. As such, we
have to make sure to always include this file first in all
implementation files. Otherwise, we might encounter problems or even
silent behavioural differences due to macros or defines not being
defined as they should be. So in fact, our header and implementation
files should make sure to always include "common.h" first.

This commit does so by establishing a common include pattern. Header
files inside of "src" will now always include "common.h" as its first
other file, separated by a newline from all the other includes to make
it stand out as special. There are two cases for the implementation
files. If they do have a matching header file, they will always include
this one first, leading to "common.h" being transitively included as
first file. If they do not have a matching header file, they instead
include "common.h" as first file themselves.

This fixes the outlined problems and will become our standard practice
for header and source files inside of the "src/" from now on.

The recent introduction of the commondir variable of a repository
requires callers to distinguish whether their files are part of
the dot-git directory or the common directory shared between
multpile worktrees. In order to take the burden from callers and
unify knowledge on which files reside where, the
`git_repository_item_path` function has been introduced which
encapsulate this knowledge.

Modify most existing callers of `git_repository_path` to use
`git_repository_item_path` instead, thus making them implicitly
aware of the common directory.

When an error state is an OOM, make sure that we treat is specially
and do not try to free it.

We use heuristics to make a decent guess at when we can save time and
space by linking object files during a clone. Unfortunately checking the
device id isn't enough, as those would be the same during e.g. a bind-mount,
but the OS still does not allow us to link between mounts of the same
filesystem.

If we fail to perform the links, fall back to copying the contents into
a new file as a last attempt.

It has now become a no-op, so remove the function and all references to
it.

The base refspecs changing can be a cause of confusion as to what is the
current base refspec set and complicate saving the remote's
configuration.

Change `git_remote_add_{fetch,push}()` to update the configuration
instead of an instance.

This finally makes `git_remote_save()` a no-op, it will be removed in a
later commit.

While this will rarely be different from the default, having it in the
remote adds yet another setting it has to keep around and can affect its
behaviour. Move it to the options.

Having the setting be different from calling its actions was not a great
idea and made for the sake of the wrong convenience.

Instead of that, accept either fetch options, push options or the
callbacks when dealing with the remote. The fetch options are currently
only the callbacks, but more options will be moved from setters and
getters on the remote to the options.

This does mean passing the same struct along the different functions but
the typical use-case will only call git_remote_fetch() or
git_remote_push() and so won't notice much difference.

We want to use the "checkout: moving from ..." message in order to let
git know when a change of branch has happened. Make the convenience
functions for this goal write this message.

This namespace is about behaving like git's branch command, so let's do
exactly that instead of taking a reflog message.

This override is still available via the reference namespace.