str: git_str_free is never a function

path: refactor utility path functions

Support checking for object existence without refresh

Document that `git_odb` is thread-safe

Commit 4ae41f9c made `git_odb`
race-free, and added internal locking. Update `docs/threading.md`
accordingly, so that APIs built atop libgit2 (e.g. language bindings)
can count on this.

Teach `git_path_is_valid` to respect `core.longpaths`.  Add helper
methods to validate length and set the error message appropriately.

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.

To accommodate less capable compilers.

Co-authored-by: Peter Pettersson <85582231+boretrk@users.noreply.github.com>

Add optional refreshing in the fake backend, and count the number of
refresh calls if enabled.

Looking up a non-existent object currently always invokes
`git_odb_refresh`. If looking up a large batch of objects, many of which
may legitimately not exist, this will repeatedly refresh the ODB to no
avail.

Add a `git_odb_exists_ext` that accepts flags controlling the ODB
lookup, and add a flag to suppress the refresh. This allows the user to
control if and when they refresh (for instance, refreshing once before
starting the batch).

Commit b1a6c316 moved auto-refresh into
the pack backend, and added a comment accordingly. Commit
43820f20 moved auto-refresh back *out*
of backends into the ODB layer, but didn't update the comment.

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