Add a `git_str` based validity check; the existing `git_path_is_valid`
defers to it.

Provide a mechanism for users to limit the number of characters that are
examined; `git_fs_path_str_is_valid` and friends will only examine up to
`str->size` bytes.

`git_fs_path_is_valid` delegates to these new functions by passing
`SIZE_MAX` (instead of doing a `strlen`), which is a sentinel value
meaning "look for a NUL terminator".

Since we're returning a boolean about validation, the name is more
properly "is valid".

Since we're returning a boolean about validation, the name is more
properly "is valid".

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).

ci: only update docs on push

Only update the documentation on a `push`.  We were previously updating the documentation only when not in a `pull_request`, which meant that we would push documentation updates in manual build triggers.

libgit2_clar is now libgit2_tests

in #6083 the test runner was renamed to libgit2_tests,
but not all references to the old name were updated.
this change changes all of them to use the new name.

cmake: cleanups and consistency

Ensure that we always use lowercase function names, and that we do not
have spaces preceding open parentheses, for consistency.

The `STDCALL` option was removed; remove the (unreachable) error
message.

There's no need to make tracing opt-in; it should always be included.

macOS may support ENABLE_REPRODUCIBLE_BUILDS, allow users to opt-in to
it. (Especially since ENABLE_REPRODUCIBLE_BUILDS is not the default.)

Nobody knows what CLAR is.  The test building option should be
`BUILD_TESTS`.

`git_buf`: now a public-only API (`git_str` is our internal API)

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.

We have been inconsistent about the way that we handle `git_buf`s
provided by users.  _Usually_ we require that it has been properly
initialized with `GIT_BUF_INIT`, but _sometimes_ we simply overwrite
the data in it regardless.  And even more rarely, we will grow a
user-provided buffer and concatenate data onto it (see
`git_diff_format_email`).

Document the path forward for `git_buf`, which is that we always
require that the buffer is intitialized with `GIT_BUF_INIT`.

`git_diff_format_email` will be kept backward compatible but users
are encouraged to switch to the new `git_email` APIs.

hash: separate hashes and git_oid

git's default rename limit is 1000, ours should match.

In `git_futils_readbuffer_updated`, always take a particular hash
instead of a `git_oid`.  This lets us change the checksum algorithm
independently of `git_oid` usage.

Separate the concerns of the hash functions from the git_oid functions.
The git_oid structure will need to understand either SHA1 or SHA256; the
hash functions should only deal with the appropriate one of these.

examples: Free the git_config and git_config_entry after use

oidarray: introduce `git_oidarray_dispose`

buf: common_prefix takes a string array

`git_strarray` is a public-facing type.  Change
`git_buf_text_common_prefix` to not use it, and just take an array of
strings instead.

Since users are disposing the _contents_ of the oidarray, not freeing
the oidarray itself, the proper cleanup function is
`git_oidarray_dispose`.  Deprecate `git_oidarray_free`.