Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add all git documentation for convenience
taken from 'git/technical/*'
- Loading branch information
Showing
31 changed files
with
9,044 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,75 @@ | ||
Error reporting in git | ||
====================== | ||
|
||
`die`, `usage`, `error`, and `warning` report errors of various | ||
kinds. | ||
|
||
- `die` is for fatal application errors. It prints a message to | ||
the user and exits with status 128. | ||
|
||
- `usage` is for errors in command line usage. After printing its | ||
message, it exits with status 129. (See also `usage_with_options` | ||
in the link:api-parse-options.html[parse-options API].) | ||
|
||
- `error` is for non-fatal library errors. It prints a message | ||
to the user and returns -1 for convenience in signaling the error | ||
to the caller. | ||
|
||
- `warning` is for reporting situations that probably should not | ||
occur but which the user (and Git) can continue to work around | ||
without running into too many problems. Like `error`, it | ||
returns -1 after reporting the situation to the caller. | ||
|
||
Customizable error handlers | ||
--------------------------- | ||
|
||
The default behavior of `die` and `error` is to write a message to | ||
stderr and then exit or return as appropriate. This behavior can be | ||
overridden using `set_die_routine` and `set_error_routine`. For | ||
example, "git daemon" uses set_die_routine to write the reason `die` | ||
was called to syslog before exiting. | ||
|
||
Library errors | ||
-------------- | ||
|
||
Functions return a negative integer on error. Details beyond that | ||
vary from function to function: | ||
|
||
- Some functions return -1 for all errors. Others return a more | ||
specific value depending on how the caller might want to react | ||
to the error. | ||
|
||
- Some functions report the error to stderr with `error`, | ||
while others leave that for the caller to do. | ||
|
||
- errno is not meaningful on return from most functions (except | ||
for thin wrappers for system calls). | ||
|
||
Check the function's API documentation to be sure. | ||
|
||
Caller-handled errors | ||
--------------------- | ||
|
||
An increasing number of functions take a parameter 'struct strbuf *err'. | ||
On error, such functions append a message about what went wrong to the | ||
'err' strbuf. The message is meant to be complete enough to be passed | ||
to `die` or `error` as-is. For example: | ||
|
||
if (ref_transaction_commit(transaction, &err)) | ||
die("%s", err.buf); | ||
|
||
The 'err' parameter will be untouched if no error occurred, so multiple | ||
function calls can be chained: | ||
|
||
t = ref_transaction_begin(&err); | ||
if (!t || | ||
ref_transaction_update(t, "HEAD", ..., &err) || | ||
ret_transaction_commit(t, &err)) | ||
die("%s", err.buf); | ||
|
||
The 'err' parameter must be a pointer to a valid strbuf. To silence | ||
a message, pass a strbuf that is explicitly ignored: | ||
|
||
if (thing_that_can_fail_in_an_ignorable_way(..., &err)) | ||
/* This failure is okay. */ | ||
strbuf_reset(&err); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
Git API Documents | ||
================= | ||
|
||
Git has grown a set of internal API over time. This collection | ||
documents them. | ||
|
||
//////////////////////////////////////////////////////////////// | ||
// table of contents begin | ||
//////////////////////////////////////////////////////////////// | ||
|
||
//////////////////////////////////////////////////////////////// | ||
// table of contents end | ||
//////////////////////////////////////////////////////////////// |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
#!/bin/sh | ||
|
||
( | ||
c=//////////////////////////////////////////////////////////////// | ||
skel=api-index-skel.txt | ||
sed -e '/^\/\/ table of contents begin/q' "$skel" | ||
echo "$c" | ||
|
||
ls api-*.txt | | ||
while read filename | ||
do | ||
case "$filename" in | ||
api-index-skel.txt | api-index.txt) continue ;; | ||
esac | ||
title=$(sed -e 1q "$filename") | ||
html=${filename%.txt}.html | ||
echo "* link:$html[$title]" | ||
done | ||
echo "$c" | ||
sed -n -e '/^\/\/ table of contents end/,$p' "$skel" | ||
) >api-index.txt+ | ||
|
||
if test -f api-index.txt && cmp api-index.txt api-index.txt+ >/dev/null | ||
then | ||
rm -f api-index.txt+ | ||
else | ||
mv api-index.txt+ api-index.txt | ||
fi |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
merge API | ||
========= | ||
|
||
The merge API helps a program to reconcile two competing sets of | ||
improvements to some files (e.g., unregistered changes from the work | ||
tree versus changes involved in switching to a new branch), reporting | ||
conflicts if found. The library called through this API is | ||
responsible for a few things. | ||
|
||
* determining which trees to merge (recursive ancestor consolidation); | ||
|
||
* lining up corresponding files in the trees to be merged (rename | ||
detection, subtree shifting), reporting edge cases like add/add | ||
and rename/rename conflicts to the user; | ||
|
||
* performing a three-way merge of corresponding files, taking | ||
path-specific merge drivers (specified in `.gitattributes`) | ||
into account. | ||
|
||
Data structures | ||
--------------- | ||
|
||
* `mmbuffer_t`, `mmfile_t` | ||
|
||
These store data usable for use by the xdiff backend, for writing and | ||
for reading, respectively. See `xdiff/xdiff.h` for the definitions | ||
and `diff.c` for examples. | ||
|
||
* `struct ll_merge_options` | ||
|
||
Check ll-merge.h for details. | ||
|
||
Low-level (single file) merge | ||
----------------------------- | ||
|
||
Check ll-merge.h for details. |
Oops, something went wrong.