Ything-RepoMirrors/libgit2
2
0
Fork 0
mirror of https://github.com/libgit2/libgit2.git synced 2026-01-25 02:56:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into ssh

Browse Source
This commit is contained in:
Edward Thomson
2024-12-13 23:32:32 +00:00
parent bef4b73871 c642ef9d4c
commit 8049f00e3b
116 changed files with 5425 additions and 597 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
.github/workflows/documentation.yml vendored Normal file
View File

@@ -0,0 +1,78 @@
# Update the www.libgit2.org reference documentation
name: Generate Documentation
on:
push:
branches: [ main, maint/* ]
release:
workflow_dispatch:
inputs:
force:
description: 'Force rebuild'
type: boolean
required: true
concurrency:
group: documentation
permissions:
contents: read
jobs:
documentation:
name: "Generate documentation"
runs-on: "ubuntu-latest"
steps:
- name: Check out source repository
uses: actions/checkout@v4
with:
path: source
fetch-depth: 0
- name: Check out documentation repository
uses: actions/checkout@v4
with:
repository: libgit2/www.libgit2.org
path: www
fetch-depth: 0
ssh-key: ${{ secrets.DOCS_PUBLISH_KEY }}
- name: Prepare branches
run: |
if [ "$(git rev-parse --abbrev-ref HEAD)" != "main" ]; then
git branch --track main origin/main
fi
for a in $(git branch -r --list 'origin/maint/*' | sed -e "s/^ origin\///"); do
git branch --track "$a" "origin/$a"
done
working-directory: source
- name: Generate documentation
run: |
args=""
if [ "${{ inputs.force }}" = "true" ]; then
args="--force"
fi
npm install
./generate --verbose $args ../.. ../../../www/docs
working-directory: source/script/api-docs
- name: Examine changes
run: |
if [ -n "$(git diff --name-only)" ]; then
echo "changes=true" >> $GITHUB_OUTPUT
else
echo "changes=false" >> $GITHUB_OUTPUT
fi
id: check
working-directory: www
- name: Publish documentation
run: |
DATE=$(date +"%Y-%m-%d")
git config user.name 'Documentation Site Generator'
git config user.email 'libgit2@users.noreply.github.com'
git add .
git commit -m"Documentation update ${DATE}"
git push origin main
if: steps.check.outputs.changes == 'true'
working-directory: www

60
.github/workflows/main.yml vendored
View File

@@ -233,6 +233,17 @@ jobs:
name: test-results-${{ matrix.platform.id }}
path: build/results_*.xml
documentation:
name: Validate documentation
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Validate documentation
run: |
(cd script/api-docs && npm install)
script/api-docs/api-generator.js --validate-only --strict --deprecate-hard .
test_results:
name: Test results
needs: [ build ]
@@ -245,52 +256,3 @@ jobs:
uses: test-summary/action@v2
with:
paths: 'test-results-*/*.xml'
# Generate documentation using docurium. We'll upload the documentation
# as a build artifact so that it can be reviewed as part of a pull
# request or in a forked build. For CI builds in the main repository's
# main branch, we'll push the gh-pages branch back up so that it is
# published to our documentation site.
documentation:
name: Generate documentation
if: success() || failure()
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
with:
path: source
fetch-depth: 0
- name: Set up container
uses: ./source/.github/actions/download-or-build-container
with:
registry: ${{ env.docker-registry }}
config-path: ${{ env.docker-config-path }}
container: docurium
github_token: ${{ secrets.github_token }}
dockerfile: ${{ matrix.platform.container.dockerfile }}
- name: Generate documentation
working-directory: source
run: |
git config user.name 'Documentation Generation'
git config user.email 'libgit2@users.noreply.github.com'
git branch gh-pages origin/gh-pages
docker login https://${{ env.docker-registry }} -u ${{ github.actor }} -p ${{ github.token }}
docker run \
--rm \
-v "$(pwd):/home/libgit2" \
-w /home/libgit2 \
${{ env.docker-registry }}/${{ github.repository }}/docurium:latest \
cm doc api.docurium
git checkout gh-pages
zip --exclude .git/\* --exclude .gitignore --exclude .gitattributes -r api-documentation.zip .
- uses: actions/upload-artifact@v4
name: Upload artifact
with:
name: api-documentation
path: source/api-documentation.zip
- name: Push documentation branch
working-directory: source
run: git push origin gh-pages
if: github.event_name == 'push' && github.repository == 'libgit2/libgit2'

17
include/git2/annotated_commit.h
View File

@@ -13,9 +13,16 @@
/**
* @file git2/annotated_commit.h
* @brief Git annotated commit routines
* @brief A commit and information about how it was looked up by the user.
* @defgroup git_annotated_commit Git annotated commit routines
* @ingroup Git
*
* An "annotated commit" is a commit that contains information about
* how the commit was resolved, which can be used for maintaining the
* user's "intent" through commands like merge and rebase. For example,
* if a user wants to "merge HEAD" then an annotated commit is used to
* both contain the HEAD commit _and_ the fact that it was resolved as
* the HEAD ref.
* @{
*/
GIT_BEGIN_DECL
@@ -25,7 +32,7 @@ GIT_BEGIN_DECL
* The resulting git_annotated_commit must be freed with
* `git_annotated_commit_free`.
*
* @param out pointer to store the git_annotated_commit result in
* @param[out] out pointer to store the git_annotated_commit result in
* @param repo repository that contains the given reference
* @param ref reference to use to lookup the git_annotated_commit
* @return 0 on success or error code
@@ -40,7 +47,7 @@ GIT_EXTERN(int) git_annotated_commit_from_ref(
* The resulting git_annotated_commit must be freed with
* `git_annotated_commit_free`.
*
* @param out pointer to store the git_annotated_commit result in
* @param[out] out pointer to store the git_annotated_commit result in
* @param repo repository that contains the given commit
* @param branch_name name of the (remote) branch
* @param remote_url url of the remote
@@ -67,7 +74,7 @@ GIT_EXTERN(int) git_annotated_commit_from_fetchhead(
* most specific function (eg `git_annotated_commit_from_ref`)
* instead of this one when that data is known.
*
* @param out pointer to store the git_annotated_commit result in
* @param[out] out pointer to store the git_annotated_commit result in
* @param repo repository that contains the given commit
* @param id the commit object id to lookup
* @return 0 on success or error code
@@ -84,7 +91,7 @@ GIT_EXTERN(int) git_annotated_commit_lookup(
* http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for
* information on the syntax accepted.
*
* @param out pointer to store the git_annotated_commit result in
* @param[out] out pointer to store the git_annotated_commit result in
* @param repo repository that contains the given commit
* @param revspec the extended sha syntax string to use to lookup the commit
* @return 0 on success or error code

33
include/git2/apply.h
View File

@@ -14,9 +14,12 @@
/**
* @file git2/apply.h
* @brief Git patch application routines
* @brief Apply patches to the working directory or index
* @defgroup git_apply Git patch application routines
* @ingroup Git
*
* Mechanisms to apply a patch to the index, the working directory,
* or both.
* @{
*/
GIT_BEGIN_DECL
@@ -57,7 +60,15 @@ typedef int GIT_CALLBACK(git_apply_hunk_cb)(
const git_diff_hunk *hunk,
void *payload);
/** Flags controlling the behavior of git_apply */
/**
* Flags controlling the behavior of `git_apply`.
*
* When the callback:
* - returns < 0, the apply process will be aborted.
* - returns > 0, the hunk will not be applied, but the apply process
* continues
* - returns 0, the hunk is applied, and the apply process continues.
*/
typedef enum {
/**
* Don't actually make changes, just test that the patch applies.
@@ -67,12 +78,19 @@ typedef enum {
} git_apply_flags_t;
/**
* Apply options structure
* Apply options structure.
*
* When the callback:
* - returns < 0, the apply process will be aborted.
* - returns > 0, the hunk will not be applied, but the apply process
* continues
* - returns 0, the hunk is applied, and the apply process continues.
*
* Initialize with `GIT_APPLY_OPTIONS_INIT`. Alternatively, you can
* use `git_apply_options_init`.
*
* @see git_apply_to_tree, git_apply
* @see git_apply_to_tree
* @see git_apply
*/
typedef struct {
unsigned int version; /**< The version */
@@ -83,14 +101,17 @@ typedef struct {
/** When applying a patch, callback that will be made per hunk. */
git_apply_hunk_cb hunk_cb;
/** Payload passed to both delta_cb & hunk_cb. */
/** Payload passed to both `delta_cb` & `hunk_cb`. */
void *payload;
/** Bitmask of git_apply_flags_t */
/** Bitmask of `git_apply_flags_t` */
unsigned int flags;
} git_apply_options;
/** Current version for the `git_apply_options` structure */
#define GIT_APPLY_OPTIONS_VERSION 1
/** Static constructor for `git_apply_options` */
#define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION}
/**

17
include/git2/attr.h
View File

@@ -12,9 +12,13 @@
/**
* @file git2/attr.h
* @brief Git attribute management routines
* @brief Attribute management routines
* @defgroup git_attr Git attribute management routines
* @ingroup Git
*
* Attributes specify additional information about how git should
* handle particular paths - for example, they may indicate whether
* a particular filter is applied, like LFS or line ending conversions.
* @{
*/
GIT_BEGIN_DECL
@@ -114,8 +118,12 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr);
* use index only for creating archives or for a bare repo (if an
* index has been specified for the bare repo).
*/
/** Examine attribute in working directory, then index */
#define GIT_ATTR_CHECK_FILE_THEN_INDEX 0
/** Examine attribute in index, then working directory */
#define GIT_ATTR_CHECK_INDEX_THEN_FILE 1
/** Examine attributes only in the index */
#define GIT_ATTR_CHECK_INDEX_ONLY 2
/**
@@ -132,8 +140,12 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr);
* Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes
* from a `.gitattributes` file in a specific commit.
*/
/** Ignore system attributes */
#define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2)
/** Honor `.gitattributes` in the HEAD revision */
#define GIT_ATTR_CHECK_INCLUDE_HEAD (1 << 3)
/** Honor `.gitattributes` in a specific commit */
#define GIT_ATTR_CHECK_INCLUDE_COMMIT (1 << 4)
/**
@@ -158,7 +170,10 @@ typedef struct {
git_oid attr_commit_id;
} git_attr_options;
/** Current version for the `git_attr_options` structure */
#define GIT_ATTR_OPTIONS_VERSION 1
/** Static constructor for `git_attr_options` */
#define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION}
/**

10
include/git2/blame.h
View File

@@ -13,9 +13,14 @@
/**
* @file git2/blame.h
* @brief Git blame routines
* @brief Specify a file's most recent changes per-line
* @defgroup git_blame Git blame routines
* @ingroup Git
*
* Producing a "blame" (or "annotated history") decorates individual
* lines in a file with the commit that introduced that particular line
* of changes. This can be useful to indicate when and why a particular
* change was made.
* @{
*/
GIT_BEGIN_DECL
@@ -122,7 +127,10 @@ typedef struct git_blame_options {
size_t max_line;
} git_blame_options;
/** Current version for the `git_blame_options` structure */
#define GIT_BLAME_OPTIONS_VERSION 1
/** Static constructor for `git_blame_options` */
#define GIT_BLAME_OPTIONS_INIT {GIT_BLAME_OPTIONS_VERSION}
/**

97
include/git2/blob.h
View File

@@ -15,9 +15,13 @@
/**
* @file git2/blob.h
* @brief Git blob load and write routines
* @brief A blob represents a file in a git repository.
* @defgroup git_blob Git blob load and write routines
* @ingroup Git
*
* A blob represents a file in a git repository. This is the raw data
* as it is stored in the repository itself. Blobs may be "filtered"
* to produce the on-disk content.
* @{
*/
GIT_BEGIN_DECL
@@ -25,12 +29,15 @@ GIT_BEGIN_DECL
/**
* Lookup a blob object from a repository.
*
* @param blob pointer to the looked up blob
* @param[out] blob pointer to the looked up blob
* @param repo the repo to use when locating the blob.
* @param id identity of the blob to locate.
* @return 0 or an error code
*/
GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git_oid *id);
GIT_EXTERN(int) git_blob_lookup(
git_blob **blob,
git_repository *repo,
const git_oid *id);
/**
* Lookup a blob object from a repository,
@@ -38,7 +45,7 @@ GIT_EXTERN(int) git_blob_lookup(git_blob **blob, git_repository *repo, const git
*
* @see git_object_lookup_prefix
*
* @param blob pointer to the looked up blob
* @param[out] blob pointer to the looked up blob
* @param repo the repo to use when locating the blob.
* @param id identity of the blob to locate.
* @param len the length of the short identifier
@@ -84,7 +91,7 @@ GIT_EXTERN(git_repository *) git_blob_owner(const git_blob *blob);
* time.
*
* @param blob pointer to the blob
* @return the pointer, or NULL on error
* @return @type `unsigned char *` the pointer, or NULL on error
*/
GIT_EXTERN(const void *) git_blob_rawcontent(const git_blob *blob);
@@ -98,6 +105,8 @@ GIT_EXTERN(git_object_size_t) git_blob_rawsize(const git_blob *blob);
/**
* Flags to control the functionality of `git_blob_filter`.
*
* @flags
*/
typedef enum {
/** When set, filters will not be applied to binary files. */
@@ -128,16 +137,34 @@ typedef enum {
* Initialize with `GIT_BLOB_FILTER_OPTIONS_INIT`. Alternatively, you can
* use `git_blob_filter_options_init`.
*
* @options[version] GIT_BLOB_FILTER_OPTIONS_VERSION
* @options[init_macro] GIT_BLOB_FILTER_OPTIONS_INIT
* @options[init_function] git_blob_filter_options_init
*/
typedef struct {
/** Version number of the options structure. */
int version;
/** Flags to control the filtering process, see `git_blob_filter_flag_t` above */
/**
* Flags to control the filtering process, see `git_blob_filter_flag_t` above.
*
* @type[flags] git_blob_filter_flag_t
*/
uint32_t flags;
#ifdef GIT_DEPRECATE_HARD
/**
* Unused and reserved for ABI compatibility.
*
* @deprecated this value should not be set
*/
void *reserved;
#else
/**
* This value is unused and reserved for API compatibility.
*
* @deprecated this value should not be set
*/
git_oid *commit_id;
#endif
@@ -148,8 +175,18 @@ typedef struct {
git_oid attr_commit_id;
} git_blob_filter_options;
/**
* The current version number for the `git_blob_filter_options` structure ABI.
*/
#define GIT_BLOB_FILTER_OPTIONS_VERSION 1
#define GIT_BLOB_FILTER_OPTIONS_INIT {GIT_BLOB_FILTER_OPTIONS_VERSION, GIT_BLOB_FILTER_CHECK_FOR_BINARY}
/**
* The default values for `git_blob_filter_options`.
*/
#define GIT_BLOB_FILTER_OPTIONS_INIT { \
GIT_BLOB_FILTER_OPTIONS_VERSION, \
GIT_BLOB_FILTER_CHECK_FOR_BINARY \
}
/**
* Initialize git_blob_filter_options structure
@@ -158,10 +195,12 @@ typedef struct {
* to creating an instance with `GIT_BLOB_FILTER_OPTIONS_INIT`.
*
* @param opts The `git_blob_filter_options` struct to initialize.
* @param version The struct version; pass `GIT_BLOB_FILTER_OPTIONS_VERSION`.
* @param version The struct version; pass GIT_BLOB_FILTER_OPTIONS_VERSION
* @return Zero on success; -1 on failure.
*/
GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsigned int version);
GIT_EXTERN(int) git_blob_filter_options_init(
git_blob_filter_options *opts,
unsigned int version);
/**
* Get a buffer with the filtered content of a blob.
@@ -171,7 +210,7 @@ GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsi
* CRLF filtering or other types of changes depending on the file
* attributes set for the blob and the content detected in it.
*
* The output is written into a `git_buf` which the caller must free
* The output is written into a `git_buf` which the caller must dispose
* when done (via `git_buf_dispose`).
*
* If no filters need to be applied, then the `out` buffer will just
@@ -183,7 +222,7 @@ GIT_EXTERN(int) git_blob_filter_options_init(git_blob_filter_options *opts, unsi
* @param blob Pointer to the blob
* @param as_path Path used for file attribute lookups, etc.
* @param opts Options to use for filtering the blob
* @return 0 on success or an error code
* @return @type[enum] git_error_code 0 on success or an error code
*/
GIT_EXTERN(int) git_blob_filter(
git_buf *out,
@@ -192,10 +231,10 @@ GIT_EXTERN(int) git_blob_filter(
git_blob_filter_options *opts);
/**
* Read a file from the working folder of a repository
* and write it to the Object Database as a loose blob
* Read a file from the working folder of a repository and write it
* to the object database.
*
* @param id return the id of the written blob
* @param[out] id return the id of the written blob
* @param repo repository where the blob will be written.
* this repository cannot be bare
* @param relative_path file from which the blob will be created,
@@ -205,19 +244,23 @@ GIT_EXTERN(int) git_blob_filter(
GIT_EXTERN(int) git_blob_create_from_workdir(git_oid *id, git_repository *repo, const char *relative_path);
/**
* Read a file from the filesystem and write its content
* to the Object Database as a loose blob
* Read a file from the filesystem (not necessarily inside the
* working folder of the repository) and write it to the object
* database.
*
* @param id return the id of the written blob
* @param[out] id return the id of the written blob
* @param repo repository where the blob will be written.
* this repository can be bare or not
* @param path file from which the blob will be created
* @return 0 or an error code
*/
GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, const char *path);
GIT_EXTERN(int) git_blob_create_from_disk(
git_oid *id,
git_repository *repo,
const char *path);
/**
* Create a stream to write a new blob into the object db
* Create a stream to write a new blob into the object database.
*
* This function may need to buffer the data on disk and will in
* general not be the right choice if you know the size of the data
@@ -234,7 +277,7 @@ GIT_EXTERN(int) git_blob_create_from_disk(git_oid *id, git_repository *repo, con
* what git filters should be applied to the object before it is written
* to the object database.
*
* @param out the stream into which to write
* @param[out] out the stream into which to write
* @param repo Repository where the blob will be written.
* This repository can be bare or not.
* @param hintpath If not NULL, will be used to select data filters
@@ -247,11 +290,11 @@ GIT_EXTERN(int) git_blob_create_from_stream(
const char *hintpath);
/**
* Close the stream and write the blob to the object db
* Close the stream and finalize writing the blob to the object database.
*
* The stream will be closed and freed.
*
* @param out the id of the new blob
* @param[out] out the id of the new blob
* @param stream the stream to close
* @return 0 or an error code
*/
@@ -260,9 +303,9 @@ GIT_EXTERN(int) git_blob_create_from_stream_commit(
git_writestream *stream);
/**
* Write an in-memory buffer to the ODB as a blob
* Write an in-memory buffer to the object database as a blob.
*
* @param id return the id of the written blob
* @param[out] id return the id of the written blob
* @param repo repository where the blob will be written
* @param buffer data to be written into the blob
* @param len length of the data
@@ -272,14 +315,14 @@ GIT_EXTERN(int) git_blob_create_from_buffer(
git_oid *id, git_repository *repo, const void *buffer, size_t len);
/**
* Determine if the blob content is most certainly binary or not.
* Determine if the blob content is most likely binary or not.
*
* The heuristic used to guess if a file is binary is taken from core git:
* Searching for NUL bytes and looking for a reasonable ratio of printable
* to non-printable characters among the first 8000 bytes.
*
* @param blob The blob which content should be analyzed
* @return 1 if the content of the blob is detected
* @return @type bool 1 if the content of the blob is detected
* as binary; 0 otherwise.
*/
GIT_EXTERN(int) git_blob_is_binary(const git_blob *blob);
@@ -300,7 +343,7 @@ GIT_EXTERN(int) git_blob_data_is_binary(const char *data, size_t len);
* Create an in-memory copy of a blob. The copy must be explicitly
* free'd or it will leak.
*
* @param out Pointer to store the copy of the object
* @param[out] out Pointer to store the copy of the object
* @param source Original object to copy
* @return 0.
*/

37
include/git2/branch.h
View File

@@ -13,9 +13,15 @@
/**
* @file git2/branch.h
* @brief Git branch parsing routines
* @brief Branch creation and handling
* @defgroup git_branch Git branch management
* @ingroup Git
*
* A branch is a specific type of reference, at any particular time,
* a git working directory typically is said to have a branch "checked out",
* meaning that commits that are created will be made "on" a branch.
* This occurs by updating the branch reference to point to the new
* commit. The checked out branch is indicated by the `HEAD` meta-ref.
* @{
*/
GIT_BEGIN_DECL
@@ -33,18 +39,13 @@ GIT_BEGIN_DECL
* See `git_tag_create()` for rules about valid names.
*
* @param out Pointer where to store the underlying reference.
*
* @param repo the repository to create the branch in.
*
* @param branch_name Name for the branch; this name is
* validated for consistency. It should also not conflict with
* an already existing branch name.
*
* validated for consistency. It should also not conflict with
* an already existing branch name.
* @param target Commit to which this branch should point. This object
* must belong to the given `repo`.
*
* must belong to the given `repo`.
* @param force Overwrite existing branch.
*
* @return 0, GIT_EINVALIDSPEC or an error code.
* A proper reference is written in the refs/heads namespace
* pointing to the provided target commit.
@@ -63,15 +64,21 @@ GIT_EXTERN(int) git_branch_create(
* commit, which lets you specify which extended sha syntax string was
* specified by a user, allowing for more exact reflog messages.
*
* See the documentation for `git_branch_create()`.
*
* @see git_branch_create
* @param ref_out Pointer where to store the underlying reference.
* @param repo the repository to create the branch in.
* @param branch_name Name for the branch; this name is
* validated for consistency. It should also not conflict with
* an already existing branch name.
* @param target Annotated commit to which this branch should point. This
* object must belong to the given `repo`.
* @param force Overwrite existing branch.
* @return 0, GIT_EINVALIDSPEC or an error code.
*/
GIT_EXTERN(int) git_branch_create_from_annotated(
git_reference **ref_out,
git_repository *repository,
git_repository *repo,
const char *branch_name,
const git_annotated_commit *commit,
const git_annotated_commit *target,
int force);
/**
@@ -222,7 +229,7 @@ GIT_EXTERN(int) git_branch_upstream(
* @param branch the branch to configure
* @param branch_name remote-tracking or local branch to set as upstream.
*
* @return 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name`
* @return @type git_error_t 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name`
* or an error code
*/
GIT_EXTERN(int) git_branch_set_upstream(

10
include/git2/buffer.h
View File

@@ -11,9 +11,12 @@
/**
* @file git2/buffer.h
* @brief Buffer export structure
*
* @brief A data structure to return data to callers
* @ingroup Git
*
* The `git_buf` buffer is used to return arbitrary data - typically
* strings - to callers. Callers are responsible for freeing the memory
* in a buffer with the `git_buf_dispose` function.
* @{
*/
GIT_BEGIN_DECL
@@ -67,8 +70,7 @@ typedef struct {
*/
GIT_EXTERN(void) git_buf_dispose(git_buf *buffer);
/** @} */
GIT_END_DECL
/** @} */
#endif

3
include/git2/cert.h
View File

@@ -12,7 +12,7 @@
/**
* @file git2/cert.h
* @brief Git certificate objects
* @brief TLS and SSH certificate handling
* @defgroup git_cert Certificate objects
* @ingroup Git
* @{
@@ -169,4 +169,5 @@ typedef struct {
/** @} */
GIT_END_DECL
#endif

61
include/git2/checkout.h
View File

@@ -13,9 +13,13 @@
/**
* @file git2/checkout.h
* @brief Git checkout routines
* @brief Update the contents of the working directory
* @defgroup git_checkout Git checkout routines
* @ingroup Git
*
* Update the contents of the working directory, or a subset of the
* files in the working directory, to point to the data in the index
* or a specific commit.
* @{
*/
GIT_BEGIN_DECL
@@ -103,6 +107,8 @@ GIT_BEGIN_DECL
* files or folders that fold to the same name on case insensitive
* filesystems. This can cause files to retain their existing names
* and write through existing symbolic links.
*
* @flags
*/
typedef enum {
/**
@@ -212,6 +218,8 @@ typedef enum {
* Notification callbacks are made prior to modifying any files on disk,
* so canceling on any notification will still happen prior to any files
* being modified.
*
* @flags
*/
typedef enum {
GIT_CHECKOUT_NOTIFY_NONE = 0,
@@ -253,7 +261,17 @@ typedef struct {
size_t chmod_calls;
} git_checkout_perfdata;
/** Checkout notification callback function */
/**
* Checkout notification callback function.
*
* @param why the notification reason
* @param path the path to the file being checked out
* @param baseline the baseline's diff file information
* @param target the checkout target diff file information
* @param workdir the working directory diff file information
* @param payload the user-supplied callback payload
* @return 0 on success, or an error code
*/
typedef int GIT_CALLBACK(git_checkout_notify_cb)(
git_checkout_notify_t why,
const char *path,
@@ -262,14 +280,26 @@ typedef int GIT_CALLBACK(git_checkout_notify_cb)(
const git_diff_file *workdir,
void *payload);
/** Checkout progress notification function */
/**
* Checkout progress notification function.
*
* @param path the path to the file being checked out
* @param completed_steps number of checkout steps completed
* @param total_steps number of total steps in the checkout process
* @param payload the user-supplied callback payload
*/
typedef void GIT_CALLBACK(git_checkout_progress_cb)(
const char *path,
size_t completed_steps,
size_t total_steps,
void *payload);
/** Checkout perfdata notification function */
/**
* Checkout performance data reporting function.
*
* @param perfdata the performance data for the checkout
* @param payload the user-supplied callback payload
*/
typedef void GIT_CALLBACK(git_checkout_perfdata_cb)(
const git_checkout_perfdata *perfdata,
void *payload);
@@ -280,10 +310,18 @@ typedef void GIT_CALLBACK(git_checkout_perfdata_cb)(
* Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can
* use `git_checkout_options_init`.
*
* @options[version] GIT_CHECKOUT_OPTIONS_VERSION
* @options[init_macro] GIT_CHECKOUT_OPTIONS_INIT
* @options[init_function] git_checkout_options_init
*/
typedef struct git_checkout_options {
unsigned int version; /**< The version */
/**
* Checkout strategy. Default is a safe checkout.
*
* @type[flags] git_checkout_strategy_t
*/
unsigned int checkout_strategy; /**< default will be a safe checkout */
int disable_filters; /**< don't apply filters like CRLF conversion */
@@ -291,7 +329,13 @@ typedef struct git_checkout_options {
unsigned int file_mode; /**< default is 0644 or 0755 as dictated by blob */
int file_open_flags; /**< default is O_CREAT | O_TRUNC | O_WRONLY */
unsigned int notify_flags; /**< see `git_checkout_notify_t` above */
/**
* Checkout notification flags specify what operations the notify
* callback is invoked for.
*
* @type[flags] git_checkout_notify_t
*/
unsigned int notify_flags;
/**
* Optional callback to get notifications on specific file states.
@@ -346,8 +390,12 @@ typedef struct git_checkout_options {
void *perfdata_payload;
} git_checkout_options;
/** Current version for the `git_checkout_options` structure */
#define GIT_CHECKOUT_OPTIONS_VERSION 1
#define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION}
/** Static constructor for `git_checkout_options` */
#define GIT_CHECKOUT_OPTIONS_INIT { GIT_CHECKOUT_OPTIONS_VERSION }
/**
* Initialize git_checkout_options structure
@@ -416,4 +464,5 @@ GIT_EXTERN(int) git_checkout_tree(
/** @} */
GIT_END_DECL
#endif

13
include/git2/cherrypick.h
View File

@@ -13,9 +13,12 @@
/**
* @file git2/cherrypick.h
* @brief Git cherry-pick routines
* @brief Cherry-pick the contents of an individual commit
* @defgroup git_cherrypick Git cherry-pick routines
* @ingroup Git
*
* "Cherry-pick" will attempts to re-apply the changes in an
* individual commit to the current index and working directory.
* @{
*/
GIT_BEGIN_DECL
@@ -33,8 +36,13 @@ typedef struct {
git_checkout_options checkout_opts; /**< Options for the checkout */
} git_cherrypick_options;
/** Current version for the `git_cherrypick_options` structure */
#define GIT_CHERRYPICK_OPTIONS_VERSION 1
#define GIT_CHERRYPICK_OPTIONS_INIT {GIT_CHERRYPICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT}
/** Static constructor for `git_cherrypick_options` */
#define GIT_CHERRYPICK_OPTIONS_INIT { \
GIT_CHERRYPICK_OPTIONS_VERSION, 0, \
GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT }
/**
* Initialize git_cherrypick_options structure
@@ -89,4 +97,3 @@ GIT_EXTERN(int) git_cherrypick(
GIT_END_DECL
#endif

23
include/git2/clone.h
View File

@@ -17,9 +17,13 @@
/**
* @file git2/clone.h
* @brief Git cloning routines
* @brief Clone a remote repository to the local disk
* @defgroup git_clone Git cloning routines
* @ingroup Git
*
* Clone will take a remote repository - located on a remote server
* accessible by HTTPS or SSH, or a repository located elsewhere on
* the local disk - and place a copy in the given local path.
* @{
*/
GIT_BEGIN_DECL
@@ -59,7 +63,7 @@ typedef enum {
* Callers of git_clone may provide a function matching this signature to override
* the remote creation and customization process during a clone operation.
*
* @param out the resulting remote
* @param[out] out the resulting remote
* @param repo the repository in which to create the remote
* @param name the remote's name
* @param url the remote's url
@@ -81,7 +85,7 @@ typedef int GIT_CALLBACK(git_remote_create_cb)(
* to override the repository creation and customization process
* during a clone operation.
*
* @param out the resulting repository
* @param[out] out the resulting repository
* @param path path in which to create the repository
* @param bare whether the repository is bare. This is the value from the clone options
* @param payload payload specified by the options
@@ -99,6 +103,9 @@ typedef int GIT_CALLBACK(git_repository_create_cb)(
* Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can
* use `git_clone_options_init`.
*
* @options[version] GIT_CLONE_OPTIONS_VERSION
* @options[init_macro] GIT_CLONE_OPTIONS_INIT
* @options[init_function] git_clone_options_init
*/
typedef struct git_clone_options {
unsigned int version;
@@ -163,7 +170,10 @@ typedef struct git_clone_options {
void *remote_cb_payload;
} git_clone_options;
/** Current version for the `git_clone_options` structure */
#define GIT_CLONE_OPTIONS_VERSION 1
/** Static constructor for `git_clone_options` */
#define GIT_CLONE_OPTIONS_INIT \
{ GIT_CLONE_OPTIONS_VERSION, \
GIT_CHECKOUT_OPTIONS_INIT, \
@@ -190,7 +200,11 @@ GIT_EXTERN(int) git_clone_options_init(
* git's defaults. You can use the options in the callback to
* customize how these are created.
*
* @param out pointer that will receive the resulting repository object
* Note that the libgit2 library _must_ be initialized using
* `git_libgit2_init` before any APIs can be called, including
* this one.
*
* @param[out] out pointer that will receive the resulting repository object
* @param url the remote repository to clone
* @param local_path local directory to clone to
* @param options configuration options for the clone. If NULL, the
@@ -207,4 +221,5 @@ GIT_EXTERN(int) git_clone(
/** @} */
GIT_END_DECL
#endif

74
include/git2/commit.h
View File

@@ -14,9 +14,13 @@
/**
* @file git2/commit.h
* @brief Git commit parsing, formatting routines
* @brief A representation of a set of changes in the repository
* @defgroup git_commit Git commit parsing, formatting routines
* @ingroup Git
*
* A commit represents a set of changes made to the files within a
* repository, and metadata about who made the changes, and when the
* changes were made.
* @{
*/
GIT_BEGIN_DECL
@@ -380,7 +384,38 @@ GIT_EXTERN(int) git_commit_create(
*
* All other parameters remain the same as `git_commit_create()`.
*
* @see git_commit_create
* @param id Pointer in which to store the OID of the newly created commit
*
* @param repo Repository where to store the commit
*
* @param update_ref If not NULL, name of the reference that
* will be updated to point to this commit. If the reference
* is not direct, it will be resolved to a direct reference.
* Use "HEAD" to update the HEAD of the current branch and
* make it point to this commit. If the reference doesn't
* exist yet, it will be created. If it does exist, the first
* parent must be the tip of this branch.
*
* @param author Signature with author and author time of commit
*
* @param committer Signature with committer and * commit time of commit
*
* @param message_encoding The encoding for the message in the
* commit, represented with a standard encoding name.
* E.g. "UTF-8". If NULL, no encoding header is written and
* UTF-8 is assumed.
*
* @param message Full message for this commit
*
* @param tree An instance of a `git_tree` object that will
* be used as the tree for the commit. This tree object must
* also be owned by the given `repo`.
*
* @param parent_count Number of parents for this commit
*
* @return 0 or an error code
* The created commit will be written to the Object Database and
* the given reference will be updated to point to it
*/
GIT_EXTERN(int) git_commit_create_v(
git_oid *id,
@@ -416,7 +451,10 @@ typedef struct {
const char *message_encoding;
} git_commit_create_options;
/** Current version for the `git_commit_create_options` structure */
#define GIT_COMMIT_CREATE_OPTIONS_VERSION 1
/** Static constructor for `git_commit_create_options` */
#define GIT_COMMIT_CREATE_OPTIONS_INIT { GIT_COMMIT_CREATE_OPTIONS_VERSION }
/**
@@ -456,7 +494,36 @@ GIT_EXTERN(int) git_commit_create_from_stage(
*
* All parameters have the same meanings as in `git_commit_create()`.
*
* @see git_commit_create
* @param id Pointer in which to store the OID of the newly created commit
*
* @param commit_to_amend The commit to amend
*
* @param update_ref If not NULL, name of the reference that
* will be updated to point to this commit. If the reference
* is not direct, it will be resolved to a direct reference.
* Use "HEAD" to update the HEAD of the current branch and
* make it point to this commit. If the reference doesn't
* exist yet, it will be created. If it does exist, the first
* parent must be the tip of this branch.
*
* @param author Signature with author and author time of commit
*
* @param committer Signature with committer and * commit time of commit
*
* @param message_encoding The encoding for the message in the
* commit, represented with a standard encoding name.
* E.g. "UTF-8". If NULL, no encoding header is written and
* UTF-8 is assumed.
*
* @param message Full message for this commit
*
* @param tree An instance of a `git_tree` object that will
* be used as the tree for the commit. This tree object must
* also be owned by the given `repo`.
*
* @return 0 or an error code
* The created commit will be written to the Object Database and
* the given reference will be updated to point to it
*/
GIT_EXTERN(int) git_commit_amend(
git_oid *id,
@@ -604,4 +671,5 @@ GIT_EXTERN(void) git_commitarray_dispose(git_commitarray *array);
/** @} */
GIT_END_DECL
#endif

19
include/git2/common.h
View File

@@ -11,7 +11,9 @@
#include <stdlib.h>
#ifdef __cplusplus
/** Start declarations in C mode for C++ compatibility */
# define GIT_BEGIN_DECL extern "C" {
/** End declarations in C mode */
# define GIT_END_DECL }
#else
/** Start declarations in C mode */
@@ -71,19 +73,19 @@ typedef size_t size_t;
# define GIT_FORMAT_PRINTF(a,b) /* empty */
#endif
#if (defined(_WIN32)) && !defined(__CYGWIN__)
#define GIT_WIN32 1
#endif
#ifdef __amigaos4__
#include <netinet/in.h>
#endif
/**
* @file git2/common.h
* @brief Git common platform definitions
* @brief Base platform functionality
* @defgroup git_common Git common platform definitions
* @ingroup Git
*
* Common platform functionality including introspecting libgit2
* itself - information like how it was built, and the current
* running version.
* @{
*/
@@ -94,10 +96,10 @@ GIT_BEGIN_DECL
* environment variable). A semi-colon ";" is used on Windows and
* AmigaOS, and a colon ":" for all other systems.
*/
#if defined(GIT_WIN32) || defined(AMIGA)
#define GIT_PATH_LIST_SEPARATOR ';'
#if (defined(_WIN32) && !defined(__CYGWIN__)) || defined(AMIGA)
# define GIT_PATH_LIST_SEPARATOR ';'
#else
#define GIT_PATH_LIST_SEPARATOR ':'
# define GIT_PATH_LIST_SEPARATOR ':'
#endif
/**
@@ -538,7 +540,6 @@ typedef enum {
* > to a remote server. Set to 0 to use the system default.
*
* @param option Option key
* @param ... value to set the option
* @return 0 on success, <0 on failure
*/
GIT_EXTERN(int) git_libgit2_opts(int option, ...);

78
include/git2/config.h
View File

@@ -13,9 +13,13 @@
/**
* @file git2/config.h
* @brief Git config management routines
* @brief Per-repository, per-user or per-system configuration
* @defgroup git_config Git config management routines
* @ingroup Git
*
* Git configuration affects the operation of the version control
* system, and can be specified on a per-repository basis, in user
* settings, or at the system level.
* @{
*/
GIT_BEGIN_DECL
@@ -38,37 +42,57 @@ GIT_BEGIN_DECL
*
* git_config_open_default() and git_repository_config() honor those
* priority levels as well.
*
* @see git_config_open_default
* @see git_repository_config
*/
typedef enum {
/** System-wide on Windows, for compatibility with portable git */
/**
* System-wide on Windows, for compatibility with "Portable Git".
*/
GIT_CONFIG_LEVEL_PROGRAMDATA = 1,
/** System-wide configuration file; /etc/gitconfig on Linux systems */
/**
* System-wide configuration file; `/etc/gitconfig` on Linux.
*/
GIT_CONFIG_LEVEL_SYSTEM = 2,
/** XDG compatible configuration file; typically ~/.config/git/config */
/**
* XDG compatible configuration file; typically
* `~/.config/git/config`.
*/
GIT_CONFIG_LEVEL_XDG = 3,
/** User-specific configuration file (also called Global configuration
* file); typically ~/.gitconfig
/**
* Global configuration file is the user-specific configuration;
* typically `~/.gitconfig`.
*/
GIT_CONFIG_LEVEL_GLOBAL = 4,
/** Repository specific configuration file; $WORK_DIR/.git/config on
* non-bare repos
/**
* Local configuration, the repository-specific configuration file;
* typically `$GIT_DIR/config`.
*/
GIT_CONFIG_LEVEL_LOCAL = 5,
/** Worktree specific configuration file; $GIT_DIR/config.worktree
/**
* Worktree-specific configuration; typically
* `$GIT_DIR/config.worktree`.
*/
GIT_CONFIG_LEVEL_WORKTREE = 6,
/** Application specific configuration file; freely defined by applications
/**
* Application-specific configuration file. Callers into libgit2
* can add their own configuration beginning at this level.
*/
GIT_CONFIG_LEVEL_APP = 7,
/** Represents the highest level available config file (i.e. the most
* specific config file available that actually is loaded)
/**
* Not a configuration level; callers can use this value when
* querying configuration levels to specify that they want to
* have data from the highest-level currently configuration.
* This can be used to indicate that callers want the most
* specific config file available that actually is loaded.
*/
GIT_CONFIG_HIGHEST_LEVEL = -1
} git_config_level_t;
@@ -77,13 +101,13 @@ typedef enum {
* An entry in a configuration file
*/
typedef struct git_config_entry {
/** Name of the configuration entry (normalized) */
/** Name of the configuration entry (normalized). */
const char *name;
/** Literal (string) value of the entry */
/** Literal (string) value of the entry. */
const char *value;
/** The type of backend that this entry exists in (eg, "file") */
/** The type of backend that this entry exists in (eg, "file"). */
const char *backend_type;
/**
@@ -92,22 +116,22 @@ typedef struct git_config_entry {
*/
const char *origin_path;
/** Depth of includes where this variable was found */
/** Depth of includes where this variable was found. */
unsigned int include_depth;
/** Configuration level for the file this was found in */
/** Configuration level for the file this was found in. */
git_config_level_t level;
} git_config_entry;
/**
* Free a config entry
* Free a config entry.
*
* @param entry The entry to free.
*/
GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry);
/**
* A config enumeration callback
* A config enumeration callback.
*
* @param entry the entry currently being enumerated
* @param payload a user-specified pointer
@@ -116,7 +140,7 @@ GIT_EXTERN(void) git_config_entry_free(git_config_entry *entry);
typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload);
/**
* An opaque structure for a configuration iterator
* An opaque structure for a configuration iterator.
*/
typedef struct git_config_iterator git_config_iterator;
@@ -241,9 +265,9 @@ GIT_EXTERN(int) git_config_new(git_config **out);
* @param cfg the configuration to add the file to
* @param path path to the configuration file to add
* @param level the priority level of the backend
* @param force replace config file at the given priority level
* @param repo optional repository to allow parsing of
* conditional includes
* @param force replace config file at the given priority level
* @return 0 on success, GIT_EEXISTS when adding more than one file
* for a given priority level (and force_replace set to 0),
* GIT_ENOTFOUND when the file doesn't exist or error code
@@ -305,6 +329,17 @@ GIT_EXTERN(int) git_config_open_level(
*/
GIT_EXTERN(int) git_config_open_global(git_config **out, git_config *config);
/**
* Set the write order for configuration backends. By default, the
* write ordering does not match the read ordering; for example, the
* worktree configuration is a high-priority for reading, but is not
* written to unless explicitly chosen.
*
* @param cfg the configuration to change write order of
* @param levels the ordering of levels for writing
* @param len the length of the levels array
* @return 0 or an error code
*/
GIT_EXTERN(int) git_config_set_writeorder(
git_config *cfg,
git_config_level_t *levels,
@@ -813,4 +848,5 @@ GIT_EXTERN(int) git_config_lock(git_transaction **tx, git_config *cfg);
/** @} */
GIT_END_DECL
#endif

32
include/git2/credential.h
View File

@@ -11,9 +11,12 @@
/**
* @file git2/credential.h
* @brief Git authentication & credential management
* @brief Authentication and credential management
* @defgroup git_credential Authentication & credential management
* @ingroup Git
*
* Credentials specify how to authenticate to a remote system
* over HTTPS or SSH.
* @{
*/
GIT_BEGIN_DECL
@@ -119,7 +122,7 @@ typedef struct git_credential_ssh_custom git_credential_ssh_custom;
* an error. As such, it's easy to get in a loop if you fail to stop providing
* the same incorrect credentials.
*
* @param out The newly created credential object.
* @param[out] out The newly created credential object.
* @param url The resource for which we are demanding a credential.
* @param username_from_url The username that was embedded in a "user\@host"
* remote url, or NULL if not included.
@@ -241,6 +244,18 @@ typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT;
typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE;
#endif
/**
* Callback for interactive SSH credentials.
*
* @param name the name
* @param name_len the length of the name
* @param instruction the authentication instruction
* @param instruction_len the length of the instruction
* @param num_prompts the number of prompts
* @param prompts the prompts
* @param responses the responses
* @param abstract the abstract
*/
typedef void GIT_CALLBACK(git_credential_ssh_interactive_cb)(
const char *name,
int name_len,
@@ -278,6 +293,18 @@ GIT_EXTERN(int) git_credential_ssh_key_from_agent(
git_credential **out,
const char *username);
/**
* Callback for credential signing.
*
* @param session the libssh2 session
* @param sig the signature
* @param sig_len the length of the signature
* @param data the data
* @param data_len the length of the data
* @param abstract the abstract
* @return 0 for success, < 0 to indicate an error, > 0 to indicate
* no credential was acquired
*/
typedef int GIT_CALLBACK(git_credential_sign_cb)(
LIBSSH2_SESSION *session,
unsigned char **sig, size_t *sig_len,
@@ -312,4 +339,5 @@ GIT_EXTERN(int) git_credential_ssh_custom_new(
/** @} */
GIT_END_DECL
#endif

1
include/git2/credential_helpers.h
View File

@@ -50,4 +50,5 @@ GIT_EXTERN(int) git_credential_userpass(
/** @} */
GIT_END_DECL
#endif

118
include/git2/deprecated.h
View File

@@ -52,7 +52,7 @@
/**
* @file git2/deprecated.h
* @brief libgit2 deprecated functions and values
* @brief Deprecated functions and values
* @ingroup Git
* @{
*/
@@ -69,15 +69,23 @@ GIT_BEGIN_DECL
*/
/**@{*/
/** @deprecated use GIT_ATTR_VALUE_UNSPECIFIED */
#define GIT_ATTR_UNSPECIFIED_T GIT_ATTR_VALUE_UNSPECIFIED
/** @deprecated use GIT_ATTR_VALUE_TRUE */
#define GIT_ATTR_TRUE_T GIT_ATTR_VALUE_TRUE
/** @deprecated use GIT_ATTR_VALUE_FALSE */
#define GIT_ATTR_FALSE_T GIT_ATTR_VALUE_FALSE
/** @deprecated use GIT_ATTR_VALUE_STRING */
#define GIT_ATTR_VALUE_T GIT_ATTR_VALUE_STRING
/** @deprecated use GIT_ATTR_IS_TRUE */
#define GIT_ATTR_TRUE(attr) GIT_ATTR_IS_TRUE(attr)
/** @deprecated use GIT_ATTR_IS_FALSE */
#define GIT_ATTR_FALSE(attr) GIT_ATTR_IS_FALSE(attr)
/** @deprecated use GIT_ATTR_IS_UNSPECIFIED */
#define GIT_ATTR_UNSPECIFIED(attr) GIT_ATTR_IS_UNSPECIFIED(attr)
/** @deprecated use git_attr_value_t */
typedef git_attr_value_t git_attr_t;
/**@}*/
@@ -93,6 +101,7 @@ typedef git_attr_value_t git_attr_t;
*/
/**@{*/
/** @deprecated use GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD */
#define GIT_BLOB_FILTER_ATTTRIBUTES_FROM_HEAD GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD
GIT_EXTERN(int) git_blob_create_fromworkdir(git_oid *id, git_repository *repo, const char *relative_path);
@@ -285,11 +294,16 @@ typedef int (*git_commit_signing_cb)(
*/
/**@{*/
/** @deprecated use GIT_CONFIGMAP_FALSE */
#define GIT_CVAR_FALSE GIT_CONFIGMAP_FALSE
/** @deprecated use GIT_CONFIGMAP_TRUE */
#define GIT_CVAR_TRUE GIT_CONFIGMAP_TRUE
/** @deprecated use GIT_CONFIGMAP_INT32 */
#define GIT_CVAR_INT32 GIT_CONFIGMAP_INT32
/** @deprecated use GIT_CONFIGMAP_STRING */
#define GIT_CVAR_STRING GIT_CONFIGMAP_STRING
/** @deprecated use git_cvar_map */
typedef git_configmap git_cvar_map;
/**@}*/
@@ -314,11 +328,12 @@ typedef enum {
/** Don't insert "[PATCH]" in the subject header*/
GIT_DIFF_FORMAT_EMAIL_EXCLUDE_SUBJECT_PATCH_MARKER = (1 << 0)
} git_diff_format_email_flags_t;
/**
* Options for controlling the formatting of the generated e-mail.
*
* @deprecated use `git_email_create_options`
*/
typedef struct {
unsigned int version;
@@ -345,7 +360,9 @@ typedef struct {
const git_signature *author;
} git_diff_format_email_options;
/** @deprecated use `git_email_create_options` */
#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION 1
/** @deprecated use `git_email_create_options` */
#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT {GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION, 0, 1, 1, NULL, NULL, NULL, NULL}
/**
@@ -401,41 +418,75 @@ GIT_EXTERN(int) git_diff_format_email_options_init(
*/
/**@{*/
/** @deprecated use `GIT_ERROR_NONE` */
#define GITERR_NONE GIT_ERROR_NONE
/** @deprecated use `GIT_ERROR_NOMEMORY` */
#define GITERR_NOMEMORY GIT_ERROR_NOMEMORY
/** @deprecated use `GIT_ERROR_OS` */
#define GITERR_OS GIT_ERROR_OS
/** @deprecated use `GIT_ERROR_INVALID` */
#define GITERR_INVALID GIT_ERROR_INVALID
/** @deprecated use `GIT_ERROR_REFERENCE` */
#define GITERR_REFERENCE GIT_ERROR_REFERENCE
/** @deprecated use `GIT_ERROR_ZLIB` */
#define GITERR_ZLIB GIT_ERROR_ZLIB
/** @deprecated use `GIT_ERROR_REPOSITORY` */
#define GITERR_REPOSITORY GIT_ERROR_REPOSITORY
/** @deprecated use `GIT_ERROR_CONFIG` */
#define GITERR_CONFIG GIT_ERROR_CONFIG
/** @deprecated use `GIT_ERROR_REGEX` */
#define GITERR_REGEX GIT_ERROR_REGEX
/** @deprecated use `GIT_ERROR_ODB` */
#define GITERR_ODB GIT_ERROR_ODB
/** @deprecated use `GIT_ERROR_INDEX` */
#define GITERR_INDEX GIT_ERROR_INDEX
/** @deprecated use `GIT_ERROR_OBJECT` */
#define GITERR_OBJECT GIT_ERROR_OBJECT
/** @deprecated use `GIT_ERROR_NET` */
#define GITERR_NET GIT_ERROR_NET
/** @deprecated use `GIT_ERROR_TAG` */
#define GITERR_TAG GIT_ERROR_TAG
/** @deprecated use `GIT_ERROR_TREE` */
#define GITERR_TREE GIT_ERROR_TREE
/** @deprecated use `GIT_ERROR_INDEXER` */
#define GITERR_INDEXER GIT_ERROR_INDEXER
/** @deprecated use `GIT_ERROR_SSL` */
#define GITERR_SSL GIT_ERROR_SSL
/** @deprecated use `GIT_ERROR_SUBMODULE` */
#define GITERR_SUBMODULE GIT_ERROR_SUBMODULE
/** @deprecated use `GIT_ERROR_THREAD` */
#define GITERR_THREAD GIT_ERROR_THREAD
/** @deprecated use `GIT_ERROR_STASH` */
#define GITERR_STASH GIT_ERROR_STASH
/** @deprecated use `GIT_ERROR_CHECKOUT` */
#define GITERR_CHECKOUT GIT_ERROR_CHECKOUT
/** @deprecated use `GIT_ERROR_FETCHHEAD` */
#define GITERR_FETCHHEAD GIT_ERROR_FETCHHEAD
/** @deprecated use `GIT_ERROR_MERGE` */
#define GITERR_MERGE GIT_ERROR_MERGE
/** @deprecated use `GIT_ERROR_SSH` */
#define GITERR_SSH GIT_ERROR_SSH
/** @deprecated use `GIT_ERROR_FILTER` */
#define GITERR_FILTER GIT_ERROR_FILTER
/** @deprecated use `GIT_ERROR_REVERT` */
#define GITERR_REVERT GIT_ERROR_REVERT
/** @deprecated use `GIT_ERROR_CALLBACK` */
#define GITERR_CALLBACK GIT_ERROR_CALLBACK
/** @deprecated use `GIT_ERROR_CHERRYPICK` */
#define GITERR_CHERRYPICK GIT_ERROR_CHERRYPICK
/** @deprecated use `GIT_ERROR_DESCRIBE` */
#define GITERR_DESCRIBE GIT_ERROR_DESCRIBE
/** @deprecated use `GIT_ERROR_REBASE` */
#define GITERR_REBASE GIT_ERROR_REBASE
/** @deprecated use `GIT_ERROR_FILESYSTEM` */
#define GITERR_FILESYSTEM GIT_ERROR_FILESYSTEM
/** @deprecated use `GIT_ERROR_PATCH` */
#define GITERR_PATCH GIT_ERROR_PATCH
/** @deprecated use `GIT_ERROR_WORKTREE` */
#define GITERR_WORKTREE GIT_ERROR_WORKTREE
/** @deprecated use `GIT_ERROR_SHA1` */
#define GITERR_SHA1 GIT_ERROR_SHA1
/** @deprecated use `GIT_ERROR_SHA` */
#define GIT_ERROR_SHA1 GIT_ERROR_SHA
/**
@@ -500,37 +551,63 @@ GIT_EXTERN(void) giterr_set_oom(void);
*/
/**@{*/
/* The git_idxentry_extended_flag_t enum */
/** @deprecated use `GIT_INDEX_ENTRY_NAMEMASK` */
#define GIT_IDXENTRY_NAMEMASK GIT_INDEX_ENTRY_NAMEMASK
/** @deprecated use `GIT_INDEX_ENTRY_STAGEMASK` */
#define GIT_IDXENTRY_STAGEMASK GIT_INDEX_ENTRY_STAGEMASK
/** @deprecated use `GIT_INDEX_ENTRY_STAGESHIFT` */
#define GIT_IDXENTRY_STAGESHIFT GIT_INDEX_ENTRY_STAGESHIFT
/* The git_indxentry_flag_t enum */
/** @deprecated use `GIT_INDEX_ENTRY_EXTENDED` */
#define GIT_IDXENTRY_EXTENDED GIT_INDEX_ENTRY_EXTENDED
/** @deprecated use `GIT_INDEX_ENTRY_VALID` */
#define GIT_IDXENTRY_VALID GIT_INDEX_ENTRY_VALID
/** @deprecated use `GIT_INDEX_ENTRY_STAGE` */
#define GIT_IDXENTRY_STAGE(E) GIT_INDEX_ENTRY_STAGE(E)
/** @deprecated use `GIT_INDEX_ENTRY_STAGE_SET` */
#define GIT_IDXENTRY_STAGE_SET(E,S) GIT_INDEX_ENTRY_STAGE_SET(E,S)
/* The git_idxentry_extended_flag_t enum */
/** @deprecated use `GIT_INDEX_ENTRY_INTENT_TO_ADD` */
#define GIT_IDXENTRY_INTENT_TO_ADD GIT_INDEX_ENTRY_INTENT_TO_ADD
/** @deprecated use `GIT_INDEX_ENTRY_SKIP_WORKTREE` */
#define GIT_IDXENTRY_SKIP_WORKTREE GIT_INDEX_ENTRY_SKIP_WORKTREE
/** @deprecated use `GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE` */
#define GIT_IDXENTRY_EXTENDED_FLAGS (GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_EXTENDED2 (1 << 15)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_UPDATE (1 << 0)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_REMOVE (1 << 1)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_UPTODATE (1 << 2)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_ADDED (1 << 3)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_HASHED (1 << 4)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_UNHASHED (1 << 5)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_WT_REMOVE (1 << 6)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_CONFLICTED (1 << 7)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_UNPACKED (1 << 8)
/** @deprecated this value is not public */
#define GIT_IDXENTRY_NEW_SKIP_WORKTREE (1 << 9)
/* The git_index_capability_t enum */
/** @deprecated use `GIT_INDEX_CAPABILITY_IGNORE_CASE` */
#define GIT_INDEXCAP_IGNORE_CASE GIT_INDEX_CAPABILITY_IGNORE_CASE
/** @deprecated use `GIT_INDEX_CAPABILITY_NO_FILEMODE` */
#define GIT_INDEXCAP_NO_FILEMODE GIT_INDEX_CAPABILITY_NO_FILEMODE
/** @deprecated use `GIT_INDEX_CAPABILITY_NO_SYMLINKS` */
#define GIT_INDEXCAP_NO_SYMLINKS GIT_INDEX_CAPABILITY_NO_SYMLINKS
/** @deprecated use `GIT_INDEX_CAPABILITY_FROM_OWNER` */
#define GIT_INDEXCAP_FROM_OWNER GIT_INDEX_CAPABILITY_FROM_OWNER
GIT_EXTERN(int) git_index_add_frombuffer(
@@ -550,17 +627,28 @@ GIT_EXTERN(int) git_index_add_frombuffer(
*/
/**@{*/
/** @deprecate use `git_object_t` */
#define git_otype git_object_t
/** @deprecate use `GIT_OBJECT_ANY` */
#define GIT_OBJ_ANY GIT_OBJECT_ANY
/** @deprecate use `GIT_OBJECT_INVALID` */
#define GIT_OBJ_BAD GIT_OBJECT_INVALID
/** @deprecated this value is not public */
#define GIT_OBJ__EXT1 0
/** @deprecate use `GIT_OBJECT_COMMIT` */
#define GIT_OBJ_COMMIT GIT_OBJECT_COMMIT
/** @deprecate use `GIT_OBJECT_TREE` */
#define GIT_OBJ_TREE GIT_OBJECT_TREE
/** @deprecate use `GIT_OBJECT_BLOB` */
#define GIT_OBJ_BLOB GIT_OBJECT_BLOB
/** @deprecate use `GIT_OBJECT_TAG` */
#define GIT_OBJ_TAG GIT_OBJECT_TAG
/** @deprecated this value is not public */
#define GIT_OBJ__EXT2 5
/** @deprecate use `GIT_OBJECT_OFS_DELTA` */
#define GIT_OBJ_OFS_DELTA GIT_OBJECT_OFS_DELTA
/** @deprecate use `GIT_OBJECT_REF_DELTA` */
#define GIT_OBJ_REF_DELTA GIT_OBJECT_REF_DELTA
/**
@@ -612,17 +700,27 @@ GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name);
/**@{*/
/** Basic type of any Git reference. */
/** @deprecate use `git_reference_t` */
#define git_ref_t git_reference_t
/** @deprecate use `git_reference_format_t` */
#define git_reference_normalize_t git_reference_format_t
/** @deprecate use `GIT_REFERENCE_INVALID` */
#define GIT_REF_INVALID GIT_REFERENCE_INVALID
/** @deprecate use `GIT_REFERENCE_DIRECT` */
#define GIT_REF_OID GIT_REFERENCE_DIRECT
/** @deprecate use `GIT_REFERENCE_SYMBOLIC` */
#define GIT_REF_SYMBOLIC GIT_REFERENCE_SYMBOLIC
/** @deprecate use `GIT_REFERENCE_ALL` */
#define GIT_REF_LISTALL GIT_REFERENCE_ALL
/** @deprecate use `GIT_REFERENCE_FORMAT_NORMAL` */
#define GIT_REF_FORMAT_NORMAL GIT_REFERENCE_FORMAT_NORMAL
/** @deprecate use `GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL` */
#define GIT_REF_FORMAT_ALLOW_ONELEVEL GIT_REFERENCE_FORMAT_ALLOW_ONELEVEL
/** @deprecate use `GIT_REFERENCE_FORMAT_REFSPEC_PATTERN` */
#define GIT_REF_FORMAT_REFSPEC_PATTERN GIT_REFERENCE_FORMAT_REFSPEC_PATTERN
/** @deprecate use `GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND` */
#define GIT_REF_FORMAT_REFSPEC_SHORTHAND GIT_REFERENCE_FORMAT_REFSPEC_SHORTHAND
/**
@@ -663,8 +761,11 @@ GIT_EXTERN(int) git_tag_create_frombuffer(
typedef git_revspec_t git_revparse_mode_t;
/** @deprecated use `GIT_REVSPEC_SINGLE` */
#define GIT_REVPARSE_SINGLE GIT_REVSPEC_SINGLE
/** @deprecated use `GIT_REVSPEC_RANGE` */
#define GIT_REVPARSE_RANGE GIT_REVSPEC_RANGE
/** @deprecated use `GIT_REVSPEC_MERGE_BASE` */
#define GIT_REVPARSE_MERGE_BASE GIT_REVSPEC_MERGE_BASE
/**@}*/
@@ -693,14 +794,22 @@ typedef git_credential_sign_cb git_cred_sign_cb;
typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_callback;
typedef git_credential_ssh_interactive_cb git_cred_ssh_interactive_cb;
/** @deprecated use `git_credential_t` */
#define git_credtype_t git_credential_t
/** @deprecated use `GIT_CREDENTIAL_USERPASS_PLAINTEXT` */
#define GIT_CREDTYPE_USERPASS_PLAINTEXT GIT_CREDENTIAL_USERPASS_PLAINTEXT
/** @deprecated use `GIT_CREDENTIAL_SSH_KEY` */
#define GIT_CREDTYPE_SSH_KEY GIT_CREDENTIAL_SSH_KEY
/** @deprecated use `GIT_CREDENTIAL_SSH_CUSTOM` */
#define GIT_CREDTYPE_SSH_CUSTOM GIT_CREDENTIAL_SSH_CUSTOM
/** @deprecated use `GIT_CREDENTIAL_DEFAULT` */
#define GIT_CREDTYPE_DEFAULT GIT_CREDENTIAL_DEFAULT
/** @deprecated use `GIT_CREDENTIAL_SSH_INTERACTIVE` */
#define GIT_CREDTYPE_SSH_INTERACTIVE GIT_CREDENTIAL_SSH_INTERACTIVE
/** @deprecated use `GIT_CREDENTIAL_USERNAME` */
#define GIT_CREDTYPE_USERNAME GIT_CREDENTIAL_USERNAME
/** @deprecated use `GIT_CREDENTIAL_SSH_MEMORY` */
#define GIT_CREDTYPE_SSH_MEMORY GIT_CREDENTIAL_SSH_MEMORY
GIT_EXTERN(void) git_cred_free(git_credential *cred);
@@ -778,8 +887,11 @@ typedef git_trace_cb git_trace_callback;
/**@{*/
#ifndef GIT_EXPERIMENTAL_SHA256
/** Deprecated OID "raw size" definition */
# define GIT_OID_RAWSZ GIT_OID_SHA1_SIZE
/** Deprecated OID "hex size" definition */
# define GIT_OID_HEXSZ GIT_OID_SHA1_HEXSIZE
/** Deprecated OID "hex zero" definition */
# define GIT_OID_HEX_ZERO GIT_OID_SHA1_HEXZERO
#endif

14
include/git2/describe.h
View File

@@ -13,10 +13,14 @@
/**
* @file git2/describe.h
* @brief Git describing routines
* @brief Describe a commit in reference to tags
* @defgroup git_describe Git describing routines
* @ingroup Git
* @{
*
* Describe a commit, showing information about how the current commit
* relates to the tags. This can be useful for showing how the current
* commit has changed from a particular tagged version of the repository.
*/
GIT_BEGIN_DECL
@@ -60,10 +64,15 @@ typedef struct git_describe_options {
int show_commit_oid_as_fallback;
} git_describe_options;
/** Default maximum candidate tags */
#define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10
/** Default abbreviated size */
#define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7
/** Current version for the `git_describe_options` structure */
#define GIT_DESCRIBE_OPTIONS_VERSION 1
/** Static constructor for `git_describe_options` */
#define GIT_DESCRIBE_OPTIONS_INIT { \
GIT_DESCRIBE_OPTIONS_VERSION, \
GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \
@@ -110,7 +119,10 @@ typedef struct {
const char *dirty_suffix;
} git_describe_format_options;
/** Current version for the `git_describe_format_options` structure */
#define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1
/** Static constructor for `git_describe_format_options` */
#define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \
GIT_DESCRIBE_FORMAT_OPTIONS_VERSION, \
GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \

46
include/git2/diff.h
View File

@@ -15,7 +15,7 @@
/**
* @file git2/diff.h
* @brief Git tree and file differencing routines.
* @brief Indicate the differences between two versions of the repository
* @ingroup Git
* @{
*/
@@ -342,6 +342,12 @@ typedef struct {
* diff process continues.
* - returns 0, the delta is inserted into the diff, and the diff process
* continues.
*
* @param diff_so_far the diff structure as it currently exists
* @param delta_to_add the delta that is to be added
* @param matched_pathspec the pathspec
* @param payload the user-specified callback payload
* @return 0 on success, 1 to skip this delta, or an error code
*/
typedef int GIT_CALLBACK(git_diff_notify_cb)(
const git_diff *diff_so_far,
@@ -357,7 +363,8 @@ typedef int GIT_CALLBACK(git_diff_notify_cb)(
* @param diff_so_far The diff being generated.
* @param old_path The path to the old file or NULL.
* @param new_path The path to the new file or NULL.
* @return Non-zero to abort the diff.
* @param payload the user-specified callback payload
* @return 0 or an error code
*/
typedef int GIT_CALLBACK(git_diff_progress_cb)(
const git_diff *diff_so_far,
@@ -463,10 +470,10 @@ typedef struct {
const char *new_prefix;
} git_diff_options;
/* The current version of the diff options structure */
/** The current version of the diff options structure */
#define GIT_DIFF_OPTIONS_VERSION 1
/* Stack initializer for diff options. Alternatively use
/** Stack initializer for diff options. Alternatively use
* `git_diff_options_init` programmatic initialization.
*/
#define GIT_DIFF_OPTIONS_INIT \
@@ -492,12 +499,14 @@ GIT_EXTERN(int) git_diff_options_init(
* @param delta A pointer to the delta data for the file
* @param progress Goes from 0 to 1 over the diff
* @param payload User-specified pointer from foreach function
* @return 0 or an error code
*/
typedef int GIT_CALLBACK(git_diff_file_cb)(
const git_diff_delta *delta,
float progress,
void *payload);
/** Maximum size of the hunk header */
#define GIT_DIFF_HUNK_HEADER_SIZE 128
/**
@@ -558,6 +567,11 @@ typedef struct {
/**
* When iterating over a diff, callback that will be made for
* binary content within the diff.
*
* @param delta the delta
* @param binary the binary content
* @param payload the user-specified callback payload
* @return 0 or an error code
*/
typedef int GIT_CALLBACK(git_diff_binary_cb)(
const git_diff_delta *delta,
@@ -584,6 +598,11 @@ typedef struct {
/**
* When iterating over a diff, callback that will be made per hunk.
*
* @param delta the delta
* @param hunk the hunk
* @param payload the user-specified callback payload
* @return 0 or an error code
*/
typedef int GIT_CALLBACK(git_diff_hunk_cb)(
const git_diff_delta *delta,
@@ -645,6 +664,12 @@ typedef struct {
* When printing a diff, callback that will be made to output each line
* of text. This uses some extra GIT_DIFF_LINE_... constants for output
* of lines of file and hunk headers.
*
* @param delta the delta that contains the line
* @param hunk the hunk that contains the line
* @param line the line in the diff
* @param payload the user-specified callback payload
* @return 0 or an error code
*/
typedef int GIT_CALLBACK(git_diff_line_cb)(
const git_diff_delta *delta, /**< delta that contains this data */
@@ -802,7 +827,10 @@ typedef struct {
git_diff_similarity_metric *metric;
} git_diff_find_options;
/** Current version for the `git_diff_find_options` structure */
#define GIT_DIFF_FIND_OPTIONS_VERSION 1
/** Static constructor for `git_diff_find_options` */
#define GIT_DIFF_FIND_OPTIONS_INIT {GIT_DIFF_FIND_OPTIONS_VERSION}
/**
@@ -1296,10 +1324,10 @@ typedef struct {
git_oid_t oid_type;
} git_diff_parse_options;
/* The current version of the diff parse options structure */
/** The current version of the diff parse options structure */
#define GIT_DIFF_PARSE_OPTIONS_VERSION 1
/* Stack initializer for diff parse options. Alternatively use
/** Stack initializer for diff parse options. Alternatively use
* `git_diff_parse_options_init` programmatic initialization.
*/
#define GIT_DIFF_PARSE_OPTIONS_INIT \
@@ -1432,7 +1460,10 @@ typedef struct git_diff_patchid_options {
unsigned int version;
} git_diff_patchid_options;
/** Current version for the `git_diff_patchid_options` structure */
#define GIT_DIFF_PATCHID_OPTIONS_VERSION 1
/** Static constructor for `git_diff_patchid_options` */
#define GIT_DIFF_PATCHID_OPTIONS_INIT { GIT_DIFF_PATCHID_OPTIONS_VERSION }
/**
@@ -1470,8 +1501,7 @@ GIT_EXTERN(int) git_diff_patchid_options_init(
*/
GIT_EXTERN(int) git_diff_patchid(git_oid *out, git_diff *diff, git_diff_patchid_options *opts);
/** @} */
GIT_END_DECL
/** @} */
#endif

13
include/git2/email.h
View File

@@ -12,7 +12,7 @@
/**
* @file git2/email.h
* @brief Git email formatting and application routines.
* @brief Produce email-ready patches
* @ingroup Git
* @{
*/
@@ -71,11 +71,14 @@ typedef struct {
size_t reroll_number;
} git_email_create_options;
/*
/** Current version for the `git_email_create_options` structure */
#define GIT_EMAIL_CREATE_OPTIONS_VERSION 1
/** Static constructor for `git_email_create_options`
*
* By default, our options include rename detection and binary
* diffs to match `git format-patch`.
*/
#define GIT_EMAIL_CREATE_OPTIONS_VERSION 1
#define GIT_EMAIL_CREATE_OPTIONS_INIT \
{ \
GIT_EMAIL_CREATE_OPTIONS_VERSION, \
@@ -91,14 +94,14 @@ typedef struct {
* @param out buffer to store the e-mail patch in
* @param commit commit to create a patch for
* @param opts email creation options
* @return 0 or an error code
*/
GIT_EXTERN(int) git_email_create_from_commit(
git_buf *out,
git_commit *commit,
const git_email_create_options *opts);
/** @} */
GIT_END_DECL
/** @} */
#endif

55
include/git2/errors.h
View File

@@ -11,7 +11,7 @@
/**
* @file git2/errors.h
* @brief Git error handling routines and variables
* @brief Error handling routines and variables
* @ingroup Git
* @{
*/
@@ -19,13 +19,20 @@ GIT_BEGIN_DECL
/** Generic return codes */
typedef enum {
GIT_OK = 0, /**< No error */
/**
* No error occurred; the call was successful.
*/
GIT_OK = 0,
GIT_ERROR = -1, /**< Generic error */
GIT_ENOTFOUND = -3, /**< Requested object could not be found */
GIT_EEXISTS = -4, /**< Object exists preventing operation */
GIT_EAMBIGUOUS = -5, /**< More than one object matches */
GIT_EBUFS = -6, /**< Output buffer too short to hold data */
/**
* An error occurred; call `git_error_last` for more information.
*/
GIT_ERROR = -1,
GIT_ENOTFOUND = -3, /**< Requested object could not be found. */
GIT_EEXISTS = -4, /**< Object exists preventing operation. */
GIT_EAMBIGUOUS = -5, /**< More than one object matches. */
GIT_EBUFS = -6, /**< Output buffer too short to hold data. */
/**
* GIT_EUSER is a special error that is never generated by libgit2
@@ -34,10 +41,10 @@ typedef enum {
*/
GIT_EUSER = -7,
GIT_EBAREREPO = -8, /**< Operation not allowed on bare repository */
GIT_EUNBORNBRANCH = -9, /**< HEAD refers to branch with no commits */
GIT_EUNMERGED = -10, /**< Merge in progress prevented operation */
GIT_ENONFASTFORWARD = -11, /**< Reference was not fast-forwardable */
GIT_EBAREREPO = -8, /**< Operation not allowed on bare repository. */
GIT_EUNBORNBRANCH = -9, /**< HEAD refers to branch with no commits. */
GIT_EUNMERGED = -10, /**< Merge in progress prevented operation */
GIT_ENONFASTFORWARD = -11, /**< Reference was not fast-forwardable */
GIT_EINVALIDSPEC = -12, /**< Name/ref spec was not in a valid format */
GIT_ECONFLICT = -13, /**< Checkout conflicts prevented operation */
GIT_ELOCKED = -14, /**< Lock file prevented operation */
@@ -66,17 +73,9 @@ typedef enum {
} git_error_code;
/**
* Structure to store extra details of the last error that occurred.
*
* This is kept on a per-thread basis if GIT_THREADS was defined when the
* library was build, otherwise one is kept globally for the library
* Error classes are the category of error. They reflect the area of the
* code where an error occurred.
*/
typedef struct {
char *message;
int klass;
} git_error;
/** Error classes */
typedef enum {
GIT_ERROR_NONE = 0,
GIT_ERROR_NOMEMORY,
@@ -117,6 +116,17 @@ typedef enum {
GIT_ERROR_GRAFTS
} git_error_t;
/**
* Structure to store extra details of the last error that occurred.
*
* This is kept on a per-thread basis if GIT_THREADS was defined when the
* library was build, otherwise one is kept globally for the library
*/
typedef struct {
char *message; /**< The error message for the last error. */
int klass; /**< The category of the last error. @type git_error_t */
} git_error;
/**
* Return the last `git_error` object that was generated for the
* current thread.
@@ -134,10 +144,11 @@ typedef enum {
* The memory for this object is managed by libgit2. It should not
* be freed.
*
* @return A git_error object.
* @return A pointer to a `git_error` object that describes the error.
*/
GIT_EXTERN(const git_error *) git_error_last(void);
/** @} */
GIT_END_DECL
#endif

21
include/git2/filter.h
View File

@@ -14,9 +14,15 @@
/**
* @file git2/filter.h
* @brief Git filter APIs
*
* @brief Filters modify files during checkout or commit
* @ingroup Git
*
* During checkout, filters update a file from a "canonical" state to
* a format appropriate for the local filesystem; during commit, filters
* produce the canonical state. For example, on Windows, the line ending
* filters _may_ take a canonical state (with Unix-style newlines) in
* the repository, and place the contents on-disk with Windows-style
* `\r\n` line endings.
* @{
*/
GIT_BEGIN_DECL
@@ -79,8 +85,11 @@ typedef struct {
git_oid attr_commit_id;
} git_filter_options;
#define GIT_FILTER_OPTIONS_VERSION 1
#define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION}
/** Current version for the `git_filter_options` structure */
#define GIT_FILTER_OPTIONS_VERSION 1
/** Static constructor for `git_filter_options` */
#define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION}
/**
* A filter that can transform file data
@@ -268,9 +277,7 @@ GIT_EXTERN(int) git_filter_list_stream_blob(
*/
GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters);
/** @} */
GIT_END_DECL
/** @} */
#endif

9
include/git2/global.h
View File

@@ -9,6 +9,12 @@
#include "common.h"
/**
* @file git2/global.h
* @brief libgit2 library initializer and shutdown functionality
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
@@ -32,7 +38,7 @@ GIT_EXTERN(int) git_libgit2_init(void);
* many times as `git_libgit2_init()` was called - it will return the
* number of remainining initializations that have not been shutdown
* (after this one).
*
*
* @return the number of remaining initializations of the library, or an
* error code.
*/
@@ -40,5 +46,6 @@ GIT_EXTERN(int) git_libgit2_shutdown(void);
/** @} */
GIT_END_DECL
#endif

5
include/git2/graph.h
View File

@@ -13,7 +13,7 @@
/**
* @file git2/graph.h
* @brief Git graph traversal routines
* @brief Graph traversal routines
* @defgroup git_revwalk Git graph traversal routines
* @ingroup Git
* @{
@@ -61,8 +61,8 @@ GIT_EXTERN(int) git_graph_descendant_of(
*
* @param repo the repository where the commits exist
* @param commit a previously loaded commit
* @param length the number of commits in the provided `descendant_array`
* @param descendant_array oids of the commits
* @param length the number of commits in the provided `descendant_array`
* @return 1 if the given commit is an ancestor of any of the given potential
* descendants, 0 if not, error code otherwise.
*/
@@ -74,4 +74,5 @@ GIT_EXTERN(int) git_graph_reachable_from_any(
/** @} */
GIT_END_DECL
#endif

10
include/git2/ignore.h
View File

@@ -10,6 +10,15 @@
#include "common.h"
#include "types.h"
/**
* @file git2/ignore.h
* @brief Ignore particular untracked files
* @ingroup Git
* @{
*
* When examining the repository status, git can optionally ignore
* specified untracked files.
*/
GIT_BEGIN_DECL
/**
@@ -73,6 +82,7 @@ GIT_EXTERN(int) git_ignore_path_is_ignored(
git_repository *repo,
const char *path);
/** @} */
GIT_END_DECL
#endif

69
include/git2/index.h
View File

@@ -15,9 +15,14 @@
/**
* @file git2/index.h
* @brief Git index parsing and manipulation routines
* @brief Index (aka "cache" aka "staging area")
* @defgroup git_index Git index parsing and manipulation routines
* @ingroup Git
*
* The index (or "cache", or "staging area") is the contents of the
* next commit. In addition, the index stores other data, such as
* conflicts that occurred during the last merge operation, and
* the "treecache" to speed up various on-disk operations.
* @{
*/
GIT_BEGIN_DECL
@@ -77,8 +82,11 @@ typedef struct git_index_entry {
* data in the `flags`.
*/
/** Mask for name length */
#define GIT_INDEX_ENTRY_NAMEMASK (0x0fff)
/** Mask for index entry stage */
#define GIT_INDEX_ENTRY_STAGEMASK (0x3000)
/** Shift bits for index entry */
#define GIT_INDEX_ENTRY_STAGESHIFT 12
/**
@@ -89,9 +97,17 @@ typedef enum {
GIT_INDEX_ENTRY_VALID = (0x8000)
} git_index_entry_flag_t;
/**
* Macro to get the stage value (0 for the "main index", or a conflict
* value) from an index entry.
*/
#define GIT_INDEX_ENTRY_STAGE(E) \
(((E)->flags & GIT_INDEX_ENTRY_STAGEMASK) >> GIT_INDEX_ENTRY_STAGESHIFT)
/**
* Macro to set the stage value (0 for the "main index", or a conflict
* value) for an index entry.
*/
#define GIT_INDEX_ENTRY_STAGE_SET(E,S) do { \
(E)->flags = ((E)->flags & ~GIT_INDEX_ENTRY_STAGEMASK) | \
(((S) & 0x03) << GIT_INDEX_ENTRY_STAGESHIFT); } while (0)
@@ -131,7 +147,14 @@ typedef enum {
} git_index_capability_t;
/** Callback for APIs that add/remove/update files matching pathspec */
/**
* Callback for APIs that add/remove/update files matching pathspec
*
* @param path the path
* @param matched_pathspec the given pathspec
* @param payload the user-specified payload
* @return 0 to continue with the index operation, positive number to skip this file for the index operation, negative number on failure
*/
typedef int GIT_CALLBACK(git_index_matched_path_cb)(
const char *path, const char *matched_pathspec, void *payload);
@@ -166,6 +189,30 @@ typedef enum {
GIT_INDEX_STAGE_THEIRS = 3
} git_index_stage_t;
#ifdef GIT_EXPERIMENTAL_SHA256
/**
* Creates a new bare Git index object, without a repository to back
* it. This index object is capable of storing SHA256 objects.
*
* @param index_out the pointer for the new index
* @param index_path the path to the index file in disk
* @param oid_type the object ID type to use for the repository
* @return 0 or an error code
*/
GIT_EXTERN(int) git_index_open(git_index **index_out, const char *index_path, git_oid_t oid_type);
/**
* Create an in-memory index object.
*
* @param index_out the pointer for the new index
* @param oid_type the object ID type to use for the repository
* @return 0 or an error code
*/
GIT_EXTERN(int) git_index_new(git_index **index_out, git_oid_t oid_type);
#else
/**
* Create a new bare Git index object as a memory representation
* of the Git index file in 'index_path', without a repository
@@ -180,16 +227,11 @@ typedef enum {
*
* The index must be freed once it's no longer in use.
*
* @param out the pointer for the new index
* @param index_out the pointer for the new index
* @param index_path the path to the index file in disk
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path, git_oid_t oid_type);
#else
GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path);
#endif
GIT_EXTERN(int) git_index_open(git_index **index_out, const char *index_path);
/**
* Create an in-memory index object.
@@ -199,13 +241,11 @@ GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path);
*
* The index must be freed once it's no longer in use.
*
* @param out the pointer for the new index
* @param index_out the pointer for the new index
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_index_new(git_index **out, git_oid_t oid_type);
#else
GIT_EXTERN(int) git_index_new(git_index **out);
GIT_EXTERN(int) git_index_new(git_index **index_out);
#endif
/**
@@ -845,4 +885,5 @@ GIT_EXTERN(void) git_index_conflict_iterator_free(
/** @} */
GIT_END_DECL
#endif

19
include/git2/indexer.h
View File

@@ -4,13 +4,23 @@
* This file is part of libgit2, distributed under the GNU GPL v2 with
* a Linking Exception. For full terms see the included COPYING file.
*/
#ifndef _INCLUDE_git_indexer_h__
#define _INCLUDE_git_indexer_h__
#ifndef INCLUDE_git_indexer_h__
#define INCLUDE_git_indexer_h__
#include "common.h"
#include "types.h"
#include "oid.h"
/**
* @file git2/indexer.h
* @brief Packfile indexing
* @ingroup Git
* @{
*
* Indexing is the operation of taking a packfile - which is simply a
* collection of unordered commits - and producing an "index" so that
* one can lookup a commit in the packfile by object ID.
*/
GIT_BEGIN_DECL
/** A git indexer object */
@@ -53,6 +63,7 @@ typedef struct git_indexer_progress {
*
* @param stats Structure containing information about the state of the transfer
* @param payload Payload provided by caller
* @return 0 on success or an error code
*/
typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload);
@@ -85,7 +96,10 @@ typedef struct git_indexer_options {
unsigned char verify;
} git_indexer_options;
/** Current version for the `git_indexer_options` structure */
#define GIT_INDEXER_OPTIONS_VERSION 1
/** Static constructor for `git_indexer_options` */
#define GIT_INDEXER_OPTIONS_INIT { GIT_INDEXER_OPTIONS_VERSION }
/**
@@ -190,6 +204,7 @@ GIT_EXTERN(const char *) git_indexer_name(const git_indexer *idx);
*/
GIT_EXTERN(void) git_indexer_free(git_indexer *idx);
/** @} */
GIT_END_DECL
#endif

8
include/git2/mailmap.h
View File

@@ -13,10 +13,15 @@
/**
* @file git2/mailmap.h
* @brief Mailmap parsing routines
* @brief Mailmaps provide alternate email addresses for users
* @defgroup git_mailmap Git mailmap routines
* @ingroup Git
* @{
*
* A mailmap can be used to specify alternate email addresses for
* repository committers or authors. This allows systems to map
* commits made using different email addresses to the same logical
* person.
*/
GIT_BEGIN_DECL
@@ -112,4 +117,5 @@ GIT_EXTERN(int) git_mailmap_resolve_signature(
/** @} */
GIT_END_DECL
#endif

47
include/git2/merge.h
View File

@@ -17,9 +17,12 @@
/**
* @file git2/merge.h
* @brief Git merge routines
* @brief Merge re-joins diverging branches of history
* @defgroup git_merge Git merge routines
* @ingroup Git
*
* Merge will take two commits and attempt to produce a commit that
* includes the changes that were made in both branches.
* @{
*/
GIT_BEGIN_DECL
@@ -45,7 +48,10 @@ typedef struct {
unsigned int mode;
} git_merge_file_input;
/** Current version for the `git_merge_file_input_options` structure */
#define GIT_MERGE_FILE_INPUT_VERSION 1
/** Static constructor for `git_merge_file_input_options` */
#define GIT_MERGE_FILE_INPUT_INIT {GIT_MERGE_FILE_INPUT_VERSION}
/**
@@ -180,6 +186,7 @@ typedef enum {
GIT_MERGE_FILE_ACCEPT_CONFLICTS = (1 << 9)
} git_merge_file_flag_t;
/** Default size for conflict markers */
#define GIT_MERGE_CONFLICT_MARKER_SIZE 7
/**
@@ -217,7 +224,10 @@ typedef struct {
unsigned short marker_size;
} git_merge_file_options;
/** Current version for the `git_merge_file_options` structure */
#define GIT_MERGE_FILE_OPTIONS_VERSION 1
/** Static constructor for `git_merge_file_options` */
#define GIT_MERGE_FILE_OPTIONS_INIT {GIT_MERGE_FILE_OPTIONS_VERSION}
/**
@@ -312,7 +322,10 @@ typedef struct {
uint32_t file_flags;
} git_merge_options;
/** Current version for the `git_merge_options` structure */
#define GIT_MERGE_OPTIONS_VERSION 1
/** Static constructor for `git_merge_options` */
#define GIT_MERGE_OPTIONS_INIT { \
GIT_MERGE_OPTIONS_VERSION, GIT_MERGE_FIND_RENAMES }
@@ -471,6 +484,37 @@ GIT_EXTERN(int) git_merge_base_many(
/**
* Find all merge bases given a list of commits
*
* This behaves similar to [`git merge-base`](https://git-scm.com/docs/git-merge-base#_discussion).
*
* Given three commits `a`, `b`, and `c`, `merge_base_many`
* will compute a hypothetical commit `m`, which is a merge between `b`
* and `c`.
* For example, with the following topology:
* ```text
* o---o---o---o---C
* /
* / o---o---o---B
* / /
* ---2---1---o---o---o---A
* ```
*
* the result of `merge_base_many` given `a`, `b`, and `c` is 1. This is
* because the equivalent topology with the imaginary merge commit `m`
* between `b` and `c` is:
* ```text
* o---o---o---o---o
* / \
* / o---o---o---o---M
* / /
* ---2---1---o---o---o---A
* ```
*
* and the result of `merge_base_many` given `a` and `m` is 1.
*
* If you're looking to recieve the common ancestor between all the
* given commits, use `merge_base_octopus`.
*
* @param out array in which to store the resulting ids
* @param repo the repository where the commits exist
* @param length The number of commits in the provided `input_array`
@@ -623,4 +667,5 @@ GIT_EXTERN(int) git_merge(
/** @} */
GIT_END_DECL
#endif

4
include/git2/message.h
View File

@@ -12,7 +12,7 @@
/**
* @file git2/message.h
* @brief Git message management routines
* @brief Commit messages
* @ingroup Git
* @{
*/
@@ -83,4 +83,4 @@ GIT_EXTERN(void) git_message_trailer_array_free(git_message_trailer_array *arr);
/** @} */
GIT_END_DECL
#endif /* INCLUDE_git_message_h__ */
#endif

4
include/git2/net.h
View File

@@ -13,12 +13,13 @@
/**
* @file git2/net.h
* @brief Git networking declarations
* @brief Low-level networking functionality
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/** Default git protocol port number */
#define GIT_DEFAULT_PORT "9418"
/**
@@ -51,4 +52,5 @@ struct git_remote_head {
/** @} */
GIT_END_DECL
#endif

15
include/git2/notes.h
View File

@@ -11,7 +11,7 @@
/**
* @file git2/notes.h
* @brief Git notes management routines
* @brief Notes are metadata attached to an object
* @defgroup git_note Git notes management routines
* @ingroup Git
* @{
@@ -21,13 +21,15 @@ GIT_BEGIN_DECL
/**
* Callback for git_note_foreach.
*
* Receives:
* - blob_id: Oid of the blob containing the message
* - annotated_object_id: Oid of the git object being annotated
* - payload: Payload data passed to `git_note_foreach`
* @param blob_id object id of the blob containing the message
* @param annotated_object_id the id of the object being annotated
* @param payload user-specified data to the foreach function
* @return 0 on success, or a negative number on failure
*/
typedef int GIT_CALLBACK(git_note_foreach_cb)(
const git_oid *blob_id, const git_oid *annotated_object_id, void *payload);
const git_oid *blob_id,
const git_oid *annotated_object_id,
void *payload);
/**
* note iterator
@@ -303,4 +305,5 @@ GIT_EXTERN(int) git_note_foreach(
/** @} */
GIT_END_DECL
#endif

17
include/git2/object.h
View File

@@ -14,13 +14,14 @@
/**
* @file git2/object.h
* @brief Git revision object management routines
* @brief Objects are blobs (files), trees (directories), commits, and annotated tags
* @defgroup git_object Git revision object management routines
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/** Maximum size of a git object */
#define GIT_OBJECT_SIZE_MAX UINT64_MAX
/**
@@ -53,18 +54,18 @@ GIT_EXTERN(int) git_object_lookup(
*
* The object obtained will be so that its identifier
* matches the first 'len' hexadecimal characters
* (packets of 4 bits) of the given 'id'.
* 'len' must be at least GIT_OID_MINPREFIXLEN, and
* long enough to identify a unique object matching
* the prefix; otherwise the method will fail.
* (packets of 4 bits) of the given `id`. `len` must be
* at least `GIT_OID_MINPREFIXLEN`, and long enough to
* identify a unique object matching the prefix; otherwise
* the method will fail.
*
* The generated reference is owned by the repository and
* should be closed with the `git_object_free` method
* instead of free'd manually.
*
* The 'type' parameter must match the type of the object
* The `type` parameter must match the type of the object
* in the odb; the method will fail otherwise.
* The special value 'GIT_OBJECT_ANY' may be passed to let
* The special value `GIT_OBJECT_ANY` may be passed to let
* the method guess the object's type.
*
* @param object_out pointer where to store the looked-up object
@@ -260,7 +261,7 @@ GIT_EXTERN(int) git_object_rawcontent_is_valid(
* @warning This function is experimental and its signature may change in
* the future.
*
* @param valid Output pointer to set with validity of the object content
* @param[out] valid Output pointer to set with validity of the object content
* @param buf The contents to validate
* @param len The length of the buffer
* @param object_type The type of the object in the buffer

138
include/git2/odb.h
View File

@@ -15,7 +15,7 @@
/**
* @file git2/odb.h
* @brief Git object database routines
* @brief An object database manages the storage of git objects
* @defgroup git_odb Git object database routines
* @ingroup Git
* @{
@@ -35,6 +35,10 @@ typedef enum {
/**
* Function type for callbacks from git_odb_foreach.
*
* @param id an id of an object in the object database
* @param payload the payload from the initial call to git_odb_foreach
* @return 0 on success, or an error code
*/
typedef int GIT_CALLBACK(git_odb_foreach_cb)(const git_oid *id, void *payload);
@@ -49,30 +53,53 @@ typedef struct {
git_oid_t oid_type;
} git_odb_options;
/* The current version of the diff options structure */
/** The current version of the diff options structure */
#define GIT_ODB_OPTIONS_VERSION 1
/* Stack initializer for odb options. Alternatively use
/**
* Stack initializer for odb options. Alternatively use
* `git_odb_options_init` programmatic initialization.
*/
#define GIT_ODB_OPTIONS_INIT { GIT_ODB_OPTIONS_VERSION }
#ifdef GIT_EXPERIMENTAL_SHA256
/**
* Create a new object database with no backends.
*
* @param[out] odb location to store the database pointer, if opened.
* @param opts the options for this object database or NULL for defaults
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_new(git_odb **odb, const git_odb_options *opts);
/**
* Create a new object database and automatically add loose and packed
* backends.
*
* @param[out] odb_out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @param objects_dir path of the backends' "objects" directory.
* @param opts the options for this object database or NULL for defaults
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_open(
git_odb **odb_out,
const char *objects_dir,
const git_odb_options *opts);
#else
/**
* Create a new object database with no backends.
*
* Before the ODB can be used for read/writing, a custom database
* backend must be manually added using `git_odb_add_backend()`
*
* @param out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @param opts the options for this object database or NULL for defaults
* @param[out] odb location to store the database pointer, if opened.
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_odb_new(git_odb **out, const git_odb_options *opts);
#else
GIT_EXTERN(int) git_odb_new(git_odb **out);
#endif
GIT_EXTERN(int) git_odb_new(git_odb **odb);
/**
* Create a new object database and automatically add
@@ -85,19 +112,12 @@ GIT_EXTERN(int) git_odb_new(git_odb **out);
* assuming `objects_dir` as the Objects folder which
* contains a 'pack/' folder with the corresponding data
*
* @param out location to store the database pointer, if opened.
* @param[out] odb_out location to store the database pointer, if opened.
* Set to NULL if the open failed.
* @param objects_dir path of the backends' "objects" directory.
* @param opts the options for this object database or NULL for defaults
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_odb_open(
git_odb **out,
const char *objects_dir,
const git_odb_options *opts);
#else
GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir);
GIT_EXTERN(int) git_odb_open(git_odb **odb_out, const char *objects_dir);
#endif
/**
@@ -134,13 +154,13 @@ GIT_EXTERN(void) git_odb_free(git_odb *db);
* internally cached, so it should be closed
* by the user once it's no longer in use.
*
* @param out pointer where to store the read object
* @param[out] obj pointer where to store the read object
* @param db database to search for the object in.
* @param id identity of the object to read.
* @return 0 if the object was read, GIT_ENOTFOUND if the object is
* not in the database.
*/
GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id);
GIT_EXTERN(int) git_odb_read(git_odb_object **obj, git_odb *db, const git_oid *id);
/**
* Read an object from the database, given a prefix
@@ -160,7 +180,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i
* internally cached, so it should be closed
* by the user once it's no longer in use.
*
* @param out pointer where to store the read object
* @param[out] obj pointer where to store the read object
* @param db database to search for the object in.
* @param short_id a prefix of the id of the object to read.
* @param len the length of the prefix
@@ -168,7 +188,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i
* database. GIT_EAMBIGUOUS if the prefix is ambiguous
* (several objects match the prefix)
*/
GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git_oid *short_id, size_t len);
GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **obj, git_odb *db, const git_oid *short_id, size_t len);
/**
* Read the header of an object from the database, without
@@ -180,8 +200,8 @@ GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git
* of an object, so the whole object will be read and then the
* header will be returned.
*
* @param len_out pointer where to store the length
* @param type_out pointer where to store the type
* @param[out] len_out pointer where to store the length
* @param[out] type_out pointer where to store the type
* @param db database to search for the object in.
* @param id identity of the object to read.
* @return 0 if the object was read, GIT_ENOTFOUND if the object is not
@@ -301,7 +321,10 @@ GIT_EXTERN(int) git_odb_refresh(git_odb *db);
* @param payload data to pass to the callback
* @return 0 on success, non-zero callback return value, or error code
*/
GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload);
GIT_EXTERN(int) git_odb_foreach(
git_odb *db,
git_odb_foreach_cb cb,
void *payload);
/**
* Write an object directly into the ODB
@@ -316,7 +339,7 @@ GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payloa
*
* @param out pointer to store the OID result of the write
* @param odb object database where to store the object
* @param data buffer with the data to store
* @param data @type `const unsigned char *` buffer with the data to store
* @param len size of the buffer
* @param type type of the data to store
* @return 0 or an error code
@@ -466,29 +489,54 @@ GIT_EXTERN(int) git_odb_write_pack(
GIT_EXTERN(int) git_odb_write_multi_pack_index(
git_odb *db);
#ifdef GIT_EXPERIMENTAL_SHA256
/**
* Determine the object-ID (sha1 or sha256 hash) of a data buffer
* Generate the object ID (in SHA1 or SHA256 format) for a given data buffer.
*
* The resulting OID will be the identifier for the data buffer as if
* the data buffer it were to written to the ODB.
*
* @param out the resulting object-ID.
* @param[out] oid the resulting object ID.
* @param data data to hash
* @param len size of the data
* @param object_type of the data to hash
* @param oid_type the oid type to hash to
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_odb_hash(
git_oid *out,
git_oid *oid,
const void *data,
size_t len,
git_object_t object_type,
git_oid_t oid_type);
/**
* Determine the object ID of a file on disk.
*
* @param[out] oid oid structure the result is written into.
* @param path file to read and determine object id for
* @param object_type of the data to hash
* @param oid_type the oid type to hash to
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_hashfile(
git_oid *oid,
const char *path,
git_object_t object_type,
git_oid_t oid_type);
#else
GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_object_t type);
#endif
/**
* Determine the object-ID (sha1 or sha256 hash) of a data buffer
*
* The resulting OID will be the identifier for the data buffer as if
* the data buffer it were to written to the ODB.
*
* @param[out] oid the resulting object-ID.
* @param data data to hash
* @param len size of the data
* @param object_type of the data to hash
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_hash(git_oid *oid, const void *data, size_t len, git_object_t object_type);
/**
* Read a file from disk and fill a git_oid with the object id
@@ -498,20 +546,13 @@ GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_obj
* the `-w` flag, however, with the --no-filters flag.
* If you need filters, see git_repository_hashfile.
*
* @param out oid structure the result is written into.
* @param[out] oid oid structure the result is written into.
* @param path file to read and determine object id for
* @param object_type of the data to hash
* @param oid_type the oid type to hash to
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_odb_hashfile(
git_oid *out,
const char *path,
git_object_t object_type,
git_oid_t oid_type);
#else
GIT_EXTERN(int) git_odb_hashfile(git_oid *out, const char *path, git_object_t type);
GIT_EXTERN(int) git_odb_hashfile(git_oid *oid, const char *path, git_object_t object_type);
#endif
/**
@@ -557,7 +598,7 @@ GIT_EXTERN(const git_oid *) git_odb_object_id(git_odb_object *object);
* This pointer is owned by the object and shall not be free'd.
*
* @param object the object
* @return a pointer to the data
* @return @type `const unsigned char *` a pointer to the data
*/
GIT_EXTERN(const void *) git_odb_object_data(git_odb_object *object);
@@ -651,4 +692,5 @@ GIT_EXTERN(int) git_odb_set_commit_graph(git_odb *odb, git_commit_graph *cgraph)
/** @} */
GIT_END_DECL
#endif

132
include/git2/odb_backend.h
View File

@@ -13,17 +13,13 @@
/**
* @file git2/backend.h
* @brief Git custom backend functions
* @brief Object database backends manage the storage of git objects
* @defgroup git_odb Git object database routines
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/*
* Constructors for in-box ODB backends.
*/
/** Options for configuring a packfile object backend. */
typedef struct {
unsigned int version; /**< version for the struct */
@@ -35,56 +31,16 @@ typedef struct {
git_oid_t oid_type;
} git_odb_backend_pack_options;
/* The current version of the diff options structure */
/** The current version of the diff options structure */
#define GIT_ODB_BACKEND_PACK_OPTIONS_VERSION 1
/* Stack initializer for odb pack backend options. Alternatively use
/**
* Stack initializer for odb pack backend options. Alternatively use
* `git_odb_backend_pack_options_init` programmatic initialization.
*/
#define GIT_ODB_BACKEND_PACK_OPTIONS_INIT \
{ GIT_ODB_BACKEND_PACK_OPTIONS_VERSION }
/**
* Create a backend for the packfiles.
*
* @param out location to store the odb backend pointer
* @param objects_dir the Git repository's objects directory
*
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_odb_backend_pack(
git_odb_backend **out,
const char *objects_dir,
const git_odb_backend_pack_options *opts);
#else
GIT_EXTERN(int) git_odb_backend_pack(
git_odb_backend **out,
const char *objects_dir);
#endif
/**
* Create a backend out of a single packfile
*
* This can be useful for inspecting the contents of a single
* packfile.
*
* @param out location to store the odb backend pointer
* @param index_file path to the packfile's .idx file
*
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_odb_backend_one_pack(
git_odb_backend **out,
const char *index_file,
const git_odb_backend_pack_options *opts);
#else
GIT_EXTERN(int) git_odb_backend_one_pack(
git_odb_backend **out,
const char *index_file);
#endif
typedef enum {
GIT_ODB_BACKEND_LOOSE_FSYNC = (1 << 0)
} git_odb_backend_loose_flag_t;
@@ -118,30 +74,100 @@ typedef struct {
git_oid_t oid_type;
} git_odb_backend_loose_options;
/* The current version of the diff options structure */
/** The current version of the diff options structure */
#define GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION 1
/* Stack initializer for odb loose backend options. Alternatively use
/**
* Stack initializer for odb loose backend options. Alternatively use
* `git_odb_backend_loose_options_init` programmatic initialization.
*/
#define GIT_ODB_BACKEND_LOOSE_OPTIONS_INIT \
{ GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION, 0, -1 }
/*
* Constructors for in-box ODB backends.
*/
#ifdef GIT_EXPERIMENTAL_SHA256
/**
* Create a backend for a directory containing packfiles.
*
* @param[out] out location to store the odb backend pointer
* @param objects_dir the Git repository's objects directory
* @param opts the options to use when creating the pack backend
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_backend_pack(
git_odb_backend **out,
const char *objects_dir,
const git_odb_backend_pack_options *opts);
/**
* Create a backend for a single packfile.
*
* @param[out] out location to store the odb backend pointer
* @param index_file path to the packfile's .idx file
* @param opts the options to use when creating the pack backend
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_backend_one_pack(
git_odb_backend **out,
const char *index_file,
const git_odb_backend_pack_options *opts);
/**
* Create a backend for loose objects
*
* @param out location to store the odb backend pointer
* @param[out] out location to store the odb backend pointer
* @param objects_dir the Git repository's objects directory
* @param opts options for the loose object backend or NULL
*
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_odb_backend_loose(
git_odb_backend **out,
const char *objects_dir,
git_odb_backend_loose_options *opts);
#else
/**
* Create a backend for a directory containing packfiles.
*
* @param[out] out location to store the odb backend pointer
* @param objects_dir the Git repository's objects directory
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_backend_pack(
git_odb_backend **out,
const char *objects_dir);
/**
* Create a backend out of a single packfile
*
* This can be useful for inspecting the contents of a single
* packfile.
*
* @param[out] out location to store the odb backend pointer
* @param index_file path to the packfile's .idx file
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_backend_one_pack(
git_odb_backend **out,
const char *index_file);
/**
* Create a backend for loose objects
*
* @param[out] out location to store the odb backend pointer
* @param objects_dir the Git repository's objects directory
* @param compression_level zlib compression level (0-9), or -1 for the default
* @param do_fsync if non-zero, perform an fsync on write
* @param dir_mode permission to use when creating directories, or 0 for default
* @param file_mode permission to use when creating directories, or 0 for default
* @return 0 or an error code
*/
GIT_EXTERN(int) git_odb_backend_loose(
git_odb_backend **out,
const char *objects_dir,
@@ -149,6 +175,7 @@ GIT_EXTERN(int) git_odb_backend_loose(
int do_fsync,
unsigned int dir_mode,
unsigned int file_mode);
#endif
/** Streaming mode */
@@ -218,6 +245,7 @@ struct git_odb_writepack {
void GIT_CALLBACK(free)(git_odb_writepack *writepack);
};
/** @} */
GIT_END_DECL
#endif

47
include/git2/oid.h
View File

@@ -13,7 +13,7 @@
/**
* @file git2/oid.h
* @brief Git object id routines
* @brief Object IDs
* @defgroup git_oid Git object id routines
* @ingroup Git
* @{
@@ -82,13 +82,18 @@ typedef enum {
#endif
/* Maximum possible object ID size in raw / hex string format. */
#ifndef GIT_EXPERIMENTAL_SHA256
# define GIT_OID_MAX_SIZE GIT_OID_SHA1_SIZE
# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA1_HEXSIZE
#else
/** Maximum possible object ID size in raw format */
#ifdef GIT_EXPERIMENTAL_SHA256
# define GIT_OID_MAX_SIZE GIT_OID_SHA256_SIZE
#else
# define GIT_OID_MAX_SIZE GIT_OID_SHA1_SIZE
#endif
/** Maximum possible object ID size in hex format */
#ifdef GIT_EXPERIMENTAL_SHA256
# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA256_HEXSIZE
#else
# define GIT_OID_MAX_HEXSIZE GIT_OID_SHA1_HEXSIZE
#endif
/** Minimum length (in number of hex characters,
@@ -107,6 +112,15 @@ typedef struct git_oid {
unsigned char id[GIT_OID_MAX_SIZE];
} git_oid;
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str, git_oid_t type);
GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str, git_oid_t type);
GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length, git_oid_t type);
GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw, git_oid_t type);
#else
/**
* Parse a hex formatted object id into a git_oid.
*
@@ -119,28 +133,18 @@ typedef struct git_oid {
* the hex sequence and have at least the number of bytes
* needed for an oid encoded in hex (40 bytes for sha1,
* 256 bytes for sha256).
* @param type the type of object id
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str, git_oid_t type);
#else
GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str);
#endif
/**
* Parse a hex formatted NUL-terminated string into a git_oid.
*
* @param out oid structure the result is written into.
* @param str input hex string; must be null-terminated.
* @param type the type of object id
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str, git_oid_t type);
#else
GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str);
#endif
/**
* Parse N characters of a hex formatted object id into a git_oid.
@@ -151,14 +155,9 @@ GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str);
* @param out oid structure the result is written into.
* @param str input hex string of at least size `length`
* @param length length of the input string
* @param type the type of object id
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length, git_oid_t type);
#else
GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length);
#endif
/**
* Copy an already raw oid into a git_oid structure.
@@ -167,10 +166,8 @@ GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length);
* @param raw the raw input bytes to be copied.
* @return 0 on success or error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw, git_oid_t type);
#else
GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw);
#endif
/**
@@ -310,6 +307,7 @@ GIT_EXTERN(int) git_oid_strcmp(const git_oid *id, const char *str);
/**
* Check is an oid is all zeros.
*
* @param id the object ID to check
* @return 1 if all zeros, 0 otherwise.
*/
GIT_EXTERN(int) git_oid_is_zero(const git_oid *id);
@@ -370,4 +368,5 @@ GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os);
/** @} */
GIT_END_DECL
#endif

8
include/git2/oidarray.h
View File

@@ -10,6 +10,13 @@
#include "common.h"
#include "oid.h"
/**
* @file git2/oidarray.h
* @brief An array of object IDs
* @defgroup git_oidarray Arrays of object IDs
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/** Array of object ids */
@@ -34,4 +41,3 @@ GIT_EXTERN(void) git_oidarray_dispose(git_oidarray *array);
GIT_END_DECL
#endif

11
include/git2/pack.h
View File

@@ -233,7 +233,15 @@ GIT_EXTERN(size_t) git_packbuilder_object_count(git_packbuilder *pb);
*/
GIT_EXTERN(size_t) git_packbuilder_written(git_packbuilder *pb);
/** Packbuilder progress notification function */
/**
* Packbuilder progress notification function.
*
* @param stage the stage of the packbuilder
* @param current the current object
* @param total the total number of objects
* @param payload the callback payload
* @return 0 on success or an error code
*/
typedef int GIT_CALLBACK(git_packbuilder_progress)(
int stage,
uint32_t current,
@@ -267,4 +275,5 @@ GIT_EXTERN(void) git_packbuilder_free(git_packbuilder *pb);
/** @} */
GIT_END_DECL
#endif

5
include/git2/patch.h
View File

@@ -14,7 +14,7 @@
/**
* @file git2/patch.h
* @brief Patch handling routines.
* @brief Patches store the textual diffs in a delta
* @ingroup Git
* @{
*/
@@ -283,8 +283,7 @@ GIT_EXTERN(int) git_patch_to_buf(
git_buf *out,
git_patch *patch);
/**@}*/
GIT_END_DECL
/**@}*/
#endif

9
include/git2/pathspec.h
View File

@@ -12,6 +12,13 @@
#include "strarray.h"
#include "diff.h"
/**
* @file git2/pathspec.h
* @brief Specifiers for path matching
* @defgroup git_pathspec Specifiers for path matching
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
@@ -276,5 +283,7 @@ GIT_EXTERN(size_t) git_pathspec_match_list_failed_entrycount(
GIT_EXTERN(const char *) git_pathspec_match_list_failed_entry(
const git_pathspec_match_list *m, size_t pos);
/** @} */
GIT_END_DECL
#endif

10
include/git2/proxy.h
View File

@@ -12,6 +12,12 @@
#include "cert.h"
#include "credential.h"
/**
* @file git2/proxy.h
* @brief TLS proxies
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
@@ -78,7 +84,10 @@ typedef struct {
void *payload;
} git_proxy_options;
/** Current version for the `git_proxy_options` structure */
#define GIT_PROXY_OPTIONS_VERSION 1
/** Static constructor for `git_proxy_options` */
#define GIT_PROXY_OPTIONS_INIT {GIT_PROXY_OPTIONS_VERSION}
/**
@@ -93,6 +102,7 @@ typedef struct {
*/
GIT_EXTERN(int) git_proxy_options_init(git_proxy_options *opts, unsigned int version);
/** @} */
GIT_END_DECL
#endif

8
include/git2/rebase.h
View File

@@ -17,8 +17,8 @@
/**
* @file git2/rebase.h
* @brief Git rebase routines
* @defgroup git_rebase Git merge routines
* @brief Rebase manipulates commits, placing them on a new parent
* @defgroup git_rebase Rebase manipulates commits, placing them on a new parent
* @ingroup Git
* @{
*/
@@ -154,7 +154,10 @@ typedef enum {
GIT_REBASE_OPERATION_EXEC
} git_rebase_operation_t;
/** Current version for the `git_rebase_options` structure */
#define GIT_REBASE_OPTIONS_VERSION 1
/** Static constructor for `git_rebase_options` */
#define GIT_REBASE_OPTIONS_INIT \
{ GIT_REBASE_OPTIONS_VERSION, 0, 0, NULL, GIT_MERGE_OPTIONS_INIT, \
GIT_CHECKOUT_OPTIONS_INIT, NULL, NULL }
@@ -395,4 +398,5 @@ GIT_EXTERN(void) git_rebase_free(git_rebase *rebase);
/** @} */
GIT_END_DECL
#endif

4
include/git2/refdb.h
View File

@@ -14,8 +14,8 @@
/**
* @file git2/refdb.h
* @brief Git custom refs backend functions
* @defgroup git_refdb Git custom refs backend API
* @brief A database for references (branches and tags)
* @defgroup git_refdb A database for references (branches and tags)
* @ingroup Git
* @{
*/

5
include/git2/reflog.h
View File

@@ -13,8 +13,8 @@
/**
* @file git2/reflog.h
* @brief Git reflog management routines
* @defgroup git_reflog Git reflog management routines
* @brief Reference logs store how references change
* @defgroup git_reflog Reference logs store how references change
* @ingroup Git
* @{
*/
@@ -167,4 +167,5 @@ GIT_EXTERN(void) git_reflog_free(git_reflog *reflog);
/** @} */
GIT_END_DECL
#endif

15
include/git2/refs.h
View File

@@ -14,8 +14,8 @@
/**
* @file git2/refs.h
* @brief Git reference management routines
* @defgroup git_reference Git reference management routines
* @brief References point to a commit; generally these are branches and tags
* @defgroup git_reference References point to a commit; generally these are branches and tags
* @ingroup Git
* @{
*/
@@ -29,7 +29,7 @@ GIT_BEGIN_DECL
* The name will be checked for validity.
* See `git_reference_symbolic_create()` for rules about valid names.
*
* @param out pointer to the looked-up reference
* @param[out] out pointer to the looked-up reference
* @param repo the repository to look up the reference
* @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...)
* @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code.
@@ -371,6 +371,7 @@ GIT_EXTERN(int) git_reference_set_target(
* reflog is enabled for the repository. We only rename
* the reflog if it exists.
*
* @param[out] new_ref The new reference
* @param ref The reference to rename
* @param new_name The new name for the reference
* @param force Overwrite an existing reference
@@ -406,6 +407,7 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref);
* This method removes the named reference from the repository without
* looking at its old value.
*
* @param repo The repository to remove the reference from
* @param name The reference to remove
* @return 0 or an error code
*/
@@ -518,7 +520,7 @@ GIT_EXTERN(int) git_reference_cmp(
/**
* Create an iterator for the repo's references
*
* @param out pointer in which to store the iterator
* @param[out] out pointer in which to store the iterator
* @param repo the repository
* @return 0 or an error code
*/
@@ -543,7 +545,7 @@ GIT_EXTERN(int) git_reference_iterator_glob_new(
/**
* Get the next reference
*
* @param out pointer in which to store the reference
* @param[out] out pointer in which to store the reference
* @param iter the iterator
* @return 0, GIT_ITEROVER if there are no more; or an error code
*/
@@ -724,7 +726,7 @@ GIT_EXTERN(int) git_reference_normalize_name(
* If you pass `GIT_OBJECT_ANY` as the target type, then the object
* will be peeled until a non-tag object is met.
*
* @param out Pointer to the peeled git_object
* @param[out] out Pointer to the peeled git_object
* @param ref The reference to be processed
* @param type The type of the requested object (GIT_OBJECT_COMMIT,
* GIT_OBJECT_TAG, GIT_OBJECT_TREE, GIT_OBJECT_BLOB or GIT_OBJECT_ANY).
@@ -768,4 +770,5 @@ GIT_EXTERN(const char *) git_reference_shorthand(const git_reference *ref);
/** @} */
GIT_END_DECL
#endif

7
include/git2/refspec.h
View File

@@ -14,8 +14,8 @@
/**
* @file git2/refspec.h
* @brief Git refspec attributes
* @defgroup git_refspec Git refspec attributes
* @brief Refspecs map local references to remote references
* @defgroup git_refspec Refspecs map local references to remote references
* @ingroup Git
* @{
*/
@@ -79,7 +79,7 @@ GIT_EXTERN(int) git_refspec_force(const git_refspec *refspec);
GIT_EXTERN(git_direction) git_refspec_direction(const git_refspec *spec);
/**
* Check if a refspec's source descriptor matches a reference
* Check if a refspec's source descriptor matches a reference
*
* @param refspec the refspec
* @param refname the name of the reference to check
@@ -116,6 +116,7 @@ GIT_EXTERN(int) git_refspec_transform(git_buf *out, const git_refspec *spec, con
*/
GIT_EXTERN(int) git_refspec_rtransform(git_buf *out, const git_refspec *spec, const char *name);
/** @} */
GIT_END_DECL
#endif

47
include/git2/remote.h
View File

@@ -19,8 +19,8 @@
/**
* @file git2/remote.h
* @brief Git remote management functions
* @defgroup git_remote remote management functions
* @brief Remotes are where local repositories fetch from and push to
* @defgroup git_remote Remotes are where local repositories fetch from and push to
* @ingroup Git
* @{
*/
@@ -116,7 +116,10 @@ typedef struct git_remote_create_options {
unsigned int flags;
} git_remote_create_options;
/** Current version for the `git_remote_create_options` structure */
#define GIT_REMOTE_CREATE_OPTIONS_VERSION 1
/** Static constructor for `git_remote_create_options` */
#define GIT_REMOTE_CREATE_OPTIONS_INIT {GIT_REMOTE_CREATE_OPTIONS_VERSION}
/**
@@ -466,7 +469,15 @@ typedef enum git_remote_completion_t {
GIT_REMOTE_COMPLETION_ERROR
} git_remote_completion_t;
/** Push network progress notification function */
/**
* Push network progress notification callback.
*
* @param current The number of objects pushed so far
* @param total The total number of objects to push
* @param bytes The number of bytes pushed
* @param payload The user-specified payload callback
* @return 0 or an error code to stop the transfer
*/
typedef int GIT_CALLBACK(git_push_transfer_progress_cb)(
unsigned int current,
unsigned int total,
@@ -502,8 +513,12 @@ typedef struct {
* as commands to the destination.
* @param len number of elements in `updates`
* @param payload Payload provided by the caller
* @return 0 or an error code to stop the push
*/
typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload);
typedef int GIT_CALLBACK(git_push_negotiation)(
const git_push_update **updates,
size_t len,
void *payload);
/**
* Callback used to inform of the update status from the remote.
@@ -682,7 +697,10 @@ struct git_remote_callbacks {
void *data);
};
/** Current version for the `git_remote_callbacks_options` structure */
#define GIT_REMOTE_CALLBACKS_VERSION 1
/** Static constructor for `git_remote_callbacks_options` */
#define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION}
/**
@@ -809,7 +827,10 @@ typedef struct {
git_strarray custom_headers;
} git_fetch_options;
/** Current version for the `git_fetch_options` structure */
#define GIT_FETCH_OPTIONS_VERSION 1
/** Static constructor for `git_fetch_options` */
#define GIT_FETCH_OPTIONS_INIT { \
GIT_FETCH_OPTIONS_VERSION, \
GIT_REMOTE_CALLBACKS_INIT, \
@@ -877,7 +898,10 @@ typedef struct {
git_strarray remote_push_options;
} git_push_options;
/** Current version for the `git_push_options` structure */
#define GIT_PUSH_OPTIONS_VERSION 1
/** Static constructor for `git_push_options` */
#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
/**
@@ -921,7 +945,10 @@ typedef struct {
git_strarray custom_headers;
} git_remote_connect_options;
/** Current version for the `git_remote_connect_options` structure */
#define GIT_REMOTE_CONNECT_OPTIONS_VERSION 1
/** Static constructor for `git_remote_connect_options` */
#define GIT_REMOTE_CONNECT_OPTIONS_INIT { \
GIT_REMOTE_CONNECT_OPTIONS_VERSION, \
GIT_REMOTE_CALLBACKS_INIT, \
@@ -1041,14 +1068,14 @@ GIT_EXTERN(int) git_remote_upload(
* `git_remote_connect` will be used (if it was called).
*
* @param remote the remote to update
* @param reflog_message The message to insert into the reflogs. If
* NULL and fetching, the default is "fetch <name>", where <name> is
* the name of the remote (or its url, for in-memory remotes). This
* parameter is ignored when pushing.
* @param callbacks pointer to the callback structure to use or NULL
* @param update_flags the git_remote_update_flags for these tips.
* @param download_tags what the behaviour for downloading tags is for this fetch. This is
* ignored for push. This must be the same value passed to `git_remote_download()`.
* @param reflog_message The message to insert into the reflogs. If
* NULL and fetching, the default is "fetch <name>", where <name> is
* the name of the remote (or its url, for in-memory remotes). This
* parameter is ignored when pushing.
* @return 0 or an error code
*/
GIT_EXTERN(int) git_remote_update_tips(
@@ -1116,6 +1143,9 @@ GIT_EXTERN(int) git_remote_push(
/**
* Get the statistics structure that is filled in by the fetch operation.
*
* @param remote the remote to get statistics for
* @return the git_indexer_progress for the remote
*/
GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote);
@@ -1215,4 +1245,5 @@ GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote);
/** @} */
GIT_END_DECL
#endif

73
include/git2/repository.h
View File

@@ -15,8 +15,8 @@
/**
* @file git2/repository.h
* @brief Git repository management routines
* @defgroup git_repository Git repository management routines
* @brief The repository stores revisions for a source tree
* @defgroup git_repository The repository stores revisions for a source tree
* @ingroup Git
* @{
*/
@@ -31,7 +31,11 @@ GIT_BEGIN_DECL
* The method will automatically detect if 'path' is a normal
* or bare repository or fail is 'path' is neither.
*
* @param out pointer to the repo which will be opened
* Note that the libgit2 library _must_ be initialized using
* `git_libgit2_init` before any APIs can be called, including
* this one.
*
* @param[out] out pointer to the repo which will be opened
* @param path the path to the repository
* @return 0 or an error code
*/
@@ -48,6 +52,15 @@ GIT_EXTERN(int) git_repository_open(git_repository **out, const char *path);
*/
GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_worktree *wt);
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_repository_wrap_odb(
git_repository **out,
git_odb *odb,
git_oid_t oid_type);
#else
/**
* Create a "fake" repository to wrap an object database
*
@@ -57,18 +70,12 @@ GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_work
*
* @param out pointer to the repo
* @param odb the object database to wrap
* @param oid_type the oid type of the object database
* @return 0 or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_repository_wrap_odb(
git_repository **out,
git_odb *odb,
git_oid_t oid_type);
#else
GIT_EXTERN(int) git_repository_wrap_odb(
git_repository **out,
git_odb *odb);
#endif
/**
@@ -81,6 +88,10 @@ GIT_EXTERN(int) git_repository_wrap_odb(
* The method will automatically detect if the repository is bare
* (if there is a repository).
*
* Note that the libgit2 library _must_ be initialized using
* `git_libgit2_init` before any APIs can be called, including
* this one.
*
* @param out A pointer to a user-allocated git_buf which will contain
* the found path.
*
@@ -158,7 +169,11 @@ typedef enum {
/**
* Find and open a repository with extended controls.
*
* @param out Pointer to the repo which will be opened. This can
* Note that the libgit2 library _must_ be initialized using
* `git_libgit2_init` before any APIs can be called, including
* this one.
*
* @param[out] out Pointer to the repo which will be opened. This can
* actually be NULL if you only want to use the error code to
* see if a repo at this path could be opened.
* @param path Path to open as git repository. If the flags
@@ -186,7 +201,11 @@ GIT_EXTERN(int) git_repository_open_ext(
* if you're e.g. hosting git repositories and need to access them
* efficiently
*
* @param out Pointer to the repo which will be opened.
* Note that the libgit2 library _must_ be initialized using
* `git_libgit2_init` before any APIs can be called, including
* this one.
*
* @param[out] out Pointer to the repo which will be opened.
* @param bare_path Direct path to the bare repository
* @return 0 on success, or an error code
*/
@@ -211,7 +230,11 @@ GIT_EXTERN(void) git_repository_free(git_repository *repo);
* TODO:
* - Reinit the repository
*
* @param out pointer to the repo which will be created or reinitialized
* Note that the libgit2 library _must_ be initialized using
* `git_libgit2_init` before any APIs can be called, including
* this one.
*
* @param[out] out pointer to the repo which will be created or reinitialized
* @param path the path to the repository
* @param is_bare if true, a Git repository without a working directory is
* created at the pointed path. If false, provided path will be
@@ -373,7 +396,10 @@ typedef struct {
#endif
} git_repository_init_options;
/** Current version for the `git_repository_init_options` structure */
#define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1
/** Static constructor for `git_repository_init_options` */
#define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION}
/**
@@ -398,6 +424,10 @@ GIT_EXTERN(int) git_repository_init_options_init(
* auto-detect the case sensitivity of the file system and if the
* file system supports file mode bits correctly.
*
* Note that the libgit2 library _must_ be initialized using
* `git_libgit2_init` before any APIs can be called, including
* this one.
*
* @param out Pointer to the repo which will be created or reinitialized.
* @param repo_path The path to the repository.
* @param opts Pointer to git_repository_init_options struct.
@@ -415,7 +445,7 @@ GIT_EXTERN(int) git_repository_init_ext(
* `git_reference_free()` must be called when done with it to release the
* allocated memory and prevent a leak.
*
* @param out pointer to the reference which will be retrieved
* @param[out] out pointer to the reference which will be retrieved
* @param repo a repository object
*
* @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
@@ -636,7 +666,7 @@ GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository
* The ODB must be freed once it's no longer being used by
* the user.
*
* @param out Pointer to store the loaded ODB
* @param[out] out Pointer to store the loaded ODB
* @param repo A repository object
* @return 0, or an error code
*/
@@ -652,7 +682,7 @@ GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo);
* The refdb must be freed once it's no longer being used by
* the user.
*
* @param out Pointer to store the loaded refdb
* @param[out] out Pointer to store the loaded refdb
* @param repo A repository object
* @return 0, or an error code
*/
@@ -668,7 +698,7 @@ GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo);
* The index must be freed once it's no longer being used by
* the user.
*
* @param out Pointer to store the loaded index
* @param[out] out Pointer to store the loaded index
* @param repo A repository object
* @return 0, or an error code
*/
@@ -858,7 +888,9 @@ GIT_EXTERN(int) git_repository_set_head_detached(
*
* See the documentation for `git_repository_set_head_detached()`.
*
* @see git_repository_set_head_detached
* @param repo Repository pointer
* @param committish annotated commit to point HEAD to
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_repository_set_head_detached_from_annotated(
git_repository *repo,
@@ -951,8 +983,8 @@ GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo);
* The memory is owned by the repository and must not be freed by the
* user.
*
* @param name where to store the pointer to the name
* @param email where to store the pointer to the email
* @param[out] name where to store the pointer to the name
* @param[out] email where to store the pointer to the email
* @param repo the repository
* @return 0 or an error code
*/
@@ -993,4 +1025,5 @@ GIT_EXTERN(int) git_repository_commit_parents(git_commitarray *commits, git_repo
/** @} */
GIT_END_DECL
#endif

19
include/git2/reset.h
View File

@@ -14,7 +14,7 @@
/**
* @file git2/reset.h
* @brief Git reset management routines
* @brief Reset will update the local repository to a prior state
* @ingroup Git
* @{
*/
@@ -75,11 +75,23 @@ GIT_EXTERN(int) git_reset(
*
* See the documentation for `git_reset()`.
*
* @see git_reset
* @param repo Repository where to perform the reset operation.
*
* @param target Annotated commit to which the Head should be moved to.
* This object must belong to the given `repo`, it will be dereferenced
* to a git_commit which oid will be used as the target of the branch.
*
* @param reset_type Kind of reset operation to perform.
*
* @param checkout_opts Optional checkout options to be used for a HARD reset.
* The checkout_strategy field will be overridden (based on reset_type).
* This parameter can be used to propagate notify and progress callbacks.
*
* @return 0 on success or an error code
*/
GIT_EXTERN(int) git_reset_from_annotated(
git_repository *repo,
const git_annotated_commit *commit,
const git_annotated_commit *target,
git_reset_t reset_type,
const git_checkout_options *checkout_opts);
@@ -108,4 +120,5 @@ GIT_EXTERN(int) git_reset_default(
/** @} */
GIT_END_DECL
#endif

13
include/git2/revert.h
View File

@@ -13,8 +13,8 @@
/**
* @file git2/revert.h
* @brief Git revert routines
* @defgroup git_revert Git revert routines
* @brief Cherry-pick the inverse of a change to "undo" its effects
* @defgroup git_revert Cherry-pick the inverse of a change to "undo" its effects
* @ingroup Git
* @{
*/
@@ -33,8 +33,13 @@ typedef struct {
git_checkout_options checkout_opts; /**< Options for the checkout */
} git_revert_options;
/** Current version for the `git_revert_options` structure */
#define GIT_REVERT_OPTIONS_VERSION 1
#define GIT_REVERT_OPTIONS_INIT {GIT_REVERT_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT}
/** Static constructor for `git_revert_options` */
#define GIT_REVERT_OPTIONS_INIT { \
GIT_REVERT_OPTIONS_VERSION, 0, \
GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT }
/**
* Initialize git_revert_options structure
@@ -87,5 +92,5 @@ GIT_EXTERN(int) git_revert(
/** @} */
GIT_END_DECL
#endif
#endif

6
include/git2/revparse.h
View File

@@ -12,8 +12,8 @@
/**
* @file git2/revparse.h
* @brief Git revision parsing routines
* @defgroup git_revparse Git revision parsing routines
* @brief Parse the textual revision information
* @defgroup git_revparse Parse the textual revision information
* @ingroup Git
* @{
*/
@@ -107,7 +107,7 @@ GIT_EXTERN(int) git_revparse(
git_repository *repo,
const char *spec);
/** @} */
GIT_END_DECL
#endif

5
include/git2/revwalk.h
View File

@@ -13,8 +13,8 @@
/**
* @file git2/revwalk.h
* @brief Git revision traversal routines
* @defgroup git_revwalk Git revision traversal routines
* @brief Traverse (walk) the commit graph (revision history)
* @defgroup git_revwalk Traverse (walk) the commit graph (revision history)
* @ingroup Git
* @{
*/
@@ -299,4 +299,5 @@ GIT_EXTERN(int) git_revwalk_add_hide_cb(
/** @} */
GIT_END_DECL
#endif

7
include/git2/signature.h
View File

@@ -12,9 +12,13 @@
/**
* @file git2/signature.h
* @brief Git signature creation
* @brief Signatures are the actor in a repository and when they acted
* @defgroup git_signature Git signature creation
* @ingroup Git
*
* Signatures contain the information about the actor (committer or
* author) in a repository, and the time that they performed the
* commit, or authoring.
* @{
*/
GIT_BEGIN_DECL
@@ -140,4 +144,5 @@ GIT_EXTERN(void) git_signature_free(git_signature *sig);
/** @} */
GIT_END_DECL
#endif

18
include/git2/stash.h
View File

@@ -13,8 +13,13 @@
/**
* @file git2/stash.h
* @brief Git stash management routines
* @brief Stashes stores some uncommitted state in the repository
* @ingroup Git
*
* Stashes stores some uncommitted state in the repository; generally
* this allows a user to stash some changes so that they can restore
* the working directory to an unmodified state. This can allow a
* developer to work on two different changes in parallel.
* @{
*/
GIT_BEGIN_DECL
@@ -94,7 +99,10 @@ typedef struct git_stash_save_options {
git_strarray paths;
} git_stash_save_options;
/** Current version for the `git_stash_save_options` structure */
#define GIT_STASH_SAVE_OPTIONS_VERSION 1
/** Static constructor for `git_stash_save_options` */
#define GIT_STASH_SAVE_OPTIONS_INIT { GIT_STASH_SAVE_OPTIONS_VERSION }
/**
@@ -165,6 +173,10 @@ typedef enum {
* Stash application progress notification function.
* Return 0 to continue processing, or a negative value to
* abort the stash application.
*
* @param progress the progress information
* @param payload the user-specified payload to the apply function
* @return 0 on success, -1 on error
*/
typedef int GIT_CALLBACK(git_stash_apply_progress_cb)(
git_stash_apply_progress_t progress,
@@ -191,7 +203,10 @@ typedef struct git_stash_apply_options {
void *progress_payload;
} git_stash_apply_options;
/** Current version for the `git_stash_apply_options` structure */
#define GIT_STASH_APPLY_OPTIONS_VERSION 1
/** Static constructor for `git_stash_apply_options` */
#define GIT_STASH_APPLY_OPTIONS_INIT { \
GIT_STASH_APPLY_OPTIONS_VERSION, \
GIT_STASH_APPLY_DEFAULT, \
@@ -309,4 +324,5 @@ GIT_EXTERN(int) git_stash_pop(
/** @} */
GIT_END_DECL
#endif

16
include/git2/status.h
View File

@@ -14,7 +14,7 @@
/**
* @file git2/status.h
* @brief Git file status routines
* @brief Status indicates how a user has changed the working directory and index
* @defgroup git_status Git file status routines
* @ingroup Git
* @{
@@ -54,11 +54,10 @@ typedef enum {
/**
* Function pointer to receive status on individual files
*
* `path` is the relative path to the file from the root of the repository.
*
* `status_flags` is a combination of `git_status_t` values that apply.
*
* `payload` is the value you passed to the foreach function as payload.
* @param path is the path to the file
* @param status_flags the `git_status_t` values for file's status
* @param payload the user-specified payload to the foreach function
* @return 0 on success, or a negative number on failure
*/
typedef int GIT_CALLBACK(git_status_cb)(
const char *path, unsigned int status_flags, void *payload);
@@ -207,6 +206,7 @@ typedef enum {
GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15)
} git_status_opt_t;
/** Default `git_status_opt_t` values */
#define GIT_STATUS_OPT_DEFAULTS \
(GIT_STATUS_OPT_INCLUDE_IGNORED | \
GIT_STATUS_OPT_INCLUDE_UNTRACKED | \
@@ -261,7 +261,10 @@ typedef struct {
uint16_t rename_threshold;
} git_status_options;
/** Current version for the `git_status_options` structure */
#define GIT_STATUS_OPTIONS_VERSION 1
/** Static constructor for `git_status_options` */
#define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION}
/**
@@ -449,4 +452,5 @@ GIT_EXTERN(int) git_status_should_ignore(
/** @} */
GIT_END_DECL
#endif

5
include/git2/strarray.h
View File

@@ -11,8 +11,8 @@
/**
* @file git2/strarray.h
* @brief Git string array routines
* @defgroup git_strarray Git string array routines
* @brief An array of strings for the user to free
* @defgroup git_strarray An array of strings for the user to free
* @ingroup Git
* @{
*/
@@ -40,4 +40,3 @@ GIT_EXTERN(void) git_strarray_dispose(git_strarray *array);
GIT_END_DECL
#endif

18
include/git2/submodule.h
View File

@@ -15,7 +15,7 @@
/**
* @file git2/submodule.h
* @brief Git submodule management utilities
* @brief Submodules place another repository's contents within this one
*
* Submodule support in libgit2 builds a list of known submodules and keeps
* it in the repository. The list is built from the .gitmodules file, the
@@ -88,20 +88,27 @@ typedef enum {
GIT_SUBMODULE_STATUS_WD_UNTRACKED = (1u << 13)
} git_submodule_status_t;
/** Submodule source bits */
#define GIT_SUBMODULE_STATUS__IN_FLAGS 0x000Fu
/** Submodule index status */
#define GIT_SUBMODULE_STATUS__INDEX_FLAGS 0x0070u
/** Submodule working directory status */
#define GIT_SUBMODULE_STATUS__WD_FLAGS 0x3F80u
/** Whether the submodule is modified */
#define GIT_SUBMODULE_STATUS_IS_UNMODIFIED(S) \
(((S) & ~GIT_SUBMODULE_STATUS__IN_FLAGS) == 0)
/** Whether the submodule is modified (in the index) */
#define GIT_SUBMODULE_STATUS_IS_INDEX_UNMODIFIED(S) \
(((S) & GIT_SUBMODULE_STATUS__INDEX_FLAGS) == 0)
/** Whether the submodule is modified (in the working directory) */
#define GIT_SUBMODULE_STATUS_IS_WD_UNMODIFIED(S) \
(((S) & (GIT_SUBMODULE_STATUS__WD_FLAGS & \
~GIT_SUBMODULE_STATUS_WD_UNINITIALIZED)) == 0)
/** Whether the submodule working directory is dirty */
#define GIT_SUBMODULE_STATUS_IS_WD_DIRTY(S) \
(((S) & (GIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED | \
GIT_SUBMODULE_STATUS_WD_WD_MODIFIED | \
@@ -150,7 +157,10 @@ typedef struct git_submodule_update_options {
int allow_fetch;
} git_submodule_update_options;
/** Current version for the `git_submodule_update_options` structure */
#define GIT_SUBMODULE_UPDATE_OPTIONS_VERSION 1
/** Static constructor for `git_submodule_update_options` */
#define GIT_SUBMODULE_UPDATE_OPTIONS_INIT \
{ GIT_SUBMODULE_UPDATE_OPTIONS_VERSION, \
GIT_CHECKOUT_OPTIONS_INIT, \
@@ -530,7 +540,8 @@ GIT_EXTERN(int) git_submodule_set_update(
* Note that at this time, libgit2 does not honor this setting and the
* fetch functionality current ignores submodules.
*
* @return 0 if fetchRecurseSubmodules is false, 1 if true
* @param submodule the submodule to examine
* @return the submodule recursion configuration
*/
GIT_EXTERN(git_submodule_recurse_t) git_submodule_fetch_recurse_submodules(
git_submodule *submodule);
@@ -542,7 +553,7 @@ GIT_EXTERN(git_submodule_recurse_t) git_submodule_fetch_recurse_submodules(
*
* @param repo the repository to affect
* @param name the submodule to configure
* @param fetch_recurse_submodules Boolean value
* @param fetch_recurse_submodules the submodule recursion configuration
* @return old value for fetchRecurseSubmodules
*/
GIT_EXTERN(int) git_submodule_set_fetch_recurse_submodules(
@@ -664,4 +675,5 @@ GIT_EXTERN(int) git_submodule_location(
/** @} */
GIT_END_DECL
#endif

12
include/git2/sys/alloc.h
View File

@@ -10,6 +10,17 @@
#include "git2/common.h"
/**
* @file git2/sys/alloc.h
* @brief Custom memory allocators
* @defgroup git_merge Git merge routines
* @ingroup Git
*
* Users can configure custom allocators; this is particularly
* interesting when running in constrained environments, when calling
* from another language, or during testing.
* @{
*/
GIT_BEGIN_DECL
/**
@@ -62,6 +73,7 @@ int git_stdalloc_init_allocator(git_allocator *allocator);
*/
int git_win32_crtdbg_init_allocator(git_allocator *allocator);
/** @} */
GIT_END_DECL
#endif

80
include/git2/sys/commit.h
View File

@@ -14,7 +14,7 @@
/**
* @file git2/sys/commit.h
* @brief Low-level Git commit creation
* @defgroup git_backend Git custom backend APIs
* @defgroup git_commit Low-level Git commit creation
* @ingroup Git
* @{
*/
@@ -29,7 +29,43 @@ GIT_BEGIN_DECL
* the `tree`, neither the `parents` list of `git_oid`s are checked for
* validity.
*
* @see git_commit_create
* @param id Pointer in which to store the OID of the newly created commit
*
* @param repo Repository where to store the commit
*
* @param update_ref If not NULL, name of the reference that
* will be updated to point to this commit. If the reference
* is not direct, it will be resolved to a direct reference.
* Use "HEAD" to update the HEAD of the current branch and
* make it point to this commit. If the reference doesn't
* exist yet, it will be created. If it does exist, the first
* parent must be the tip of this branch.
*
* @param author Signature with author and author time of commit
*
* @param committer Signature with committer and * commit time of commit
*
* @param message_encoding The encoding for the message in the
* commit, represented with a standard encoding name.
* E.g. "UTF-8". If NULL, no encoding header is written and
* UTF-8 is assumed.
*
* @param message Full message for this commit
*
* @param tree An instance of a `git_tree` object that will
* be used as the tree for the commit. This tree object must
* also be owned by the given `repo`.
*
* @param parent_count Number of parents for this commit
*
* @param parents Array of `parent_count` pointers to `git_commit`
* objects that will be used as the parents for this commit. This
* array may be NULL if `parent_count` is 0 (root commit). All the
* given commits must be owned by the `repo`.
*
* @return 0 or an error code
* The created commit will be written to the Object Database and
* the given reference will be updated to point to it
*/
GIT_EXTERN(int) git_commit_create_from_ids(
git_oid *id,
@@ -49,6 +85,10 @@ GIT_EXTERN(int) git_commit_create_from_ids(
* This is invoked with the count of the number of parents processed so far
* along with the user supplied payload. This should return a git_oid of
* the next parent or NULL if all parents have been provided.
*
* @param idx the index of the parent
* @param payload the user-specified payload
* @return the object id of the parent, or NULL if there are no further parents
*/
typedef const git_oid * GIT_CALLBACK(git_commit_parent_callback)(size_t idx, void *payload);
@@ -61,7 +101,40 @@ typedef const git_oid * GIT_CALLBACK(git_commit_parent_callback)(size_t idx, voi
* with `parent_payload` and should return `git_oid` values or NULL to
* indicate that all parents are accounted for.
*
* @see git_commit_create
* @param id Pointer in which to store the OID of the newly created commit
*
* @param repo Repository where to store the commit
*
* @param update_ref If not NULL, name of the reference that
* will be updated to point to this commit. If the reference
* is not direct, it will be resolved to a direct reference.
* Use "HEAD" to update the HEAD of the current branch and
* make it point to this commit. If the reference doesn't
* exist yet, it will be created. If it does exist, the first
* parent must be the tip of this branch.
*
* @param author Signature with author and author time of commit
*
* @param committer Signature with committer and * commit time of commit
*
* @param message_encoding The encoding for the message in the
* commit, represented with a standard encoding name.
* E.g. "UTF-8". If NULL, no encoding header is written and
* UTF-8 is assumed.
*
* @param message Full message for this commit
*
* @param tree An instance of a `git_tree` object that will
* be used as the tree for the commit. This tree object must
* also be owned by the given `repo`.
*
* @param parent_cb Callback to invoke to obtain parent information
*
* @param parent_payload User-specified payload to provide to the callback
*
* @return 0 or an error code
* The created commit will be written to the Object Database and
* the given reference will be updated to point to it
*/
GIT_EXTERN(int) git_commit_create_from_callback(
git_oid *id,
@@ -77,4 +150,5 @@ GIT_EXTERN(int) git_commit_create_from_callback(
/** @} */
GIT_END_DECL
#endif

8
include/git2/sys/commit_graph.h
View File

@@ -12,8 +12,8 @@
/**
* @file git2/sys/commit_graph.h
* @brief Git commit-graph
* @defgroup git_commit_graph Git commit-graph APIs
* @brief Commit graphs store information about commit relationships
* @defgroup git_commit_graph Commit graphs
* @ingroup Git
* @{
*/
@@ -136,7 +136,10 @@ typedef struct {
size_t max_commits;
} git_commit_graph_writer_options;
/** Current version for the `git_commit_graph_writer_options` structure */
#define GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION 1
/** Static constructor for `git_commit_graph_writer_options` */
#define GIT_COMMIT_GRAPH_WRITER_OPTIONS_INIT { \
GIT_COMMIT_GRAPH_WRITER_OPTIONS_VERSION \
}
@@ -181,4 +184,5 @@ GIT_EXTERN(int) git_commit_graph_writer_dump(
/** @} */
GIT_END_DECL
#endif

19
include/git2/sys/config.h
View File

@@ -13,14 +13,19 @@
/**
* @file git2/sys/config.h
* @brief Git config backend routines
* @defgroup git_backend Git custom backend APIs
* @brief Custom configuration database backends
* @defgroup git_backend Custom configuration database backends
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* An entry in a configuration backend. This is provided so that
* backend implementors can have a mechanism to free their data.
*/
typedef struct git_config_backend_entry {
/** The base configuration entry */
struct git_config_entry entry;
/**
@@ -93,7 +98,11 @@ struct git_config_backend {
int GIT_CALLBACK(unlock)(struct git_config_backend *, int success);
void GIT_CALLBACK(free)(struct git_config_backend *);
};
/** Current version for the `git_config_backend_options` structure */
#define GIT_CONFIG_BACKEND_VERSION 1
/** Static constructor for `git_config_backend_options` */
#define GIT_CONFIG_BACKEND_INIT {GIT_CONFIG_BACKEND_VERSION}
/**
@@ -152,7 +161,10 @@ typedef struct {
const char *origin_path;
} git_config_backend_memory_options;
/** Current version for the `git_config_backend_memory_options` structure */
#define GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION 1
/** Static constructor for `git_config_backend_memory_options` */
#define GIT_CONFIG_BACKEND_MEMORY_OPTIONS_INIT { GIT_CONFIG_BACKEND_MEMORY_OPTIONS_VERSION }
@@ -164,6 +176,7 @@ typedef struct {
* @param cfg the configuration that is to be parsed
* @param len the length of the string pointed to by `cfg`
* @param opts the options to initialize this backend with, or NULL
* @return 0 on success or an error code
*/
extern int git_config_backend_from_string(
git_config_backend **out,
@@ -179,6 +192,7 @@ extern int git_config_backend_from_string(
* @param values the configuration values to set (in "key=value" format)
* @param len the length of the values array
* @param opts the options to initialize this backend with, or NULL
* @return 0 on success or an error code
*/
extern int git_config_backend_from_values(
git_config_backend **out,
@@ -188,4 +202,5 @@ extern int git_config_backend_from_values(
/** @} */
GIT_END_DECL
#endif

7
include/git2/sys/credential.h
View File

@@ -11,9 +11,9 @@
#include "git2/credential.h"
/**
* @file git2/sys/cred.h
* @brief Git credentials low-level implementation
* @defgroup git_credential Git credentials low-level implementation
* @file git2/sys/credential.h
* @brief Low-level credentials implementation
* @defgroup git_credential Low-level credentials implementation
* @ingroup Git
* @{
*/
@@ -85,6 +85,7 @@ struct git_credential_ssh_custom {
void *payload; /**< Payload passed to prompt_callback */
};
/** @} */
GIT_END_DECL
#endif

22
include/git2/sys/diff.h
View File

@@ -15,7 +15,7 @@
/**
* @file git2/sys/diff.h
* @brief Low-level Git diff utilities
* @brief Low-level diff utilities
* @ingroup Git
* @{
*/
@@ -33,6 +33,12 @@ GIT_BEGIN_DECL
* must pass a `git_buf *` value as the payload to the `git_diff_print`
* and/or `git_patch_print` function. The data will be appended to the
* buffer (after any existing content).
*
* @param delta the delta being processed
* @param hunk the hunk being processed
* @param line the line being processed
* @param payload the payload provided by the diff generator
* @return 0 on success or an error code
*/
GIT_EXTERN(int) git_diff_print_callback__to_buf(
const git_diff_delta *delta,
@@ -53,6 +59,12 @@ GIT_EXTERN(int) git_diff_print_callback__to_buf(
* value from `fopen()`) as the payload to the `git_diff_print`
* and/or `git_patch_print` function. If you pass NULL, this will write
* data to `stdout`.
*
* @param delta the delta being processed
* @param hunk the hunk being processed
* @param line the line being processed
* @param payload the payload provided by the diff generator
* @return 0 on success or an error code
*/
GIT_EXTERN(int) git_diff_print_callback__to_file_handle(
const git_diff_delta *delta,
@@ -70,7 +82,10 @@ typedef struct {
size_t oid_calculations; /**< Number of ID calculations */
} git_diff_perfdata;
/** Current version for the `git_diff_perfdata_options` structure */
#define GIT_DIFF_PERFDATA_VERSION 1
/** Static constructor for `git_diff_perfdata_options` */
#define GIT_DIFF_PERFDATA_INIT {GIT_DIFF_PERFDATA_VERSION,0,0}
/**
@@ -85,10 +100,15 @@ GIT_EXTERN(int) git_diff_get_perfdata(
/**
* Get performance data for diffs from a git_status_list
*
* @param out Structure to be filled with diff performance data
* @param status Diff to read performance data from
* @return 0 for success, <0 for error
*/
GIT_EXTERN(int) git_status_list_get_perfdata(
git_diff_perfdata *out, const git_status_list *status);
/** @} */
GIT_END_DECL
#endif

2
include/git2/sys/email.h
View File

@@ -33,6 +33,7 @@ GIT_BEGIN_DECL
* @param body optional text to include above the diffstat
* @param author the person who authored this commit
* @param opts email creation options
* @return 0 on success or an error code
*/
GIT_EXTERN(int) git_email_create_from_diff(
git_buf *out,
@@ -47,4 +48,5 @@ GIT_EXTERN(int) git_email_create_from_diff(
/** @} */
GIT_END_DECL
#endif

10
include/git2/sys/errors.h
View File

@@ -10,6 +10,15 @@
#include "git2/common.h"
/**
* @file git2/sys/errors.h
* @brief Advanced error handling
* @ingroup Git
*
* Error handling for advanced consumers; those who use callbacks
* or those who create custom databases.
* @{
*/
GIT_BEGIN_DECL
/**
@@ -61,6 +70,7 @@ GIT_EXTERN(int) git_error_set_str(int error_class, const char *string);
*/
GIT_EXTERN(void) git_error_set_oom(void);
/** @} */
GIT_END_DECL
#endif

69
include/git2/sys/filter.h
View File

@@ -11,8 +11,8 @@
/**
* @file git2/sys/filter.h
* @brief Git filter backend and plugin routines
* @defgroup git_backend Git custom backend APIs
* @brief Custom filter backends and plugins
* @defgroup git_backend Custom filter backends and plugins
* @ingroup Git
* @{
*/
@@ -26,7 +26,10 @@ GIT_BEGIN_DECL
*/
GIT_EXTERN(git_filter *) git_filter_lookup(const char *name);
/** The "crlf" filter */
#define GIT_FILTER_CRLF "crlf"
/** The "ident" filter */
#define GIT_FILTER_IDENT "ident"
/**
@@ -53,6 +56,12 @@ GIT_EXTERN(git_filter *) git_filter_lookup(const char *name);
* the filter list for you, but you can use this in combination with the
* `git_filter_lookup` and `git_filter_list_push` functions to assemble
* your own chains of filters.
*
* @param out the filter list
* @param repo the repository to use for configuration
* @param mode the filter mode (direction)
* @param options the options
* @return 0 on success or an error code
*/
GIT_EXTERN(int) git_filter_list_new(
git_filter_list **out,
@@ -72,6 +81,11 @@ GIT_EXTERN(int) git_filter_list_new(
* filter. Using this function, you can either pass in a payload if you
* know the expected payload format, or you can pass NULL. Some filters
* may fail with a NULL payload. Good luck!
*
* @param fl the filter list
* @param filter the filter to push
* @param payload the payload for the filter
* @return 0 on success or an error code
*/
GIT_EXTERN(int) git_filter_list_push(
git_filter_list *fl, git_filter *filter, void *payload);
@@ -96,17 +110,26 @@ typedef struct git_filter_source git_filter_source;
/**
* Get the repository that the source data is coming from.
*
* @param src the filter source
* @return the repository for the filter information
*/
GIT_EXTERN(git_repository *) git_filter_source_repo(const git_filter_source *src);
/**
* Get the path that the source data is coming from.
*
* @param src the filter source
* @return the path that is being filtered
*/
GIT_EXTERN(const char *) git_filter_source_path(const git_filter_source *src);
/**
* Get the file mode of the source file
* If the mode is unknown, this will return 0
*
* @param src the filter source
* @return the file mode for the file being filtered
*/
GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src);
@@ -114,16 +137,25 @@ GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src);
* Get the OID of the source
* If the OID is unknown (often the case with GIT_FILTER_CLEAN) then
* this will return NULL.
*
* @param src the filter source
* @return the object id of the file being filtered
*/
GIT_EXTERN(const git_oid *) git_filter_source_id(const git_filter_source *src);
/**
* Get the git_filter_mode_t to be used
*
* @param src the filter source
* @return the mode (direction) of the filter
*/
GIT_EXTERN(git_filter_mode_t) git_filter_source_mode(const git_filter_source *src);
/**
* Get the combination git_filter_flag_t options to be applied
*
* @param src the filter source
* @return the flags of the filter
*/
GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src);
@@ -137,6 +169,9 @@ GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src);
* before the first use of the filter, so you can defer expensive
* initialization operations (in case libgit2 is being used in a way that
* doesn't need the filter).
*
* @param self the filter to initialize
* @return 0 on success, negative number on failure
*/
typedef int GIT_CALLBACK(git_filter_init_fn)(git_filter *self);
@@ -149,6 +184,8 @@ typedef int GIT_CALLBACK(git_filter_init_fn)(git_filter *self);
* This may be called even if the `initialize` callback was not made.
*
* Typically this function will free the `git_filter` object itself.
*
* @param self the filter to shutdown
*/
typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self);
@@ -171,6 +208,12 @@ typedef void GIT_CALLBACK(git_filter_shutdown_fn)(git_filter *self);
* allocated (not stack), so that it doesn't go away before the `stream`
* callback can use it. If a filter allocates and assigns a value to the
* `payload`, it will need a `cleanup` callback to free the payload.
*
* @param self the filter check
* @param payload a data for future filter functions
* @param src the filter source
* @param attr_values the attribute values
* @return 0 on success or a negative value on error
*/
typedef int GIT_CALLBACK(git_filter_check_fn)(
git_filter *self,
@@ -191,6 +234,12 @@ typedef int GIT_CALLBACK(git_filter_check_fn)(
* The `payload` value will refer to any payload that was set by the
* `check` callback. It may be read from or written to as needed.
*
* @param self the filter check
* @param payload a data for future filter functions
* @param to the input buffer
* @param from the output buffer
* @param src the filter source
* @return 0 on success or a negative value on error
* @deprecated use git_filter_stream_fn
*/
typedef int GIT_CALLBACK(git_filter_apply_fn)(
@@ -209,6 +258,13 @@ typedef int GIT_CALLBACK(git_filter_apply_fn)(
* `git_writestream` that will the original data will be written to;
* with that data, the `git_writestream` will then perform the filter
* translation and stream the filtered data out to the `next` location.
*
* @param out the write stream
* @param self the filter
* @param payload a data for future filter functions
* @param src the filter source
* @param next the output stream
* @return 0 on success or a negative value on error
*/
typedef int GIT_CALLBACK(git_filter_stream_fn)(
git_writestream **out,
@@ -225,6 +281,9 @@ typedef int GIT_CALLBACK(git_filter_stream_fn)(
* `stream` callbacks allocated a `payload` to keep per-source filter
* state, use this callback to free that payload and release resources
* as required.
*
* @param self the filter
* @param payload a data for future filter functions
*/
typedef void GIT_CALLBACK(git_filter_cleanup_fn)(
git_filter *self,
@@ -291,7 +350,10 @@ struct git_filter {
git_filter_cleanup_fn cleanup;
};
/** Current version for the `git_filter_options` structure */
#define GIT_FILTER_VERSION 1
/** Static constructor for `git_filter_options` */
#define GIT_FILTER_INIT {GIT_FILTER_VERSION}
/**
@@ -300,7 +362,7 @@ struct git_filter {
*
* @param filter the `git_filter` struct to initialize.
* @param version Version the struct; pass `GIT_FILTER_VERSION`
* @return Zero on success; -1 on failure.
* @return 0 on success; -1 on failure.
*/
GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version);
@@ -350,4 +412,5 @@ GIT_EXTERN(int) git_filter_unregister(const char *name);
/** @} */
GIT_END_DECL
#endif

11
include/git2/sys/hashsig.h
View File

@@ -9,6 +9,16 @@
#include "git2/common.h"
/**
* @file git2/sys/hashsig.h
* @brief Signatures for file similarity comparison
* @defgroup git_hashsig Git merge routines
* @ingroup Git
*
* Hash signatures are used for file similary comparison; this is
* used for git's rename handling.
* @{
*/
GIT_BEGIN_DECL
/**
@@ -101,6 +111,7 @@ GIT_EXTERN(int) git_hashsig_compare(
const git_hashsig *a,
const git_hashsig *b);
/** @} */
GIT_END_DECL
#endif

5
include/git2/sys/index.h
View File

@@ -12,8 +12,8 @@
/**
* @file git2/sys/index.h
* @brief Low-level Git index manipulation routines
* @defgroup git_backend Git custom backend APIs
* @brief Low-level index manipulation routines
* @defgroup git_index Low-level index manipulation routines
* @ingroup Git
* @{
*/
@@ -67,6 +67,7 @@ GIT_EXTERN(const git_index_name_entry *) git_index_name_get_byindex(
* @param ancestor the path of the file as it existed in the ancestor
* @param ours the path of the file as it existed in our tree
* @param theirs the path of the file as it existed in their tree
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_index_name_add(git_index *index,
const char *ancestor, const char *ours, const char *theirs);

15
include/git2/sys/mempack.h
View File

@@ -15,8 +15,8 @@
/**
* @file git2/sys/mempack.h
* @brief Custom ODB backend that permits packing objects in-memory
* @defgroup git_backend Git custom backend APIs
* @brief A custom object database backend for storing objects in-memory
* @defgroup git_mempack A custom object database backend for storing objects in-memory
* @ingroup Git
* @{
*/
@@ -60,6 +60,7 @@ GIT_EXTERN(int) git_mempack_new(git_odb_backend **out);
*
* @param backend The mempack backend
* @param pb The packbuilder to use to write the packfile
* @return 0 on success or an error code
*/
GIT_EXTERN(int) git_mempack_write_thin_pack(git_odb_backend *backend, git_packbuilder *pb);
@@ -101,6 +102,16 @@ GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_ba
*/
GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend);
/**
* Get the total number of objects in mempack
*
* @param count The count of objects in the mempack
* @param backend The mempack backend
* @return 0 on success, or -1 on error
*/
GIT_EXTERN(int) git_mempack_object_count(size_t *count, git_odb_backend *backend);
/** @} */
GIT_END_DECL
#endif

62
include/git2/sys/merge.h
View File

@@ -14,13 +14,18 @@
/**
* @file git2/sys/merge.h
* @brief Git merge driver backend and plugin routines
* @defgroup git_merge Git merge driver APIs
* @brief Custom merge drivers
* @defgroup git_merge Custom merge drivers
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* A "merge driver" is a mechanism that can be configured to handle
* conflict resolution for files changed in both the "ours" and "theirs"
* side of a merge.
*/
typedef struct git_merge_driver git_merge_driver;
/**
@@ -31,8 +36,11 @@ typedef struct git_merge_driver git_merge_driver;
*/
GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name);
/** The "text" merge driver */
#define GIT_MERGE_DRIVER_TEXT "text"
/** The "binary" merge driver */
#define GIT_MERGE_DRIVER_BINARY "binary"
/** The "union" merge driver */
#define GIT_MERGE_DRIVER_UNION "union"
/**
@@ -40,23 +48,48 @@ GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name);
*/
typedef struct git_merge_driver_source git_merge_driver_source;
/** Get the repository that the source data is coming from. */
/**
* Get the repository that the source data is coming from.
*
* @param src the merge driver source
* @return the repository
*/
GIT_EXTERN(git_repository *) git_merge_driver_source_repo(
const git_merge_driver_source *src);
/** Gets the ancestor of the file to merge. */
/**
* Gets the ancestor of the file to merge.
*
* @param src the merge driver source
* @return the ancestor or NULL if there was no ancestor
*/
GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ancestor(
const git_merge_driver_source *src);
/** Gets the ours side of the file to merge. */
/**
* Gets the ours side of the file to merge.
*
* @param src the merge driver source
* @return the ours side or NULL if there was no ours side
*/
GIT_EXTERN(const git_index_entry *) git_merge_driver_source_ours(
const git_merge_driver_source *src);
/** Gets the theirs side of the file to merge. */
/**
* Gets the theirs side of the file to merge.
*
* @param src the merge driver source
* @return the theirs side or NULL if there was no theirs side
*/
GIT_EXTERN(const git_index_entry *) git_merge_driver_source_theirs(
const git_merge_driver_source *src);
/** Gets the merge file options that the merge was invoked with */
/**
* Gets the merge file options that the merge was invoked with.
*
* @param src the merge driver source
* @return the options
*/
GIT_EXTERN(const git_merge_file_options *) git_merge_driver_source_file_options(
const git_merge_driver_source *src);
@@ -72,6 +105,9 @@ GIT_EXTERN(const git_merge_file_options *) git_merge_driver_source_file_options(
* right before the first use of the driver, so you can defer expensive
* initialization operations (in case libgit2 is being used in a way that
* doesn't need the merge driver).
*
* @param self the merge driver to initialize
* @return 0 on success, or a negative number on failure
*/
typedef int GIT_CALLBACK(git_merge_driver_init_fn)(git_merge_driver *self);
@@ -84,6 +120,8 @@ typedef int GIT_CALLBACK(git_merge_driver_init_fn)(git_merge_driver *self);
* This may be called even if the `initialize` callback was not made.
*
* Typically this function will free the `git_merge_driver` object itself.
*
* @param self the merge driver to shutdown
*/
typedef void GIT_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self);
@@ -104,6 +142,14 @@ typedef void GIT_CALLBACK(git_merge_driver_shutdown_fn)(git_merge_driver *self);
* specified by the file's attributes.
*
* The `src` contains the data about the file to be merged.
*
* @param self the merge driver
* @param path_out the resolved path
* @param mode_out the resolved mode
* @param merged_out the merged output contents
* @param filter_name the filter that was invoked
* @param src the data about the unmerged file
* @return 0 on success, or an error code
*/
typedef int GIT_CALLBACK(git_merge_driver_apply_fn)(
git_merge_driver *self,
@@ -139,6 +185,7 @@ struct git_merge_driver {
git_merge_driver_apply_fn apply;
};
/** The version for the `git_merge_driver` */
#define GIT_MERGE_DRIVER_VERSION 1
/**
@@ -179,4 +226,5 @@ GIT_EXTERN(int) git_merge_driver_unregister(const char *name);
/** @} */
GIT_END_DECL
#endif

7
include/git2/sys/midx.h
View File

@@ -11,9 +11,9 @@
#include "git2/types.h"
/**
* @file git2/midx.h
* @brief Git multi-pack-index routines
* @defgroup git_midx Git multi-pack-index routines
* @file git2/sys/midx.h
* @brief Incremental multi-pack indexes
* @defgroup git_midx Incremental multi-pack indexes
* @ingroup Git
* @{
*/
@@ -75,4 +75,5 @@ GIT_EXTERN(int) git_midx_writer_dump(
/** @} */
GIT_END_DECL
#endif

10
include/git2/sys/odb_backend.h
View File

@@ -13,9 +13,9 @@
#include "git2/odb.h"
/**
* @file git2/sys/backend.h
* @brief Git custom backend implementors functions
* @defgroup git_backend Git custom backend APIs
* @file git2/sys/odb_backend.h
* @brief Object database backends for custom object storage
* @defgroup git_backend Object database backends for custom object storage
* @ingroup Git
* @{
*/
@@ -106,7 +106,10 @@ struct git_odb_backend {
void GIT_CALLBACK(free)(git_odb_backend *);
};
/** Current version for the `git_odb_backend_options` structure */
#define GIT_ODB_BACKEND_VERSION 1
/** Static constructor for `git_odb_backend_options` */
#define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION}
/**
@@ -167,6 +170,7 @@ GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len);
#endif
/** @} */
GIT_END_DECL
#endif

9
include/git2/sys/openssl.h
View File

@@ -9,6 +9,12 @@
#include "git2/common.h"
/**
* @file git2/sys/openssl.h
* @brief Custom OpenSSL functionality
* @defgroup git_openssl Custom OpenSSL functionality
* @{
*/
GIT_BEGIN_DECL
/**
@@ -33,6 +39,7 @@ GIT_BEGIN_DECL
*/
GIT_EXTERN(int) git_openssl_set_locking(void);
/** @} */
GIT_END_DECL
#endif
#endif

13
include/git2/sys/path.h
View File

@@ -10,6 +10,16 @@
#include "git2/common.h"
/**
* @file git2/sys/path.h
* @brief Custom path handling
* @defgroup git_path Custom path handling
* @ingroup Git
*
* Merge will take two commits and attempt to produce a commit that
* includes the changes that were made in both branches.
* @{
*/
GIT_BEGIN_DECL
/**
@@ -59,6 +69,7 @@ typedef enum {
*/
GIT_EXTERN(int) git_path_is_gitfile(const char *path, size_t pathlen, git_path_gitfile gitfile, git_path_fs fs);
/** @} */
GIT_END_DECL
#endif /* INCLUDE_sys_git_path */
#endif

76
include/git2/sys/refdb_backend.h
View File

@@ -12,9 +12,9 @@
#include "git2/oid.h"
/**
* @file git2/refdb_backend.h
* @brief Git custom refs backend functions
* @defgroup git_refdb_backend Git custom refs backend API
* @file git2/sys/refdb_backend.h
* @brief Custom reference database backends for refs storage
* @defgroup git_refdb_backend Custom reference database backends for refs storage
* @ingroup Git
* @{
*/
@@ -65,9 +65,9 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg exists The implementation shall set this to `0` if a ref does
* @param exists The implementation shall set this to `0` if a ref does
* not exist, otherwise to `1`.
* @arg ref_name The reference's name that should be checked for
* @param ref_name The reference's name that should be checked for
* existence.
* @return `0` on success, a negative error value code.
*/
@@ -81,9 +81,9 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg out The implementation shall set this to the allocated
* @param out The implementation shall set this to the allocated
* reference, if it could be found, otherwise to `NULL`.
* @arg ref_name The reference's name that should be checked for
* @param ref_name The reference's name that should be checked for
* existence.
* @return `0` on success, `GIT_ENOTFOUND` if the reference does
* exist, otherwise a negative error code.
@@ -98,12 +98,12 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg out The implementation shall set this to the allocated
* @param out The implementation shall set this to the allocated
* reference iterator. A custom structure may be used with an
* embedded `git_reference_iterator` structure. Both `next`
* and `next_name` functions of `git_reference_iterator` need
* to be populated.
* @arg glob A pattern to filter references by. If given, the iterator
* @param glob A pattern to filter references by. If given, the iterator
* shall only return references that match the glob when
* passed to `wildmatch`.
* @return `0` on success, otherwise a negative error code.
@@ -118,20 +118,20 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg ref The reference to persist. May either be a symbolic or
* @param ref The reference to persist. May either be a symbolic or
* direct reference.
* @arg force Whether to write the reference if a reference with the
* @param force Whether to write the reference if a reference with the
* same name already exists.
* @arg who The person updating the reference. Shall be used to create
* @param who The person updating the reference. Shall be used to create
* a reflog entry.
* @arg message The message detailing what kind of reference update is
* @param message The message detailing what kind of reference update is
* performed. Shall be used to create a reflog entry.
* @arg old If not `NULL` and `force` is not set, then the
* @param old If not `NULL` and `force` is not set, then the
* implementation needs to ensure that the reference is currently at
* the given OID before writing the new value. If both `old`
* and `old_target` are `NULL`, then the reference should not
* exist at the point of writing.
* @arg old_target If not `NULL` and `force` is not set, then the
* @param old_target If not `NULL` and `force` is not set, then the
* implementation needs to ensure that the symbolic
* reference is currently at the given target before
* writing the new value. If both `old` and
@@ -149,15 +149,15 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg out The implementation shall set this to the newly created
* @param out The implementation shall set this to the newly created
* reference or `NULL` on error.
* @arg old_name The current name of the reference that is to be renamed.
* @arg new_name The new name that the old reference shall be renamed to.
* @arg force Whether to write the reference if a reference with the
* @param old_name The current name of the reference that is to be renamed.
* @param new_name The new name that the old reference shall be renamed to.
* @param force Whether to write the reference if a reference with the
* target name already exists.
* @arg who The person updating the reference. Shall be used to create
* @param who The person updating the reference. Shall be used to create
* a reflog entry.
* @arg message The message detailing what kind of reference update is
* @param message The message detailing what kind of reference update is
* performed. Shall be used to create a reflog entry.
* @return `0` on success, otherwise a negative error code.
*/
@@ -173,11 +173,11 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg ref_name The name of the reference name that shall be deleted.
* @arg old_id If not `NULL` and `force` is not set, then the
* @param ref_name The name of the reference name that shall be deleted.
* @param old_id If not `NULL` and `force` is not set, then the
* implementation needs to ensure that the reference is currently at
* the given OID before writing the new value.
* @arg old_target If not `NULL` and `force` is not set, then the
* @param old_target If not `NULL` and `force` is not set, then the
* implementation needs to ensure that the symbolic
* reference is currently at the given target before
* writing the new value.
@@ -243,7 +243,7 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg reflog The complete reference log for a given reference. Note
* @param reflog The complete reference log for a given reference. Note
* that this may contain entries that have already been
* written to disk.
* @return `0` on success, a negative error code otherwise
@@ -255,8 +255,8 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg old_name The name of old reference whose reflog shall be renamed from.
* @arg new_name The name of new reference whose reflog shall be renamed to.
* @param old_name The name of old reference whose reflog shall be renamed from.
* @param new_name The name of new reference whose reflog shall be renamed to.
* @return `0` on success, a negative error code otherwise
*/
int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name);
@@ -266,7 +266,7 @@ struct git_refdb_backend {
*
* A refdb implementation must provide this function.
*
* @arg name The name of the reference whose reflog shall be deleted.
* @param name The name of the reference whose reflog shall be deleted.
* @return `0` on success, a negative error code otherwise
*/
int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name);
@@ -277,9 +277,9 @@ struct git_refdb_backend {
* A refdb implementation may provide this function; if it is not
* provided, the transaction API will fail to work.
*
* @arg payload_out Opaque parameter that will be passed verbosely to
* @param payload_out Opaque parameter that will be passed verbosely to
* `unlock`.
* @arg refname Reference that shall be locked.
* @param refname Reference that shall be locked.
* @return `0` on success, a negative error code otherwise
*/
int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname);
@@ -294,16 +294,16 @@ struct git_refdb_backend {
* A refdb implementation must provide this function if a `lock`
* implementation is provided.
*
* @arg payload The payload returned by `lock`.
* @arg success `1` if a reference should be updated, `2` if
* @param payload The payload returned by `lock`.
* @param success `1` if a reference should be updated, `2` if
* a reference should be deleted, `0` if the lock must be
* discarded.
* @arg update_reflog `1` in case the reflog should be updated, `0`
* @param update_reflog `1` in case the reflog should be updated, `0`
* otherwise.
* @arg ref The reference which should be unlocked.
* @arg who The person updating the reference. Shall be used to create
* @param ref The reference which should be unlocked.
* @param who The person updating the reference. Shall be used to create
* a reflog entry in case `update_reflog` is set.
* @arg message The message detailing what kind of reference update is
* @param message The message detailing what kind of reference update is
* performed. Shall be used to create a reflog entry in
* case `update_reflog` is set.
* @return `0` on success, a negative error code otherwise
@@ -312,7 +312,10 @@ struct git_refdb_backend {
const git_reference *ref, const git_signature *sig, const char *message);
};
/** Current version for the `git_refdb_backend_options` structure */
#define GIT_REFDB_BACKEND_VERSION 1
/** Static constructor for `git_refdb_backend_options` */
#define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION}
/**
@@ -356,6 +359,7 @@ GIT_EXTERN(int) git_refdb_set_backend(
git_refdb *refdb,
git_refdb_backend *backend);
/** @} */
GIT_END_DECL
#endif

21
include/git2/sys/reflog.h
View File

@@ -1,21 +0,0 @@
/*
* Copyright (C) the libgit2 contributors. All rights reserved.
*
* This file is part of libgit2, distributed under the GNU GPL v2 with
* a Linking Exception. For full terms see the included COPYING file.
*/
#ifndef INCLUDE_sys_git_reflog_h__
#define INCLUDE_sys_git_reflog_h__
#include "git2/common.h"
#include "git2/types.h"
#include "git2/oid.h"
GIT_BEGIN_DECL
GIT_EXTERN(git_reflog_entry *) git_reflog_entry__alloc(void);
GIT_EXTERN(void) git_reflog_entry__free(git_reflog_entry *entry);
GIT_END_DECL
#endif

5
include/git2/sys/refs.h
View File

@@ -13,8 +13,8 @@
/**
* @file git2/sys/refs.h
* @brief Low-level Git ref creation
* @defgroup git_backend Git custom backend APIs
* @brief Low-level git reference creation
* @defgroup git_backend Low-level git reference creation
* @ingroup Git
* @{
*/
@@ -46,4 +46,5 @@ GIT_EXTERN(git_reference *) git_reference__alloc_symbolic(
/** @} */
GIT_END_DECL
#endif

3
include/git2/sys/remote.h
View File

@@ -13,7 +13,7 @@
/**
* @file git2/sys/remote.h
* @brief Low-level remote functionality for custom transports
* @defgroup git_remote Low-level remote functionality
* @defgroup git_remote Low-level remote functionality for custom transports
* @ingroup Git
* @{
*/
@@ -49,4 +49,5 @@ GIT_EXTERN(void) git_remote_connect_options_dispose(
/** @} */
GIT_END_DECL
#endif

25
include/git2/sys/repository.h
View File

@@ -13,13 +13,25 @@
/**
* @file git2/sys/repository.h
* @brief Git repository custom implementation routines
* @defgroup git_backend Git custom backend APIs
* @brief Custom repository handling
* @defgroup git_repository Custom repository handling
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
#ifdef GIT_EXPERIMENTAL_SHA256
/**
* Create a new repository with no backends.
*
* @param[out] out The blank repository
* @param oid_type the object ID type for this repository
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_repository_new(git_repository **out, git_oid_t oid_type);
#else
/**
* Create a new repository with neither backends nor config object
*
@@ -30,13 +42,11 @@ GIT_BEGIN_DECL
* can fail to function properly: locations under $GIT_DIR, $GIT_COMMON_DIR,
* or $GIT_INFO_DIR are impacted.
*
* @param out The blank repository
* @param[out] out The blank repository
* @return 0 on success, or an error code
*/
#ifdef GIT_EXPERIMENTAL_SHA256
GIT_EXTERN(int) git_repository_new(git_repository **out, git_oid_t oid_type);
#else
GIT_EXTERN(int) git_repository_new(git_repository **out);
#endif
/**
@@ -161,6 +171,7 @@ GIT_EXTERN(int) git_repository_set_bare(git_repository *repo);
* and caches them so that subsequent calls to `git_submodule_lookup` are O(1).
*
* @param repo the repository whose submodules will be cached.
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_repository_submodule_cache_all(
git_repository *repo);
@@ -176,10 +187,12 @@ GIT_EXTERN(int) git_repository_submodule_cache_all(
* of these has changed, the cache might become invalid.
*
* @param repo the repository whose submodule cache will be cleared
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_repository_submodule_cache_clear(
git_repository *repo);
/** @} */
GIT_END_DECL
#endif

9
include/git2/sys/stream.h
View File

@@ -11,8 +11,16 @@
#include "git2/types.h"
#include "git2/proxy.h"
/**
* @file git2/sys/stream.h
* @brief Streaming file I/O functionality
* @defgroup git_stream Streaming file I/O functionality
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/** Current version for the `git_stream` structures */
#define GIT_STREAM_VERSION 1
/**
@@ -147,6 +155,7 @@ GIT_EXTERN(int) git_stream_register_tls(git_stream_cb ctor);
#endif
/**@}*/
GIT_END_DECL
#endif

27
include/git2/sys/transport.h
View File

@@ -18,14 +18,20 @@
/**
* @file git2/sys/transport.h
* @brief Git custom transport registration interfaces and functions
* @defgroup git_transport Git custom transport registration
* @brief Custom transport registration interfaces and functions
* @defgroup git_transport Custom transport registration
* @ingroup Git
*
* Callers can override the default HTTPS or SSH implementation by
* specifying a custom transport.
* @{
*/
GIT_BEGIN_DECL
/**
* The negotiation state during a fetch smart transport negotiation.
*/
typedef struct {
const git_remote_head * const *refs;
size_t refs_len;
@@ -146,7 +152,10 @@ struct git_transport {
void GIT_CALLBACK(free)(git_transport *transport);
};
/** Current version for the `git_transport` structure */
#define GIT_TRANSPORT_VERSION 1
/** Static constructor for `git_transport` */
#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION}
/**
@@ -299,6 +308,7 @@ GIT_EXTERN(int) git_transport_smart_credentials(git_credential **out, git_transp
*
* @param out options struct to fill
* @param transport the transport to extract the data from.
* @return 0 on success, or an error code
*/
GIT_EXTERN(int) git_transport_remote_connect_options(
git_remote_connect_options *out,
@@ -386,7 +396,14 @@ struct git_smart_subtransport {
void GIT_CALLBACK(free)(git_smart_subtransport *transport);
};
/** A function which creates a new subtransport for the smart transport */
/**
* A function that creates a new subtransport for the smart transport
*
* @param out the smart subtransport
* @param owner the transport owner
* @param param the input parameter
* @return 0 on success, or an error code
*/
typedef int GIT_CALLBACK(git_smart_subtransport_cb)(
git_smart_subtransport **out,
git_transport *owner,
@@ -429,6 +446,7 @@ typedef struct git_smart_subtransport_definition {
*
* @param out The newly created subtransport
* @param owner The smart transport to own this subtransport
* @param param custom parameters for the subtransport
* @return 0 or an error code
*/
GIT_EXTERN(int) git_smart_subtransport_http(
@@ -441,6 +459,7 @@ GIT_EXTERN(int) git_smart_subtransport_http(
*
* @param out The newly created subtransport
* @param owner The smart transport to own this subtransport
* @param param custom parameters for the subtransport
* @return 0 or an error code
*/
GIT_EXTERN(int) git_smart_subtransport_git(
@@ -453,6 +472,7 @@ GIT_EXTERN(int) git_smart_subtransport_git(
*
* @param out The newly created subtransport
* @param owner The smart transport to own this subtransport
* @param param custom parameters for the subtransport
* @return 0 or an error code
*/
GIT_EXTERN(int) git_smart_subtransport_ssh(
@@ -462,4 +482,5 @@ GIT_EXTERN(int) git_smart_subtransport_ssh(
/** @} */
GIT_END_DECL
#endif

4
include/git2/tag.h
View File

@@ -15,7 +15,7 @@
/**
* @file git2/tag.h
* @brief Git tag parsing routines
* @brief A (nearly) immutable pointer to a commit; useful for versioning
* @defgroup git_tag Git tag management
* @ingroup Git
* @{
@@ -335,6 +335,7 @@ typedef int GIT_CALLBACK(git_tag_foreach_cb)(const char *name, git_oid *oid, voi
* @param repo Repository
* @param callback Callback function
* @param payload Pointer to callback data (optional)
* @return 0 on success or an error code
*/
GIT_EXTERN(int) git_tag_foreach(
git_repository *repo,
@@ -380,4 +381,5 @@ GIT_EXTERN(int) git_tag_name_is_valid(int *valid, const char *name);
/** @} */
GIT_END_DECL
#endif

12
include/git2/trace.h
View File

@@ -12,8 +12,8 @@
/**
* @file git2/trace.h
* @brief Git tracing configuration routines
* @defgroup git_trace Git tracing configuration routines
* @brief Tracing functionality to introspect libgit2 in your application
* @defgroup git_trace Tracing functionality to introspect libgit2 in your application
* @ingroup Git
* @{
*/
@@ -48,8 +48,13 @@ typedef enum {
/**
* An instance for a tracing function
*
* @param level the trace level
* @param msg the trace message
*/
typedef void GIT_CALLBACK(git_trace_cb)(git_trace_level_t level, const char *msg);
typedef void GIT_CALLBACK(git_trace_cb)(
git_trace_level_t level,
const char *msg);
/**
* Sets the system tracing configuration to the specified level with the
@@ -64,4 +69,5 @@ GIT_EXTERN(int) git_trace_set(git_trace_level_t level, git_trace_cb cb);
/** @} */
GIT_END_DECL
#endif

5
include/git2/transaction.h
View File

@@ -12,8 +12,8 @@
/**
* @file git2/transaction.h
* @brief Git transactional reference routines
* @defgroup git_transaction Git transactional reference routines
* @brief Transactional reference handling
* @defgroup git_transaction Transactional reference handling
* @ingroup Git
* @{
*/
@@ -118,4 +118,5 @@ GIT_EXTERN(void) git_transaction_free(git_transaction *tx);
/** @} */
GIT_END_DECL
#endif

14
include/git2/transport.h
View File

@@ -15,8 +15,8 @@
/**
* @file git2/transport.h
* @brief Git transport interfaces and functions
* @defgroup git_transport interfaces and functions
* @brief Transports are the low-level mechanism to connect to a remote server
* @defgroup git_transport Transports are the low-level mechanism to connect to a remote server
* @ingroup Git
* @{
*/
@@ -30,10 +30,18 @@ GIT_BEGIN_DECL
* @param str The message from the transport
* @param len The length of the message
* @param payload Payload provided by the caller
* @return 0 on success or an error code
*/
typedef int GIT_CALLBACK(git_transport_message_cb)(const char *str, int len, void *payload);
/** Signature of a function which creates a transport */
/**
* Signature of a function which creates a transport.
*
* @param out the transport generate
* @param owner the owner for the transport
* @param param the param to the transport creation
* @return 0 on success or an error code
*/
typedef int GIT_CALLBACK(git_transport_cb)(git_transport **out, git_remote *owner, void *param);
/** @} */

21
include/git2/tree.h
View File

@@ -14,8 +14,8 @@
/**
* @file git2/tree.h
* @brief Git tree parsing, loading routines
* @defgroup git_tree Git tree parsing, loading routines
* @brief Trees are collections of files and folders to make up the repository hierarchy
* @defgroup git_tree Trees are collections of files and folders to make up the repository hierarchy
* @ingroup Git
* @{
*/
@@ -24,7 +24,7 @@ GIT_BEGIN_DECL
/**
* Lookup a tree object from the repository.
*
* @param out Pointer to the looked up tree
* @param[out] out Pointer to the looked up tree
* @param repo The repo to use when locating the tree.
* @param id Identity of the tree to locate.
* @return 0 or an error code
@@ -345,6 +345,10 @@ GIT_EXTERN(int) git_treebuilder_remove(
* The return value is treated as a boolean, with zero indicating that the
* entry should be left alone and any non-zero value meaning that the
* entry should be removed from the treebuilder list (i.e. filtered out).
*
* @param entry the tree entry for the callback to examine
* @param payload the payload from the caller
* @return 0 to do nothing, non-zero to remove the entry
*/
typedef int GIT_CALLBACK(git_treebuilder_filter_cb)(
const git_tree_entry *entry, void *payload);
@@ -379,7 +383,14 @@ GIT_EXTERN(int) git_treebuilder_filter(
GIT_EXTERN(int) git_treebuilder_write(
git_oid *id, git_treebuilder *bld);
/** Callback for the tree traversal method */
/**
* Callback for the tree traversal method.
*
* @param root the current (relative) root to the entry
* @param entry the tree entry
* @param payload the caller-provided callback payload
* @return a positive value to skip the entry, a negative value to stop the walk
*/
typedef int GIT_CALLBACK(git_treewalk_cb)(
const char *root, const git_tree_entry *entry, void *payload);
@@ -470,6 +481,6 @@ typedef struct {
GIT_EXTERN(int) git_tree_create_updated(git_oid *out, git_repository *repo, git_tree *baseline, size_t nupdates, const git_tree_update *updates);
/** @} */
GIT_END_DECL
#endif

22
include/git2/types.h
View File

@@ -81,13 +81,18 @@ typedef enum {
GIT_OBJECT_REF_DELTA = 7 /**< A delta, base is given by object id. */
} git_object_t;
/** An open object database handle. */
/**
* An object database stores the objects (commit, trees, blobs, tags,
* etc) for a repository.
*/
typedef struct git_odb git_odb;
/** A custom backend in an ODB */
typedef struct git_odb_backend git_odb_backend;
/** An object read from the ODB */
/**
* A "raw" object read from the object database.
*/
typedef struct git_odb_object git_odb_object;
/** A stream to read/write from the ODB */
@@ -194,7 +199,18 @@ typedef struct git_reference_iterator git_reference_iterator;
/** Transactional interface to references */
typedef struct git_transaction git_transaction;
/** Annotated commits, the input to merge and rebase. */
/**
* Annotated commits are commits with additional metadata about how the
* commit was resolved, which can be used for maintaining the user's
* "intent" through commands like merge and rebase.
*
* For example, if a user wants to conceptually "merge `HEAD`", then the
* commit portion of an annotated commit will point to the `HEAD` commit,
* but the _annotation_ will denote the ref `HEAD`. This allows git to
* perform the internal bookkeeping so that the system knows both the
* content of what is being merged but also how the content was looked up
* so that it can be recorded in the reflog appropriately.
*/
typedef struct git_annotated_commit git_annotated_commit;
/** Representation of a status collection */

11
include/git2/version.h
View File

@@ -7,6 +7,14 @@
#ifndef INCLUDE_git_version_h__
#define INCLUDE_git_version_h__
/**
* @file git2/version.h
* @brief The version of libgit2
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* The version string for libgit2. This string follows semantic
* versioning (v2) guidelines.
@@ -61,4 +69,7 @@
#define LIBGIT2_VERSION_CHECK(major, minor, revision) \
(LIBGIT2_VERSION_NUMBER >= ((major)*1000000)+((minor)*10000)+((revision)*100))
/** @} */
GIT_END_DECL
#endif

13
include/git2/worktree.h
View File

@@ -14,9 +14,9 @@
#include "checkout.h"
/**
* @file git2/worktrees.h
* @brief Git worktree related functions
* @defgroup git_commit Git worktree related functions
* @file git2/worktree.h
* @brief Additional working directories for a repository
* @defgroup git_commit Additional working directories for a repository
* @ingroup Git
* @{
*/
@@ -96,7 +96,10 @@ typedef struct git_worktree_add_options {
git_checkout_options checkout_options;
} git_worktree_add_options;
/** Current version for the `git_worktree_add_options` structure */
#define GIT_WORKTREE_ADD_OPTIONS_VERSION 1
/** Static constructor for `git_worktree_add_options` */
#define GIT_WORKTREE_ADD_OPTIONS_INIT { GIT_WORKTREE_ADD_OPTIONS_VERSION, \
0, 0, NULL, GIT_CHECKOUT_OPTIONS_INIT }
@@ -211,7 +214,10 @@ typedef struct git_worktree_prune_options {
uint32_t flags;
} git_worktree_prune_options;
/** Current version for the `git_worktree_prune_options` structure */
#define GIT_WORKTREE_PRUNE_OPTIONS_VERSION 1
/** Static constructor for `git_worktree_prune_options` */
#define GIT_WORKTREE_PRUNE_OPTIONS_INIT {GIT_WORKTREE_PRUNE_OPTIONS_VERSION,0}
/**
@@ -268,4 +274,5 @@ GIT_EXTERN(int) git_worktree_prune(git_worktree *wt,
/** @} */
GIT_END_DECL
#endif

1
script/api-docs/.gitignore vendored Normal file
View File

@@ -0,0 +1 @@
node_modules/

13
script/api-docs/README.md Normal file
View File

@@ -0,0 +1,13 @@
# API Documentation Generator
These scripts generate the "raw API" specs and reference documentation
for [www.libgit2.org](https://libgit2.org/docs/reference).
The "raw API" specs consists of JSON documents, on per
released version or branch, that describes the APIs. This is
suitable for creating documentation from, or may be useful for
language bindings as well.
The reference documentation is documentation fragments for each
API in each version, ready to be included in the libgit2 documentation
website.

1547
script/api-docs/api-generator.js Executable file
View File

File diff suppressed because it is too large Load Diff

1417
script/api-docs/docs-generator.js Executable file
View File

File diff suppressed because it is too large Load Diff

115
script/api-docs/generate Executable file
View File

@@ -0,0 +1,115 @@
#!/usr/bin/env bash
#
# Usage: generate repo_path output_path
#
# Example: generate https://github.com/libgit2/libgit2 path_to_output
# to clone the repository from GitHub and produce documentation;
# the repo_path can also be a local path
set -eo pipefail
source_path=$(mktemp -d)
verbose=
force=
for var in "$@"; do
if [ "${var}" == "--verbose" ]; then
verbose=true
elif [ "${var}" == "--force" ]; then
force=true
elif [ "${repo_path}" == "" ]; then
repo_path="${var}"
elif [ "${output_path}" == "" ]; then
output_path="${var}"
else
repo_path=""
output_path=""
fi
done
if [ "${repo_path}" = "" -o "${output_path}" = "" ]; then
echo "usage: $0 [--verbose] [--force] repo_path output_path" 1>&2
exit 1
fi
function do_checkout {
if [ "$1" = "" ]; then
echo "usage: $0 source_path" 1>&2
exit 1
fi
if [ "${verbose}" ]; then
echo ":: Checking out source trees..."
echo ""
fi
source_path=$1
mkdir -p "${source_path}"
git clone "${repo_path}" "${source_path}/main" --no-checkout
( cd "${source_path}/main" && git sparse-checkout set --no-cone 'include/*' )
( cd "${source_path}/main" && git read-tree origin/main )
( cd "${source_path}/main" && git checkout -- include )
for tag in $(git --git-dir="${source_path}/main/.git" tag -l); do
git --git-dir="${source_path}/main/.git" worktree add -f "${source_path}/${tag}" "${tag}" --no-checkout
( cd "${source_path}/${tag}" && git sparse-checkout set --no-cone 'include/*' )
( cd "${source_path}/${tag}" && git read-tree HEAD )
if [ "${tag}" == "v0.1.0" ]; then
( cd "${source_path}/${tag}" && git checkout -- src/git )
elif [ "${tag}" == "v0.2.0" -o "${tag}" == "v0.3.0" ]; then
( cd "${source_path}/${tag}" && git checkout -- src/git2 )
else
( cd "${source_path}/${tag}" && git checkout -- include )
fi
done
}
do_checkout ${source_path}
if [ "${verbose}" ]; then
echo ""
echo ":: Generating raw API documentation..."
echo ""
fi
for version in ${source_path}/*; do
version=$(echo "${version}" | sed -e "s/.*\///")
commit=$( cd "${source_path}/${version}" && git rev-parse HEAD )
if [ -f "${output_path}/api/${version}.json" ]; then
existing_commit=$(jq -r .info.commit < "${output_path}/api/${version}.json")
if [ "${existing_commit}" == "${commit}" -a ! "${force}" ]; then
if [ "${verbose}" ]; then
echo "Raw API documentation for ${version} exists; skipping..."
fi
continue
fi
fi
echo "Generating raw API documentation for ${version}..."
mkdir -p "${output_path}/api"
node ./api-generator.js "${source_path}/${version}" > "${output_path}/api/${version}.json"
done
if [ "${verbose}" ]; then
echo ""
echo ":: Generating HTML documentation..."
echo ""
fi
search_options=""
docs_options=""
if [ "${verbose}" ]; then
search_options="${search_options} --verbose"
docs_options="${docs_options} --verbose"
fi
if [ "${force}" ]; then
docs_options="${docs_options} --force"
fi
node ./search-generator.js ${search_options} "${output_path}/api" "${output_path}/search-index"
node ./docs-generator.js ${docs_options} --jekyll-layout default "${output_path}/api" "${output_path}/reference"

85
script/api-docs/package-lock.json generated Normal file
View File

@@ -0,0 +1,85 @@
{
"name": "api-docs",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"dependencies": {
"commander": "^12.1.0",
"markdown-it": "^14.1.0",
"minisearch": "^7.1.1"
}
},
"node_modules/argparse": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
"integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="
},
"node_modules/commander": {
"version": "12.1.0",
"resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
"integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
"engines": {
"node": ">=18"
}
},
"node_modules/entities": {
"version": "4.5.0",
"resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
"integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
"engines": {
"node": ">=0.12"
},
"funding": {
"url": "https://github.com/fb55/entities?sponsor=1"
}
},
"node_modules/linkify-it": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz",
"integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==",
"dependencies": {
"uc.micro": "^2.0.0"
}
},
"node_modules/markdown-it": {
"version": "14.1.0",
"resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz",
"integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==",
"dependencies": {
"argparse": "^2.0.1",
"entities": "^4.4.0",
"linkify-it": "^5.0.0",
"mdurl": "^2.0.0",
"punycode.js": "^2.3.1",
"uc.micro": "^2.1.0"
},
"bin": {
"markdown-it": "bin/markdown-it.mjs"
}
},
"node_modules/mdurl": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz",
"integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w=="
},
"node_modules/minisearch": {
"version": "7.1.1",
"resolved": "https://registry.npmjs.org/minisearch/-/minisearch-7.1.1.tgz",
"integrity": "sha512-b3YZEYCEH4EdCAtYP7OlDyx7FdPwNzuNwLQ34SfJpM9dlbBZzeXndGavTrC+VCiRWomL21SWfMc6SCKO/U2ZNw=="
},
"node_modules/punycode.js": {
"version": "2.3.1",
"resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
"integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
"engines": {
"node": ">=6"
}
},
"node_modules/uc.micro": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
"integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A=="
}
}
}

7
script/api-docs/package.json Normal file
View File

@@ -0,0 +1,7 @@
{
"dependencies": {
"commander": "^12.1.0",
"markdown-it": "^14.1.0",
"minisearch": "^7.1.1"
}
}

212
script/api-docs/search-generator.js Executable file
View File

@@ -0,0 +1,212 @@
#!/usr/bin/env node
const markdownit = require('markdown-it');
const { program } = require('commander');
const minisearch = require('minisearch');
const path = require('node:path');
const fs = require('node:fs/promises');
const linkPrefix = '/docs/reference';
const defaultBranch = 'main';
function uniqueifyId(api, nodes) {
let suffix = "", i = 1;
while (true) {
const possibleId = `${api.kind}-${api.name}${suffix}`;
let collision = false;
for (const item of nodes) {
if (item.id === possibleId) {
collision = true;
break;
}
}
if (!collision) {
return possibleId;
}
suffix = `-${++i}`;
}
}
async function produceSearchIndex(version, apiData) {
const nodes = [ ];
for (const group in apiData['groups']) {
for (const name in apiData['groups'][group]['apis']) {
const api = apiData['groups'][group]['apis'][name];
let displayName = name;
if (api.kind === 'macro') {
displayName = displayName.replace(/\(.*/, '');
}
const apiSearchData = {
id: uniqueifyId(api, nodes),
name: displayName,
group: group,
kind: api.kind
};
apiSearchData.description = Array.isArray(api.comment) ?
api.comment[0] : api.comment;
let detail = "";
if (api.kind === 'macro') {
detail = api.value;
}
else if (api.kind === 'alias') {
detail = api.type;
}
else {
let details = undefined;
if (api.kind === 'struct' || api.kind === 'enum') {
details = api.members;
}
else if (api.kind === 'function' || api.kind === 'callback') {
details = api.params;
}
else {
throw new Error(`unknown api type '${api.kind}'`);
}
for (const item of details || [ ]) {
if (detail.length > 0) {
detail += ' ';
}
detail += item.name;
if (item.comment) {
detail += ' ';
detail += item.comment;
}
}
if (api.kind === 'function' || api.kind === 'callback') {
if (detail.length > 0 && api.returns?.type) {
detail += ' ' + api.returns.type;
}
if (detail.length > 0 && api.returns?.comment) {
detail += ' ' + api.returns.comment;
}
}
}
detail = detail.replaceAll(/\s+/g, ' ')
.replaceAll(/[\"\'\`]/g, '');
apiSearchData.detail = detail;
nodes.push(apiSearchData);
}
}
const index = new minisearch({
fields: [ 'name', 'description', 'detail' ],
storeFields: [ 'name', 'group', 'kind', 'description' ],
searchOptions: { boost: { name: 5, description: 2 } }
});
index.addAll(nodes);
const filename = `${outputPath}/${version}.json`;
await fs.mkdir(outputPath, { recursive: true });
await fs.writeFile(filename, JSON.stringify(index, null, 2));
}
function versionSort(a, b) {
if (a === b) {
return 0;
}
const aVersion = a.match(/^v(\d+)(?:\.(\d+)(?:\.(\d+)(?:\.(\d+))?)?)?(?:-(.*))?$/);
const bVersion = b.match(/^v(\d+)(?:\.(\d+)(?:\.(\d+)(?:\.(\d+))?)?)?(?:-(.*))?$/);
if (!aVersion && !bVersion) {
return a.localeCompare(b);
}
else if (aVersion && !bVersion) {
return -1;
}
else if (!aVersion && bVersion) {
return 1;
}
for (let i = 1; i < 5; i++) {
if (!aVersion[i] && !bVersion[i]) {
break;
}
else if (aVersion[i] && !bVersion[i]) {
return 1;
}
else if (!aVersion[i] && bVersion[i]) {
return -1;
}
else if (aVersion[i] !== bVersion[i]) {
return aVersion[i] - bVersion[i];
}
}
if (aVersion[5] && !bVersion[5]) {
return -1;
}
else if (!aVersion[5] && bVersion[5]) {
return 1;
}
else if (aVersion[5] && bVersion[5]) {
return aVersion[5].localeCompare(bVersion[5]);
}
return 0;
}
program.option('--verbose')
.option('--version <version...>');
program.parse();
const options = program.opts();
if (program.args.length != 2) {
console.error(`usage: ${path.basename(process.argv[1])} raw_api_dir output_dir`);
process.exit(1);
}
const docsPath = program.args[0];
const outputPath = program.args[1];
(async () => {
try {
const v = options.version ? options.version :
(await fs.readdir(docsPath))
.filter(a => a.endsWith('.json'))
.map(a => a.replace(/\.json$/, ''));
const versions = v.sort(versionSort).reverse();
for (const version of versions) {
if (options.verbose) {
console.log(`Reading documentation data for ${version}...`);
}
const apiData = JSON.parse(await fs.readFile(`${docsPath}/${version}.json`));
if (options.verbose) {
console.log(`Creating minisearch index for ${version}...`);
}
await produceSearchIndex(version, apiData);
}
} catch (e) {
console.error(e);
process.exit(1);
}
})();

9
src/libgit2/config_cache.c
View File

@@ -64,11 +64,10 @@ static git_configmap _configmap_logallrefupdates[] = {
{GIT_CONFIGMAP_STRING, "always", GIT_LOGALLREFUPDATES_ALWAYS},
};
/*
* Generic map for integer values
*/
static git_configmap _configmap_int[] = {
static git_configmap _configmap_abbrev[] = {
{GIT_CONFIGMAP_INT32, NULL, 0},
{GIT_CONFIGMAP_FALSE, NULL, GIT_ABBREV_FALSE},
{GIT_CONFIGMAP_STRING, "auto", GIT_ABBREV_DEFAULT}
};
static struct map_data _configmaps[] = {
@@ -79,7 +78,7 @@ static struct map_data _configmaps[] = {
{"core.filemode", NULL, 0, GIT_FILEMODE_DEFAULT },
{"core.ignorestat", NULL, 0, GIT_IGNORESTAT_DEFAULT },
{"core.trustctime", NULL, 0, GIT_TRUSTCTIME_DEFAULT },
{"core.abbrev", _configmap_int, 1, GIT_ABBREV_DEFAULT },
{"core.abbrev", _configmap_abbrev, ARRAY_SIZE(_configmap_abbrev), GIT_ABBREV_DEFAULT },
{"core.precomposeunicode", NULL, 0, GIT_PRECOMPOSE_DEFAULT },
{"core.safecrlf", _configmap_safecrlf, ARRAY_SIZE(_configmap_safecrlf), GIT_SAFE_CRLF_DEFAULT},
{"core.logallrefupdates", _configmap_logallrefupdates, ARRAY_SIZE(_configmap_logallrefupdates), GIT_LOGALLREFUPDATES_DEFAULT},

Some files were not shown because too many files have changed in this diff Show More