diff options
Diffstat (limited to 'Documentation/technical')
| -rw-r--r-- | Documentation/technical/api-argv-array.txt | 5 | ||||
| -rw-r--r-- | Documentation/technical/api-config.txt | 140 | ||||
| -rw-r--r-- | Documentation/technical/api-credentials.txt | 68 | ||||
| -rw-r--r-- | Documentation/technical/api-parse-options.txt | 37 | ||||
| -rw-r--r-- | Documentation/technical/api-revision-walking.txt | 5 | ||||
| -rw-r--r-- | Documentation/technical/api-strbuf.txt | 18 | ||||
| -rw-r--r-- | Documentation/technical/api-string-list.txt | 4 | ||||
| -rw-r--r-- | Documentation/technical/index-format.txt | 13 | ||||
| -rw-r--r-- | Documentation/technical/pack-protocol.txt | 4 | ||||
| -rw-r--r-- | Documentation/technical/protocol-common.txt | 2 |
10 files changed, 267 insertions, 29 deletions
diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 49b3d52952..1b7d8f140c 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -37,6 +37,11 @@ Functions `argv_array_push`:: Push a copy of a string onto the end of the array. +`argv_array_pushl`:: + Push a list of strings onto the end of the array. The arguments + should be a list of `const char *` strings, terminated by a NULL + argument. + `argv_array_pushf`:: Format a string and push it onto the end of the array. This is a convenience wrapper combining `strbuf_addf` and `argv_array_push`. diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt new file mode 100644 index 0000000000..edf8dfb99b --- /dev/null +++ b/Documentation/technical/api-config.txt @@ -0,0 +1,140 @@ +config API +========== + +The config API gives callers a way to access git configuration files +(and files which have the same syntax). See linkgit:git-config[1] for a +discussion of the config file syntax. + +General Usage +------------- + +Config files are parsed linearly, and each variable found is passed to a +caller-provided callback function. The callback function is responsible +for any actions to be taken on the config option, and is free to ignore +some options. It is not uncommon for the configuration to be parsed +several times during the run of a git program, with different callbacks +picking out different variables useful to themselves. + +A config callback function takes three parameters: + +- the name of the parsed variable. This is in canonical "flat" form: the + section, subsection, and variable segments will be separated by dots, + and the section and variable segments will be all lowercase. E.g., + `core.ignorecase`, `diff.SomeType.textconv`. + +- the value of the found variable, as a string. If the variable had no + value specified, the value will be NULL (typically this means it + should be interpreted as boolean true). + +- a void pointer passed in by the caller of the config API; this can + contain callback-specific data + +A config callback should return 0 for success, or -1 if the variable +could not be parsed properly. + +Basic Config Querying +--------------------- + +Most programs will simply want to look up variables in all config files +that git knows about, using the normal precedence rules. To do this, +call `git_config` with a callback function and void data pointer. + +`git_config` will read all config sources in order of increasing +priority. Thus a callback should typically overwrite previously-seen +entries with new ones (e.g., if both the user-wide `~/.gitconfig` and +repo-specific `.git/config` contain `color.ui`, the config machinery +will first feed the user-wide one to the callback, and then the +repo-specific one; by overwriting, the higher-priority repo-specific +value is left at the end). + +The `git_config_with_options` function lets the caller examine config +while adjusting some of the default behavior of `git_config`. It should +almost never be used by "regular" git code that is looking up +configuration variables. It is intended for advanced callers like +`git-config`, which are intentionally tweaking the normal config-lookup +process. It takes two extra parameters: + +`filename`:: +If this parameter is non-NULL, it specifies the name of a file to +parse for configuration, rather than looking in the usual files. Regular +`git_config` defaults to `NULL`. + +`respect_includes`:: +Specify whether include directives should be followed in parsed files. +Regular `git_config` defaults to `1`. + +There is a special version of `git_config` called `git_config_early`. +This version takes an additional parameter to specify the repository +config, instead of having it looked up via `git_path`. This is useful +early in a git program before the repository has been found. Unless +you're working with early setup code, you probably don't want to use +this. + +Reading Specific Files +---------------------- + +To read a specific file in git-config format, use +`git_config_from_file`. This takes the same callback and data parameters +as `git_config`. + +Value Parsing Helpers +--------------------- + +To aid in parsing string values, the config API provides callbacks with +a number of helper functions, including: + +`git_config_int`:: +Parse the string to an integer, including unit factors. Dies on error; +otherwise, returns the parsed result. + +`git_config_ulong`:: +Identical to `git_config_int`, but for unsigned longs. + +`git_config_bool`:: +Parse a string into a boolean value, respecting keywords like "true" and +"false". Integer values are converted into true/false values (when they +are non-zero or zero, respectively). Other values cause a die(). If +parsing is successful, the return value is the result. + +`git_config_bool_or_int`:: +Same as `git_config_bool`, except that integers are returned as-is, and +an `is_bool` flag is unset. + +`git_config_maybe_bool`:: +Same as `git_config_bool`, except that it returns -1 on error rather +than dying. + +`git_config_string`:: +Allocates and copies the value string into the `dest` parameter; if no +string is given, prints an error message and returns -1. + +`git_config_pathname`:: +Similar to `git_config_string`, but expands `~` or `~user` into the +user's home directory when found at the beginning of the path. + +Include Directives +------------------ + +By default, the config parser does not respect include directives. +However, a caller can use the special `git_config_include` wrapper +callback to support them. To do so, you simply wrap your "real" callback +function and data pointer in a `struct config_include_data`, and pass +the wrapper to the regular config-reading functions. For example: + +------------------------------------------- +int read_file_with_include(const char *file, config_fn_t fn, void *data) +{ + struct config_include_data inc = CONFIG_INCLUDE_INIT; + inc.fn = fn; + inc.data = data; + return git_config_from_file(git_config_include, file, &inc); +} +------------------------------------------- + +`git_config` respects includes automatically. The lower-level +`git_config_from_file` does not. + +Writing Config Files +-------------------- + +TODO diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 21ca6a2553..adb6f0c896 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider world can take many forms, in this document the word "credential" always refers to a username and password pair). +This document describes two interfaces: the C API that the credential +subsystem provides to the rest of git, and the protocol that git uses to +communicate with system-specific "credential helpers". If you are +writing git code that wants to look up or prompt for credentials, see +the section "C API" below. If you want to write your own helper, see +the section on "Credential Helpers" below. + +Typical setup +------------- + +------------ ++-----------------------+ +| git code (C) |--- to server requiring ---> +| | authentication +|.......................| +| C credential API |--- prompt ---> User ++-----------------------+ + ^ | + | pipe | + | v ++-----------------------+ +| git credential helper | ++-----------------------+ +------------ + +The git code (typically a remote-helper) will call the C API to obtain +credential data like a login/password pair (credential_fill). The +API will itself call a remote helper (e.g. "git credential-cache" or +"git credential-store") that may retrieve credential data from a +store. If the credential helper cannot find the information, the C API +will prompt the user. Then, the caller of the API takes care of +contacting the server, and does the actual authentication. + +C API +----- + +The credential C API is meant to be called by git code which needs to +acquire or store a credential. It is centered around an object +representing a single credential and provides three basic operations: +fill (acquire credentials by calling helpers and/or prompting the user), +approve (mark a credential as successfully used so that it can be stored +for later use), and reject (mark a credential as unsuccessful so that it +can be erased from any persistent storage). + Data Structures ---------------- +~~~~~~~~~~~~~~~ `struct credential`:: @@ -21,14 +65,17 @@ Data Structures The `helpers` member of the struct is a `string_list` of helpers. Each string specifies an external helper which will be run, in order, to either acquire or store credentials. See the section on credential -helpers below. +helpers below. This list is filled-in by the API functions +according to the corresponding configuration variables before +consulting helpers, so there usually is no need for a caller to +modify the helpers field at all. + This struct should always be initialized with `CREDENTIAL_INIT` or `credential_init`. Functions ---------- +~~~~~~~~~ `credential_init`:: @@ -72,7 +119,7 @@ Functions Parse a URL into broken-down credential fields. Example -------- +~~~~~~~ The example below shows how the functions of the credential API could be used to login to a fictitious "foo" service on a remote host: @@ -135,8 +182,10 @@ credentials from and to long-term storage (where "long-term" is simply longer than a single git process; e.g., credentials may be stored in-memory for a few minutes, or indefinitely on disk). -Each helper is specified by a single string. The string is transformed -by git into a command to be executed using these rules: +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:git-config[1]). +The string is transformed by git into a command to be executed using +these rules: 1. If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command. @@ -243,3 +292,10 @@ request. If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older helpers will just ignore the new requests). + +See also +-------- + +linkgit:gitcredentials[7] + +linkgit:git-config[5] (See configuration variables `credential.*`) diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 4b92514f60..3062389404 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -21,7 +21,7 @@ that allow to change the behavior of a command. * There are basically two forms of options: 'Short options' consist of one dash (`-`) and one alphanumeric character. - 'Long options' begin with two dashes (`\--`) and some + 'Long options' begin with two dashes (`--`) and some alphanumeric characters. * Options are case-sensitive. @@ -31,7 +31,7 @@ The parse-options API allows: * 'sticked' and 'separate form' of options with arguments. `-oArg` is sticked, `-o Arg` is separate form. - `\--option=Arg` is sticked, `\--option Arg` is separate form. + `--option=Arg` is sticked, `--option Arg` is separate form. * Long options may be 'abbreviated', as long as the abbreviation is unambiguous. @@ -39,11 +39,12 @@ The parse-options API allows: * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`. * Boolean long options can be 'negated' (or 'unset') by prepending - `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`. + `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely, + options that begin with `no-` can be 'negated' by removing it. -* Options and non-option arguments can clearly be separated using the `\--` - option, e.g. `-a -b \--option \-- \--this-is-a-file` indicates that - `\--this-is-a-file` must not be processed as an option. +* Options and non-option arguments can clearly be separated using the `--` + option, e.g. `-a -b --option -- --this-is-a-file` indicates that + `--this-is-a-file` must not be processed as an option. Steps to parse options ---------------------- @@ -75,7 +76,7 @@ before the full parser, which in turn shows the full help message. Flags are the bitwise-or of: `PARSE_OPT_KEEP_DASHDASH`:: - Keep the `\--` that usually separates options from + Keep the `--` that usually separates options from non-option arguments. `PARSE_OPT_STOP_AT_NON_OPTION`:: @@ -113,22 +114,22 @@ say `static struct option builtin_add_options[]`. There are some macros to easily define options: `OPT__ABBREV(&int_var)`:: - Add `\--abbrev[=<n>]`. + Add `--abbrev[=<n>]`. `OPT__COLOR(&int_var, description)`:: - Add `\--color[=<when>]` and `--no-color`. + Add `--color[=<when>]` and `--no-color`. `OPT__DRY_RUN(&int_var, description)`:: - Add `-n, \--dry-run`. + Add `-n, --dry-run`. `OPT__FORCE(&int_var, description)`:: - Add `-f, \--force`. + Add `-f, --force`. `OPT__QUIET(&int_var, description)`:: - Add `-q, \--quiet`. + Add `-q, --quiet`. `OPT__VERBOSE(&int_var, description)`:: - Add `-v, \--verbose`. + Add `-v, --verbose`. `OPT_GROUP(description)`:: Start an option group. `description` is a short string that @@ -215,10 +216,10 @@ The last element of the array must be `OPT_END()`. If not stated otherwise, interpret the arguments as follows: * `short` is a character for the short option - (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit), + (e.g. `'e'` for `-e`, use `0` to omit), * `long` is a string for the long option - (e.g. `"example"` for `\--example`, use `NULL` to omit), + (e.g. `"example"` for `--example`, use `NULL` to omit), * `int_var` is an integer variable, @@ -242,10 +243,10 @@ The function must be defined in this form: The callback mechanism is as follows: * Inside `func`, the only interesting member of the structure - given by `opt` is the void pointer `opt\->value`. - `\*opt\->value` will be the value that is saved into `var`, if you + given by `opt` is the void pointer `opt->value`. + `*opt->value` will be the value that is saved into `var`, if you use `OPT_CALLBACK()`. - For example, do `*(unsigned long *)opt\->value = 42;` to get 42 + For example, do `*(unsigned long *)opt->value = 42;` to get 42 into an `unsigned long` variable. * Return value `0` indicates success and non-zero return diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt index 996da0503a..b7d0d9a8a7 100644 --- a/Documentation/technical/api-revision-walking.txt +++ b/Documentation/technical/api-revision-walking.txt @@ -56,6 +56,11 @@ function. returning a `struct commit *` each time you call it. The end of the revision list is indicated by returning a NULL pointer. +`reset_revision_walk`:: + + Reset the flags used by the revision walking api. You can use + this to do multiple sequencial revision walks. + Data structures --------------- diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index afe2759951..95a8bf3846 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -255,8 +255,24 @@ same behaviour as well. `strbuf_getline`:: - Read a line from a FILE* pointer. The second argument specifies the line + Read a line from a FILE *, overwriting the existing contents + of the strbuf. The second argument specifies the line terminator character, typically `'\n'`. + Reading stops after the terminator or at EOF. The terminator + is removed from the buffer before returning. Returns 0 unless + there was nothing left before EOF, in which case it returns `EOF`. + +`strbuf_getwholeline`:: + + Like `strbuf_getline`, but keeps the trailing terminator (if + any) in the buffer. + +`strbuf_getwholeline_fd`:: + + Like `strbuf_getwholeline`, but operates on a file descriptor. + It reads one character at a time, so it is very slow. Do not + use it unless you need the correct position in the file + descriptor. `stripspace`:: diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index ce24eb96f5..5a0c14fceb 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -83,7 +83,9 @@ Functions Insert a new element to the string_list. The returned pointer can be handy if you want to write something to the `util` pointer of the - string_list_item containing the just added string. + string_list_item containing the just added string. If the given + string already exists the insertion will be skipped and the + pointer to the existing item returned. + Since this function uses xrealloc() (which die()s if it fails) if the list needs to grow, it is safe not to check the pointer. I.e. you may diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 8930b3fabc..9d25b30178 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -113,9 +113,22 @@ GIT index format are encoded in 7-bit ASCII and the encoding cannot contain a NUL byte (iow, this is a UNIX pathname). + (Version 4) In version 4, the entry path name is prefix-compressed + relative to the path name for the previous entry (the very first + entry is encoded as if the path name for the previous entry is an + empty string). At the beginning of an entry, an integer N in the + variable width encoding (the same encoding as the offset is encoded + for OFS_DELTA pack entries; see pack-format.txt) is stored, followed + by a NUL-terminated string S. Removing N bytes from the end of the + path name for the previous entry, and replacing it with the string S + yields the path name for this entry. + 1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes while keeping the name NUL-terminated. + (Version 4) In version 4, the padding after the pathname does not + exist. + == Extensions === Cached tree diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 546980c0a4..49cdc571cd 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -351,7 +351,7 @@ Then the server will start sending its packfile data. A simple clone may look like this (with no 'have' lines): ---- - C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d\0multi_ack \ + C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \ side-band-64k ofs-delta\n C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n @@ -367,7 +367,7 @@ A simple clone may look like this (with no 'have' lines): An incremental update (fetch) response might look like this: ---- - C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d\0multi_ack \ + C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \ side-band-64k ofs-delta\n C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n diff --git a/Documentation/technical/protocol-common.txt b/Documentation/technical/protocol-common.txt index d30a1b9510..fb7ff084f8 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/technical/protocol-common.txt @@ -36,7 +36,7 @@ More specifically, they: . They cannot have ASCII control characters (i.e. bytes whose values are lower than \040, or \177 `DEL`), space, tilde `~`, - caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`, + caret `^`, colon `:`, question-mark `?`, asterisk `*`, or open bracket `[` anywhere. . They cannot end with a slash `/` nor a dot `.`. |