Unverified Commit 2f1d6eff by Edward Thomson Committed by GitHub

Merge pull request #4954 from tiennou/fix/documentation

Documentation fixes
parents cf14215d 690e55e0
......@@ -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.
......
......@@ -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;
......
......@@ -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);
......
......@@ -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