Skip to content

G
git2
Unverified Commit 2f1d6eff by Edward Thomson Committed by GitHub
Options

Merge pull request #4954 from tiennou/fix/documentation 

Documentation fixes
parents cf14215d 690e55e0
Showing with 142 additions and 89 deletions
docs/error-handling.md
......@@ -110,6 +110,15 @@ int git_repository_open(git_repository **repository, const char *path)
}
~~~
Note that some error codes have been defined with a specific meaning in the
context of callbacks:
- `GIT_EUSER` provides a way to bubble up a non libgit2-related failure, which
allows it to be preserved all the way up to the initial function call (a `git_cred`
setup trying to access an unavailable LDAP server for instance).
- `GIT_EPASSTHROUGH` provides a way to tell libgit2 that it should behave as if
no callback was provided. This is of special interest to bindings, which would
always provide a C function as a "trampoline", and decide at runtime what to do.
The public error API
--------------------
......@@ -119,7 +128,7 @@ The public error API
of error and the error message that was generated by the library.
Do not use this function unless the prior call to a libgit2 API
returned an error, as it can otherwise give misleading results.
libgit2's error strings are not cleared aggressively,
libgit2's error strings are not cleared aggressively,
and this function may return an error string that reflects a prior error,
possibly even reflecting internal state.
......
include/git2/repository.h
......@@ -94,40 +94,53 @@ GIT_EXTERN(int) git_repository_discover(
/**
* Option flags for `git_repository_open_ext`.
*
* * GIT_REPOSITORY_OPEN_NO_SEARCH - Only open the repository if it can be
* immediately found in the start_path. Do not walk up from the
* start_path looking at parent directories.
* * GIT_REPOSITORY_OPEN_CROSS_FS - Unless this flag is set, open will not
* continue searching across filesystem boundaries (i.e. when `st_dev`
* changes from the `stat` system call). (E.g. Searching in a user's home
* directory "/home/user/source/" will not return "/.git/" as the found
* repo if "/" is a different filesystem than "/home".)
* * GIT_REPOSITORY_OPEN_BARE - Open repository as a bare repo regardless
* of core.bare config, and defer loading config file for faster setup.
* Unlike `git_repository_open_bare`, this can follow gitlinks.
* * GIT_REPOSITORY_OPEN_NO_DOTGIT - Do not check for a repository by
* appending /.git to the start_path; only open the repository if
* start_path itself points to the git directory.
* * GIT_REPOSITORY_OPEN_FROM_ENV - Find and open a git repository,
* respecting the environment variables used by the git command-line
* tools. If set, `git_repository_open_ext` will ignore the other
* flags and the `ceiling_dirs` argument, and will allow a NULL `path`
* to use `GIT_DIR` or search from the current directory. The search
* for a repository will respect $GIT_CEILING_DIRECTORIES and
* $GIT_DISCOVERY_ACROSS_FILESYSTEM. The opened repository will
* respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and
* $GIT_ALTERNATE_OBJECT_DIRECTORIES. In the future, this flag will
* also cause `git_repository_open_ext` to respect $GIT_WORK_TREE and
* $GIT_COMMON_DIR; currently, `git_repository_open_ext` with this
* flag will error out if either $GIT_WORK_TREE or $GIT_COMMON_DIR is
* set.
*/
typedef enum {
/**
* Only open the repository if it can be immediately found in the
* start_path. Do not walk up from the start_path looking at parent
* directories.
*/
GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0),
/**
* Unless this flag is set, open will not continue searching across
* filesystem boundaries (i.e. when `st_dev` changes from the `stat`
* system call). For example, searching in a user's home directory at
* "/home/user/source/" will not return "/.git/" as the found repo if
* "/" is a different filesystem than "/home".
*/
GIT_REPOSITORY_OPEN_CROSS_FS = (1 << 1),
/**
* Open repository as a bare repo regardless of core.bare config, and
* defer loading config file for faster setup.
* Unlike `git_repository_open_bare`, this can follow gitlinks.
*/
GIT_REPOSITORY_OPEN_BARE = (1 << 2),
/**
* Do not check for a repository by appending /.git to the start_path;
* only open the repository if start_path itself points to the git
* directory.
*/
GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3),
/**
* Find and open a git repository, respecting the environment variables
* used by the git command-line tools.
* If set, `git_repository_open_ext` will ignore the other flags and
* the `ceiling_dirs` argument, and will allow a NULL `path` to use
* `GIT_DIR` or search from the current directory.
* The search for a repository will respect $GIT_CEILING_DIRECTORIES and
* $GIT_DISCOVERY_ACROSS_FILESYSTEM. The opened repository will
* respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and
* $GIT_ALTERNATE_OBJECT_DIRECTORIES.
* In the future, this flag will also cause `git_repository_open_ext`
* to respect $GIT_WORK_TREE and $GIT_COMMON_DIR; currently,
* `git_repository_open_ext` with this flag will error out if either
* $GIT_WORK_TREE or $GIT_COMMON_DIR is set.
*/
GIT_REPOSITORY_OPEN_FROM_ENV = (1 << 4),
} git_repository_open_flag_t;
......
include/git2/signature.h
......@@ -30,8 +30,8 @@ GIT_BEGIN_DECL
* @param out new signature, in case of error NULL
* @param name name of the person
* @param email email of the person
* @param time time when the action happened
* @param offset timezone offset in minutes for the time
* @param time time (in seconds from epoch) when the action happened
* @param offset timezone offset (in minutes) for the time
* @return 0 or an error code
*/
GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset);
......
include/git2/sys/transport.h
......@@ -33,8 +33,9 @@ typedef enum {
} git_transport_flags_t;
struct git_transport {
unsigned int version;
/* Set progress and error callbacks */
unsigned int version; /**< The struct version */
/** Set progress and error callbacks */
int GIT_CALLBACK(set_callbacks)(
git_transport *transport,
git_transport_message_cb progress_cb,
......@@ -42,13 +43,15 @@ struct git_transport {
git_transport_certificate_check_cb certificate_check_cb,
void *payload);
/* Set custom headers for HTTP requests */
/** Set custom headers for HTTP requests */
int GIT_CALLBACK(set_custom_headers)(
git_transport *transport,
const git_strarray *custom_headers);
/* Connect the transport to the remote repository, using the given
* direction. */
/**
* Connect the transport to the remote repository, using the given
* direction.
*/
int GIT_CALLBACK(connect)(
git_transport *transport,
const char *url,
......@@ -58,29 +61,40 @@ struct git_transport {
int direction,
int flags);
/* This function may be called after a successful call to
* connect(). The array returned is owned by the transport and
* is guaranteed until the next call of a transport function. */
/**
* Get the list of available references in the remote repository.
*
* This function may be called after a successful call to
* `connect()`. The array returned is owned by the transport and
* must be kept valid until the next call to one of its functions.
*/
int GIT_CALLBACK(ls)(
const git_remote_head ***out,
size_t *size,
git_transport *transport);
/* Executes the push whose context is in the git_push object. */
/** Executes the push whose context is in the git_push object. */
int GIT_CALLBACK(push)(git_transport *transport, git_push *push, const git_remote_callbacks *callbacks);
/* This function may be called after a successful call to connect(), when
* the direction is FETCH. The function performs a negotiation to calculate
* the wants list for the fetch. */
/**
* Negotiate a fetch with the remote repository.
*
* This function may be called after a successful call to `connect()`,
* when the direction is GIT_DIRECTION_FETCH. The function performs a
* negotiation to calculate the `wants` list for the fetch.
*/
int GIT_CALLBACK(negotiate_fetch)(
git_transport *transport,
git_repository *repo,
const git_remote_head * const *refs,
size_t count);
/* This function may be called after a successful call to negotiate_fetch(),
* when the direction is FETCH. This function retrieves the pack file for
* the fetch from the remote end. */
/**
* Start downloading the packfile from the remote repository.
*
* This function may be called after a successful call to
* negotiate_fetch(), when the direction is GIT_DIRECTION_FETCH.
*/
int GIT_CALLBACK(download_pack)(
git_transport *transport,
git_repository *repo,
......@@ -88,20 +102,24 @@ struct git_transport {
git_transfer_progress_cb progress_cb,
void *progress_payload);
/* Checks to see if the transport is connected */
/** Checks to see if the transport is connected */
int GIT_CALLBACK(is_connected)(git_transport *transport);
/* Reads the flags value previously passed into connect() */
/** Reads the flags value previously passed into connect() */
int GIT_CALLBACK(read_flags)(git_transport *transport, int *flags);
/* Cancels any outstanding transport operation */
/** Cancels any outstanding transport operation */
void GIT_CALLBACK(cancel)(git_transport *transport);
/* This function is the reverse of connect() -- it terminates the
* connection to the remote end. */
/**
* Close the connection to the remote repository.
*
* This function is the reverse of connect() -- it terminates the
* connection to the remote end.
*/
int GIT_CALLBACK(close)(git_transport *transport);
/* Frees/destructs the git_transport object. */
/** Frees/destructs the git_transport object. */
void GIT_CALLBACK(free)(git_transport *transport);
};
......@@ -167,10 +185,13 @@ GIT_EXTERN(int) git_transport_register(
void *param);
/**
*
* Unregister a custom transport definition which was previously registered
* with git_transport_register.
*
* The caller is responsible for synchronizing calls to git_transport_register
* and git_transport_unregister with other calls to the library that
* instantiate transports.
*
* @param prefix From the previous call to git_transport_register
* @return 0 or an error code
*/
......@@ -262,20 +283,7 @@ GIT_EXTERN(int) git_transport_smart_proxy_options(git_proxy_options *out, git_tr
*** Begin interface for subtransports for the smart transport ***
*/
/* The smart transport knows how to speak the git protocol, but it has no
* knowledge of how to establish a connection between it and another endpoint,
* or how to move data back and forth. For this, a subtransport interface is
* declared, and the smart transport delegates this work to the subtransports.
* Three subtransports are implemented: git, http, and winhttp. (The http and
* winhttp transports each implement both http and https.) */
/* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
* (request/response). The smart transport handles the differences in its own
* logic. The git subtransport is RPC = 0, while http and winhttp are both
* RPC = 1. */
/* Actions that the smart transport can ask
* a subtransport to perform */
/** Actions that the smart transport can ask a subtransport to perform */
typedef enum {
GIT_SERVICE_UPLOADPACK_LS = 1,
GIT_SERVICE_UPLOADPACK = 2,
......@@ -286,58 +294,81 @@ typedef enum {
typedef struct git_smart_subtransport git_smart_subtransport;
typedef struct git_smart_subtransport_stream git_smart_subtransport_stream;
/* A stream used by the smart transport to read and write data
/**
* A stream used by the smart transport to read and write data
* from a subtransport */
struct git_smart_subtransport_stream {
/* The owning subtransport */
/** The owning subtransport */
git_smart_subtransport *subtransport;
/** Read available data from the stream */
int GIT_CALLBACK(read)(
git_smart_subtransport_stream *stream,
char *buffer,
size_t buf_size,
size_t *bytes_read);
/** Write data to the stream */
int GIT_CALLBACK(write)(
git_smart_subtransport_stream *stream,
const char *buffer,
size_t len);
/** Free the stream */
void GIT_CALLBACK(free)(
git_smart_subtransport_stream *stream);
};
/* An implementation of a subtransport which carries data for the
/**
* An implementation of a subtransport which carries data for the
* smart transport */
struct git_smart_subtransport {
/**
* Setup a subtransport stream for the requested action.
*/
int GIT_CALLBACK(action)(
git_smart_subtransport_stream **out,
git_smart_subtransport *transport,
const char *url,
git_smart_service_t action);
/* Subtransports are guaranteed a call to close() between
/**
* Close the subtransport.
*
* Subtransports are guaranteed a call to close() between
* calls to action(), except for the following two "natural" progressions
* of actions against a constant URL.
* of actions against a constant URL:
*
* 1. UPLOADPACK_LS -> UPLOADPACK
* 2. RECEIVEPACK_LS -> RECEIVEPACK */
* - UPLOADPACK_LS -> UPLOADPACK
* - RECEIVEPACK_LS -> RECEIVEPACK
*/
int GIT_CALLBACK(close)(git_smart_subtransport *transport);
/** Free the subtransport */
void GIT_CALLBACK(free)(git_smart_subtransport *transport);
};
/* A function which creates a new subtransport for the smart transport */
/** A function which creates a new subtransport for the smart transport */
typedef int GIT_CALLBACK(git_smart_subtransport_cb)(
git_smart_subtransport **out,
git_transport* owner,
void* param);
git_transport *owner,
void *param);
/**
* Definition for a "subtransport"
*
* This is used to let the smart protocol code know about the protocol
* which you are implementing.
* The smart transport knows how to speak the git protocol, but it has no
* knowledge of how to establish a connection between it and another endpoint,
* or how to move data back and forth. For this, a subtransport interface is
* declared, and the smart transport delegates this work to the subtransports.
*
* Three subtransports are provided by libgit2: git, http, and winhttp.
* The http and winhttp transports each implement both http and https.
*
* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
* (request/response). The smart transport handles the differences in its own
* logic. The git subtransport is RPC = 0, while http and winhttp are both
* RPC = 1.
*/
typedef struct git_smart_subtransport_definition {
/** The function to use to create the git_smart_subtransport */
......@@ -349,17 +380,17 @@ typedef struct git_smart_subtransport_definition {
*/
unsigned rpc;
/** Param of the callback
*/
void* param;
/** User-specified parameter passed to the callback */
void *param;
} git_smart_subtransport_definition;
/* Smart transport subtransports that come with libgit2 */
/**
* Create an instance of the http subtransport. This subtransport
* also supports https. On Win32, this subtransport may be implemented
* using the WinHTTP library.
* Create an instance of the http subtransport.
*
* This subtransport also supports https. On Win32, this subtransport may be
* implemented using the WinHTTP library.
*
* @param out The newly created subtransport
* @param owner The smart transport to own this subtransport
......@@ -367,7 +398,7 @@ typedef struct git_smart_subtransport_definition {
*/
GIT_EXTERN(int) git_smart_subtransport_http(
git_smart_subtransport **out,
git_transport* owner,
git_transport *owner,
void *param);
/**
......@@ -379,7 +410,7 @@ GIT_EXTERN(int) git_smart_subtransport_http(
*/
GIT_EXTERN(int) git_smart_subtransport_git(
git_smart_subtransport **out,
git_transport* owner,
git_transport *owner,
void *param);
/**
......@@ -391,7 +422,7 @@ GIT_EXTERN(int) git_smart_subtransport_git(
*/
GIT_EXTERN(int) git_smart_subtransport_ssh(
git_smart_subtransport **out,
git_transport* owner,
git_transport *owner,
void *param);
/** @} */
......
include/git2/types.h
......@@ -59,7 +59,7 @@ typedef __haiku_std_int64 git_time_t;
* app, even though /we/ define _FILE_OFFSET_BITS=64.
*/
typedef int64_t git_off_t;
typedef int64_t git_time_t;
typedef int64_t git_time_t; /**< time in seconds from epoch */
#endif
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment