diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.0.4.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.1.0.txt | 122 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 2 | ||||
| -rw-r--r-- | Documentation/git.txt | 8 | ||||
| -rw-r--r-- | Documentation/technical/api-config.txt | 173 |
5 files changed, 243 insertions, 67 deletions
diff --git a/Documentation/RelNotes/2.0.4.txt b/Documentation/RelNotes/2.0.4.txt new file mode 100644 index 0000000000..7e340921a2 --- /dev/null +++ b/Documentation/RelNotes/2.0.4.txt @@ -0,0 +1,5 @@ +Git v2.0.4 Release Notes +======================== + + * An earlier update to v2.0.2 broken output from "git diff-tree", + which is fixed in this release. diff --git a/Documentation/RelNotes/2.1.0.txt b/Documentation/RelNotes/2.1.0.txt index be598ad7a2..ae4753728e 100644 --- a/Documentation/RelNotes/2.1.0.txt +++ b/Documentation/RelNotes/2.1.0.txt @@ -12,7 +12,7 @@ Backward compatibility notes $ git config core.pager "less -S" to restore the traditional behaviour. It is expected that people - find output from the most subcommands easier to read with the new + find output from most subcommands easier to read with the new default, except for "blame" which tends to produce really long lines. To override the new default only for "git blame", you can do this: @@ -31,7 +31,7 @@ UI, Workflows & Features default value "FRSX" when we spawn "less" as the pager. "S" (chop long lines instead of wrapping) has been removed from this default set of options, because it is more or less a personal taste thing, - as opposed to others that have good justifications (i.e. "R" is + as opposed to the others that have good justifications (i.e. "R" is very much justified because many kinds of output we produce are colored and "FX" is justified because output we produce is often shorter than a page). @@ -39,47 +39,47 @@ UI, Workflows & Features * The logic and data used to compute the display width needed for UTF-8 strings have been updated to match Unicode 7.0 better. - * HTTP-based transports learned to propagate the error messages from - the webserver better to the client coming over the HTTP transport. + * HTTP-based transports learned to better propagate the error messages from + the webserver to the client coming over the HTTP transport. * The completion script for bash (in contrib/) has been updated to - handle aliases that define complex sequence of commands better. + better handle aliases that define a complex sequence of commands. - * The "core.preloadindex" configuration variable is by default - enabled, allowing modern platforms to take advantage of the - multiple cores they have. + * The "core.preloadindex" configuration variable is enabled by default, + allowing modern platforms to take advantage of their + multiple cores. * "git clone" applies the "if cloning from a local disk, physically - copy repository using hardlinks, unless otherwise told not to with - --no-local" optimization when url.*.insteadOf mechanism rewrites a - "git clone $URL" that refers to a repository over the network to a + copy the repository using hardlinks, unless otherwise told not to with + --no-local" optimization when the url.*.insteadOf mechanism rewrites a + remote-repository "git clone $URL" into a clone from a local disk. - * "git commit --date=<date>" option learned to read from more + * "git commit --date=<date>" option learned more timestamp formats, including "--date=now". * The `core.commentChar` configuration variable is used to specify a - custom comment character other than the default "#" to be used in - the commit log editor. This can be set to `auto` to attempt to - choose a different character that does not conflict with what - already starts a line in the message being edited for cases like + custom comment character (other than the default "#") for + the commit message editor. This can be set to `auto` to attempt to + choose a different character that does not conflict with any that + already starts a line in the message being edited, for cases like "git commit --amend". - * "git format-patch" learned --signature-file=<file> to take the mail - signature from. + * "git format-patch" learned --signature-file=<file> to add the contents + of a file as a signature to the mail message it produces. - * "git grep" learned grep.fullname configuration variable to force - "--full-name" to be default. This may cause regressions on - scripted users that do not expect this new behaviour. + * "git grep" learned the grep.fullname configuration variable to force + "--full-name" to be the default. This may cause regressions for + scripted users who do not expect this new behaviour. * "git imap-send" learned to ask the credential helper for auth material. - * "git log" and friends now understand the value "auto" set to the + * "git log" and friends now understand the value "auto" for the "log.decorate" configuration variable to enable the "--decorate" option automatically when the output is sent to tty. - * "git merge" without argument, even when there is an upstream + * "git merge" without an argument, even when there is an upstream defined for the current branch, refused to run until merge.defaultToUpstream is set to true. Flip the default of that configuration variable to true. @@ -87,22 +87,20 @@ UI, Workflows & Features * "git mergetool" learned to drive the vimdiff3 backend. * mergetool.prompt used to default to 'true', always asking "do you - really want to run the tool on this path?". Among the two - purposes this prompt serves, ignore the use case to confirm that - the user wants to view particular path with the named tool, and - redefine the meaning of the prompt only to confirm the choice of - the tool made by the autodetection (for those who configured the - tool explicitly, the prompt shown for the latter purpose is - simply annoying). - - Strictly speaking, this is a backward incompatible change and the + really want to run the tool on this path?". The default has been + changed to 'false'. However, the prompt will still appear if + mergetool used its autodetection system to guess which tool to use. + Users who explicitly specify or configure a tool will no longer see + the prompt by default. + + Strictly speaking, this is a backward incompatible change and users need to explicitly set the variable to 'true' if they want - to resurrect the now-ignored use case. + to be prompted to confirm running the tool on each path. * "git replace" learned the "--edit" subcommand to create a replacement by editing an existing object. - * "git replace" learned a "--graft" option to rewrite parents of a + * "git replace" learned a "--graft" option to rewrite the parents of a commit. * "git send-email" learned "--to-cover" and "--cc-cover" options, to @@ -117,10 +115,10 @@ UI, Workflows & Features being edited as a comment in the editor. * "git tag" learned to pay attention to "tag.sort" configuration, to - be used as the default sort order when no --sort=<value> the option + be used as the default sort order when no --sort=<value> option is given. - * "git verify-commit" command to check GPG signature in signed + * A new "git verify-commit" command, to check GPG signatures in signed commits, in a way similar to "git verify-tag" is used to check signed tags, was added. @@ -129,8 +127,8 @@ Performance, Internal Implementation, etc. * Build procedure for 'subtree' (in contrib/) has been cleaned up. - * The support for the profile-feedback build, which has been left - bit-rotten for quite a while, has been updated. + * Support for the profile-feedback build, which has + bit-rotted for quite a while, has been updated. * An experimental format to use two files (the base file and incremental changes relative to it) to represent the index has been @@ -138,16 +136,12 @@ Performance, Internal Implementation, etc. when only small part of the working tree changes. * Effort to shrink the size of patches Windows folks maintain on top - by upstreaming them continues. - - * Patches maintained by msysgit folks for Windows port are being - upstreamed here a bit by bit. + by upstreaming them continues. More tests that are not applicable + to the Windows environment are identified and either skipped or + made more portable. - * The leaf function to check validity of a refname format has been - micro-optimized, using SSE2 instructions when available. A few - breakages during its development have been caught and fixed already - but there might remain some more still; please test and report if - you find any. + * Eradication of "test $condition -a $condition" from our scripts + continues. * The `core.deltabasecachelimit` used to default to 16 MiB , but this proved to be too small, and has been bumped to 96 MiB. @@ -156,7 +150,7 @@ Performance, Internal Implementation, etc. structure that is used to keep track of the work to be done. * "git diff" that compares 3-or-more trees (e.g. parents and the - result of a merge) have been optimized. + result of a merge) has been optimized. * The API to update/delete references are being converted to handle updates to multiple references in a transactional way. As an @@ -192,8 +186,8 @@ notes for details). to a tty. (merge 38de156 mn/sideband-no-ansi later to maint). - * Mishandling of patterns in .gitignore that has trailing SPs quoted - with backslashes (e.g. ones that end with "\ ") have been + * Mishandling of patterns in .gitignore that have trailing SPs quoted + with backslashes (e.g. ones that end with "\ ") has been corrected. (merge 97c1364be6b pb/trim-trailing-spaces later to maint). @@ -230,7 +224,7 @@ notes for details). and to allow the caller find the length of the object. (merge 218aa3a jk/commit-buffer-length later to maint). - * The "mailmap.file" configuration option did not support the tilde + * The "mailmap.file" configuration option did not support tilde expansion (i.e. ~user/path and ~/path). (merge 9352fd5 ow/config-mailmap-pathname later to maint). @@ -242,7 +236,7 @@ notes for details). * The unix-domain socket used by the sample credential cache daemon tried to unlink an existing stale one at a wrong path, if the path to the socket was given as an overlong path that does not fit in - sun_path member of the sockaddr_un structure. + the sun_path member of the sockaddr_un structure. (merge 2869b3e rs/fix-unlink-unix-socket later to maint). * An ancient rewrite passed a wrong pointer to a curl library @@ -250,12 +244,12 @@ notes for details). (merge 479eaa8 ah/fix-http-push later to maint). * "--ignore-space-change" option of "git apply" ignored the spaces - at the beginning of line too aggressively, which is inconsistent - with the option of the same name "diff" and "git diff" have. + at the beginning of lines too aggressively, which is inconsistent + with the option of the same name that "diff" and "git diff" have. (merge 14d3bb4 jc/apply-ignore-whitespace later to maint). - * "git blame" miscounted number of columns needed to show localized - timestamps, resulting in jaggy left-side-edge of the source code + * "git blame" miscounted the number of columns needed to show localized + timestamps, resulting in a jaggy left-side-edge for the source code lines in its output. (merge dd75553 jx/blame-align-relative-time later to maint). @@ -269,17 +263,17 @@ notes for details). because it incorrectly used strstr(). (merge 60a5f5f jc/fix-clone-single-starting-at-a-tag later to maint). - * "git commit --allow-empty-messag -C $commit" did not work when the + * "git commit --allow-empty-message -C $commit" did not work when the commit did not have any log message. (merge 076cbd6 jk/commit-C-pick-empty later to maint). * "git diff --find-copies-harder" sometimes pretended as if the mode - bits have changed for paths that are marked with assume-unchanged + bits have changed for paths that are marked with the assume-unchanged bit. (merge 5304810 jk/diff-files-assume-unchanged later to maint). * "filter-branch" left an empty single-parent commit that results when - all parents of a merge commit gets mapped to the same commit, even + all parents of a merge commit get mapped to the same commit, even under "--prune-empty". (merge 79bc4ef cb/filter-branch-prune-empty-degenerate-merges later to maint). @@ -312,10 +306,10 @@ notes for details). mergetag that was and was not correctly validated. (merge 42c55ce mg/fix-log-mergetag-color later to maint). - * "log --show-signature" did not pay attention to "--graph" option. + * "log --show-signature" did not pay attention to the "--graph" option. (merge cf3983d zk/log-graph-showsig later to maint). - * "git mailinfo" used to read beyond the end of header string while + * "git mailinfo" used to read beyond the ends of header strings while parsing an incoming e-mail message to extract the patch. (merge b1a013d rs/mailinfo-header-cmp later to maint). @@ -335,7 +329,7 @@ notes for details). (merge fb79947 rs/pack-objects-no-unnecessary-realloc later to maint). * Recent updates to "git repack" started to duplicate objects that - are in packfiles marked with .keep flag into the new packfile by + are in packfiles marked with the .keep flag into the new packfile by mistake. (merge d078d85 jk/repack-pack-keep-objects later to maint). @@ -373,14 +367,14 @@ notes for details). * "git status", even though it is a read-only operation, tries to update the index with refreshed lstat(2) info to optimize future accesses to the working tree opportunistically, but this could - race with a "read-write" operation that modify the index while it + race with a "read-write" operation that modifies the index while it is running. Detect such a race and avoid overwriting the index. (merge 426ddee ym/fix-opportunistic-index-update-race later to maint). * "git status" (and "git commit") behaved as if changes in a modified submodule are not there if submodule.*.ignore configuration is set, which was misleading. The configuration is only to unclutter diff - output during the course of development, and should not to hide + output during the course of development, and not to hide changes in the "status" output to cause the users forget to commit them. (merge c215d3d jl/status-added-submodule-is-never-ignored later to maint). diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 21cd455508..c0d7403b9a 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -33,7 +33,7 @@ When the command line does not specify what to push with `<refspec>...` arguments or `--all`, `--mirror`, `--tags` options, the command finds the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide -what to push (See gitlink:git-config[1] for the meaning of `push.default`). +what to push (See linkgit:git-config[1] for the meaning of `push.default`). OPTIONS[[OPTIONS]] diff --git a/Documentation/git.txt b/Documentation/git.txt index a0f1ede866..de7b870a35 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,15 @@ unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v2.0.3/git.html[documentation for release 2.0.3] +* link:v2.1.0/git.html[documentation for release 2.1] * release notes for + link:RelNotes/2.1.0.txt[2.1]. + +* link:v2.0.4/git.html[documentation for release 2.0.4] + +* release notes for + link:RelNotes/2.0.4.txt[2.0.4], link:RelNotes/2.0.3.txt[2.0.3], link:RelNotes/2.0.2.txt[2.0.2], link:RelNotes/2.0.1.txt[2.0.1], diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index 230b3a0f60..21f280ca6d 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -77,6 +77,86 @@ 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`. +Querying For Specific Variables +------------------------------- + +For programs wanting to query for specific variables in a non-callback +manner, the config API provides two functions `git_config_get_value` +and `git_config_get_value_multi`. They both read values from an internal +cache generated previously from reading the config files. + +`int git_config_get_value(const char *key, const char **value)`:: + + Finds the highest-priority value for the configuration variable `key`, + stores the pointer to it in `value` and returns 0. When the + configuration variable `key` is not found, returns 1 without touching + `value`. The caller should not free or modify `value`, as it is owned + by the cache. + +`const struct string_list *git_config_get_value_multi(const char *key)`:: + + Finds and returns the value list, sorted in order of increasing priority + for the configuration variable `key`. When the configuration variable + `key` is not found, returns NULL. The caller should not free or modify + the returned pointer, as it is owned by the cache. + +`void git_config_clear(void)`:: + + Resets and invalidates the config cache. + +The config API also provides type specific API functions which do conversion +as well as retrieval for the queried variable, including: + +`int git_config_get_int(const char *key, int *dest)`:: + + Finds and parses the value to an integer for the configuration variable + `key`. Dies on error; otherwise, stores the value of the parsed integer in + `dest` and returns 0. When the configuration variable `key` is not found, + returns 1 without touching `dest`. + +`int git_config_get_ulong(const char *key, unsigned long *dest)`:: + + Similar to `git_config_get_int` but for unsigned longs. + +`int git_config_get_bool(const char *key, int *dest)`:: + + Finds and parses the value into a boolean value, for the configuration + variable `key` 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, + stores the value of the parsed result in `dest` and returns 0. When the + configuration variable `key` is not found, returns 1 without touching + `dest`. + +`int git_config_get_bool_or_int(const char *key, int *is_bool, int *dest)`:: + + Similar to `git_config_get_bool`, except that integers are copied as-is, + and `is_bool` flag is unset. + +`int git_config_get_maybe_bool(const char *key, int *dest)`:: + + Similar to `git_config_get_bool`, except that it returns -1 on error + rather than dying. + +`int git_config_get_string_const(const char *key, const char **dest)`:: + + Allocates and copies the retrieved string into the `dest` parameter for + the configuration variable `key`; if NULL string is given, prints an + error message and returns -1. When the configuration variable `key` is + not found, returns 1 without touching `dest`. + +`int git_config_get_string(const char *key, char **dest)`:: + + Similar to `git_config_get_string_const`, except that retrieved value + copied into the `dest` parameter is a mutable string. + +`int git_config_get_pathname(const char *key, const char **dest)`:: + + Similar to `git_config_get_string`, but expands `~` or `~user` into + the user's home directory when found at the beginning of the path. + +See test-config.c for usage examples. + Value Parsing Helpers --------------------- @@ -134,7 +214,98 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data) `git_config` respects includes automatically. The lower-level `git_config_from_file` does not. +Custom Configsets +----------------- + +A `config_set` can be used to construct an in-memory cache for +config-like files that the caller specifies (i.e., files like `.gitmodules`, +`~/.gitconfig` etc.). For example, + +--------------------------------------- +struct config_set gm_config; +git_configset_init(&gm_config); +int b; +/* we add config files to the config_set */ +git_configset_add_file(&gm_config, ".gitmodules"); +git_configset_add_file(&gm_config, ".gitmodules_alt"); + +if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) { + /* hack hack hack */ +} + +/* when we are done with the configset */ +git_configset_clear(&gm_config); +---------------------------------------- + +Configset API provides functions for the above mentioned work flow, including: + +`void git_configset_init(struct config_set *cs)`:: + + Initializes the config_set `cs`. + +`int git_configset_add_file(struct config_set *cs, const char *filename)`:: + + Parses the file and adds the variable-value pairs to the `config_set`, + dies if there is an error in parsing the file. Returns 0 on success, or + -1 if the file does not exist or is inaccessible. The user has to decide + if he wants to free the incomplete configset or continue using it when + the function returns -1. + +`int git_configset_get_value(struct config_set *cs, const char *key, const char **value)`:: + + Finds the highest-priority value for the configuration variable `key` + and config set `cs`, stores the pointer to it in `value` and returns 0. + When the configuration variable `key` is not found, returns 1 without + touching `value`. The caller should not free or modify `value`, as it + is owned by the cache. + +`const struct string_list *git_configset_get_value_multi(struct config_set *cs, const char *key)`:: + + Finds and returns the value list, sorted in order of increasing priority + for the configuration variable `key` and config set `cs`. When the + configuration variable `key` is not found, returns NULL. The caller + should not free or modify the returned pointer, as it is owned by the cache. + +`void git_configset_clear(struct config_set *cs)`:: + + Clears `config_set` structure, removes all saved variable-value pairs. + +In addition to above functions, the `config_set` API provides type specific +functions in the vein of `git_config_get_int` and family but with an extra +parameter, pointer to struct `config_set`. +They all behave similarly to the `git_config_get*()` family described in +"Querying For Specific Variables" above. + Writing Config Files -------------------- -TODO +Git gives multiple entry points in the Config API to write config values to +files namely `git_config_set_in_file` and `git_config_set`, which write to +a specific config file or to `.git/config` respectively. They both take a +key/value pair as parameter. +In the end they both call `git_config_set_multivar_in_file` which takes four +parameters: + +- the name of the file, as a string, to which key/value pairs will be written. + +- the name of key, as a string. 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 variable, as a string. If value is equal to NULL, it will + remove the matching key from the config file. + +- the value regex, as a string. It will disregard key/value pairs where value + does not match. + +- a multi_replace value, as an int. If value is equal to zero, nothing or only + one matching key/value is replaced, else all matching key/values (regardless + how many) are removed, before the new pair is written. + +It returns 0 on success. + +Also, there are functions `git_config_rename_section` and +`git_config_rename_section_in_file` with parameters `old_name` and `new_name` +for renaming or removing sections in the config files. If NULL is passed +through `new_name` parameter, the section will be removed from the config file. |