This is pretty useful in avoiding races: I want to create a ref only if
it doesn't already exist. I can't check first because of TOCTOU -- by
the time I finish the check, someone else might have already created
the ref. And I can't take a lock because then I can't do the create,
since the create expects to take the lock.
The semantics are inspired by git update-ref, which allows an all-zero old
value to mean that the ref must not exist.
Provide a function that can check reference name validity but can also
signal when an error occurs. Use the name "name_is_valid", which is
more suggestive of checking a given name, rather than "is_valid_name",
which suggests that the function checks the validity of the current
reference's name.
The C standard does not specify whether an enum is a signed or unsigned
type. Obviously, any enum that includes negative values _must_ be
signed, but if all values are positive then the compiler is free to
choose signed or unsigned.
Thus, by changing the type signatures to `git_object_t` and declaring
the old `GIT_OBJ_` values as a signed or unsigned int, we risk a
mismatch between what the compiler has chosen for a `git_object_t`'s
type and our type declaration.
Thus, we declare the deprecated values as the enum instead of guessing.
Since we now always build the library with cdecl calling conventions,
our callbacks should be decorated as such so that users will not be able
to provide callbacks defined with other calling conventions.
The `GIT_CALLBACK` macro will inject the `__cdecl` attribute as
appropriate.
Update the reference type names from an abbreviation (`git_ref`) to use
the fullname (`git_reference`). This ensures that we are consistent
with our naming for reference types and functions throughout the
library.
The previous names are now marked as deprecated.
We have no need to take a non-const reference. This does involve some other work
to make sure we don't mix const and non-const variables, but by splitting what
we want each variable to do we can also simplify the logic for when we do want
to free a new reference we might have allocated.
git_object_t is the future; update the public API to use it. This will
also ensure that we can build our tests which make use of the old API
without modification (and without compiler warnings).
References passed to the callback function of `git_reference_foreach`
are expected to be owned by the callback. As such, they are never being
freed by `git_reference_foreach`, but will have to be freed by the
caller. This small detail is never mentioned in the function's
documentation, though, making it easy to get wrong. Document this to
make it discoverable.
The signature for the reflog is not something which changes
dynamically. Almost all uses will be NULL, since we want for the
repository's default identity to be used, making it noise.
In order to allow for changing the identity, we instead provide
git_repository_set_ident() and git_repository_ident() which allow a user
to override the choice of signature.
This makes them show up in the reference, even if the text itself isn't
the most descriptive.
These have been found with
grep -Przon '\n\ntypedef struct.*?\{' -- include
grep -Przon '\n\ntypedef enum.*?\{' -- include
Change the name to _matching() intead of _if(), and force _set_target()
to be a conditional update. If the user doesn't care about the old
value, they should use git_reference_create().
Any well-behaved program should write a descriptive message to the
reflog whenever it updates a reference. Let's make this more prominent
by removing the version without the reflog parameters.
The frontend used to look at the file directly, but that's obviously not
the right thing to do. Expose it on the backend and use that function
instead.
Before these changes, looking up a reference would return the
same precomposed or decomposed form of the reference name that
was used to look it up, so on MacOS which ignores the difference
between the two, a single reference could be looked up either way
and git_reference_name would return the form of the name that was
used to look it up! This change makes lookup always return the
precomposed name if core.precomposeunicode is set regardless of
which version was used to look it up. The reference iterator was
already returning the precomposed form from earlier work.
This also updates the CMakeLists.txt rules for enabling iconv
usage because the clar tests for this code were actually not being
activated properly with the old version.
Finally, this moves git_repository_reset_filesystem from include/
git2/repository.h to include/git2/sys/repository.h since it is not
really a function that normal library users should have to think
about very often.
Fixed a few header @param and @return typos with the help of -Wdocumentation in Xcode.
The following warnings have not been fixed:
common.h:213 - Not sure how the documentation format is for '...'
notes.h:102 - Correct @param name but empty text
notes.h:111 - Correct @param name but empty text
pack.h:140 - @return missing text
pack.h:148 - @return missing text
