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.

Using a `git_oid *` in filter options was a mistake; it is a deviation
from our typical pattern, and callers in some languages that GC may need
very special treatment in order to pass both an options structure and a
pointer outside of it.

The filter's proxy_stream is used to adapt filters that only provided an
`apply` function into a `stream` function.  Make this internal to the
library instead of private to the filter file.  This will allow the
filters to use it directly, instead of relying on the filter
functionality to do the proxying.

Provide a mechanism to filter using attribute data from a specific
commit (making use of `GIT_ATTR_CHECK_INCLUDE_COMMIT`).

Allow filter users to provide an options structure instead of simply
flags.  This allows for future growth for filter options.

Filters use a short-lived structure to keep state during an operation to
allow for caching and avoid unnecessary reallocations.  This was
previously called the "filter options", despite the fact that they
contain no configurable options.  Rename them to a "filter session" in
keeping with an "attribute session", which more accurately describes
their use (and allows us to create "filter options" in the future).

Allow more advanced attribute queries using a `git_attr_options`, and
extended functions to use it.  Presently there is no additional
configuration in a `git_attr_options` beyond the flags, but this is for
future growth.

Introduce `git_filter_list__convert_buf` which behaves like the old
implementation of `git_filter_list__apply_data`, where it might move the
input data buffer over into the output data buffer space for efficiency.

This new implementation will do so in a more predictible way, always
freeing the given input buffer (either moving it to the output buffer or
filtering it into the output buffer first).

Convert internal users to it.

Deprecate `git_filter_list_apply_to_data` as it takes user input as a
`git_buf`.  Users should use `git_filter_list_apply_to_buffer` instead.

Provide a filter application mechanism that takes a user-provided string
and length, instead of a `git_buf`.

The API `git_filter_list_apply_to_data` shares data between its out and
in parameters to avoid unnecessarily copying it when there are no
filters to apply.  However, it does so in a manner that is potentially
confusing, leaving both `git_buf`s populated with data.  This is risky
for end-users who have to know how to deal with this.  Instead, we
remove this optimization - users who want to avoid unnecessary copies
can use the longstanding streaming API or check the filter status before
invoking the filters.

`git_filter_list_stream_data` takes user input in a `git_buf`.
`git_buf` should only be used when libgit2 itself needs to allocate data
and returned to a user that they can free when they wish.  Replace it
with `git_filter_list_stream_buffer` that takes a data buffer and
length.

`git_buf_sanitize` is called with user-input, and wants to sanity-check
that input.  Allow it to return a value if the input was malformed in a
way that we cannot cope.

Provide a mechanism for system components to register for initialization
and shutdown of the libgit2 runtime.

We've accumulated quite some functions which are never used outside of
their respective code unit, but which are lacking the `static` keyword.
Add it to reduce their linkage scope and allow the compiler to optimize
better.

Instead of using a signed type (`off_t`) use a new `git_object_size_t`
for the sizes of objects.

When `GIT_FILTER_ATTRIBUTES_FROM_HEAD` is specified, configure the
filter to read filter attributes from `gitattributes` files that are
checked in to the repository at the HEAD revision.  This passes the flag
`GIT_ATTR_CHECK_INCLUDE_HEAD` to the attribute reading functions.

Allow system-wide attributes (the ones specified in
`/etc/gitattributes`) to be ignored if the flag
`GIT_FILTER_NO_SYSTEM_ATTRIBUTES` is specified.

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.

Our enumeration values are not generally suffixed with `T`.  Further,
our enumeration names are generally more descriptive.

The only function that is named `issomething` (without underscore) was
`git_oid_iszero`.  Rename it to `git_oid_is_zero` for consistency with
the rest of the library.

Validate that the return value of the read is not less than INT_MAX,
then cast.

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

When git_filter_apply_fn callback returns a error while smudging proxy_stream_close
ends up returning without closing the stream. This is turn makes blob_content_to_file
crash as it asserts the stream being closed whether there are errors or not.

Closing the target stream on error fixes this problem.

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.

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.

Error messages should be sentence fragments, and therefore:

1. Should not begin with a capital letter,
2. Should not conclude with punctuation, and
3. Should not end a sentence and begin a new one

Previously we would set the global filter registry structure before
adding filters to the structure, without a lock, which is quite racy.
Now, register default filters during global registration and use an
rwlock to read and write the filter registry (as appopriate).

When the stream list init or write fail, we must also make sure to close
the stream, as that's the function contract.

Allow custom filters with wildcard attributes, so that clients
can support some random `filter=foo` in a .gitattributes and look
up the corresponding smudge/clean commands in the configuration file.

`git_filter_list_contains` can be used to query a filter list to
determine if a given filter will be run.

When we hit an error writing to the next stream from a file, we jump to
'done' which currently skips over closing the file descriptor.

Make sure to close the descriptor if it has been set to a valid value.