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 141 additions and 88 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
--------------------
......
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