summaryrefslogtreecommitdiff
path: root/Documentation/technical
AgeCommit message (Collapse)AuthorFilesLines
2012-05-14pack-protocol: fix first-want separator in the examplesLibravatar Carlos Martín Nieto1-2/+2
When sending the "want" list, the capabilities list is separated from the obj-id by a SP instead of NUL as in the ref advertisement. The text is correct, but the examples wrongly show the separator as NUL. Fix the example so it uses SP. Signed-off-by: Carlos Martín Nieto <cmn@elego.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-18argv-array: add a new "pushl" methodLibravatar Jeff King1-0/+5
It can be convenient to push many strings in a single line (e.g., if you are initializing an array with defaults). This patch provides a convenience wrapper to allow this. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-03-30Merge branch 'maint'Libravatar Junio C Hamano1-1/+3
* maint: string-list: document that string_list_insert() inserts unique strings
2012-03-30string-list: document that string_list_insert() inserts unique stringsLibravatar Heiko Voigt1-1/+3
Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-03-04Merge branch 'tr/maint-bundle-long-subject' into maintLibravatar Junio C Hamano1-1/+17
* tr/maint-bundle-long-subject: t5704: match tests to modern style strbuf: improve strbuf_get*line documentation bundle: use a strbuf to scan the log for boundary commits bundle: put strbuf_readline_fd in strbuf.c with adjustments
2012-03-01Merge branch 'rs/no-no-no-parseopt'Libravatar Junio C Hamano1-1/+2
* rs/no-no-no-parseopt: parse-options: remove PARSE_OPT_NEGHELP parse-options: allow positivation of options starting, with no- test-parse-options: convert to OPT_BOOL() Conflicts: builtin/grep.c
2012-02-26Merge branch 'tr/maint-bundle-long-subject'Libravatar Junio C Hamano1-1/+17
* tr/maint-bundle-long-subject: t5704: match tests to modern style strbuf: improve strbuf_get*line documentation bundle: use a strbuf to scan the log for boundary commits bundle: put strbuf_readline_fd in strbuf.c with adjustments
2012-02-26parse-options: allow positivation of options starting, with no-Libravatar René Scharfe1-1/+2
Long options can be negated by adding no- right after the leading two dashes. This is useful e.g. to override options set by aliases. For options that are defined to start with no- already, this looks a bit funny. Allow such options to also be negated by removing the prefix. The following thirteen options are affected: apply --no-add bisect--helper --no-checkout checkout-index --no-create clone --no-checkout --no-hardlinks commit --no-verify --no-post-rewrite format-patch --no-binary hash-object --no-filters read-tree --no-sparse-checkout revert --no-commit show-branch --no-name update-ref --no-deref The following five are NOT affected because they are defined with PARSE_OPT_NONEG or the non-negated version is defined as well: branch --no-merged format-patch --no-stat --no-numbered update-index --no-assume-unchanged --no-skip-worktree Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-23strbuf: improve strbuf_get*line documentationLibravatar Thomas Rast1-1/+17
Clarify strbuf_getline() documentation, and add the missing documentation for strbuf_getwholeline() and strbuf_getwholeline_fd(). Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-17config: add include directiveLibravatar Jeff King1-1/+27
It can be useful to split your ~/.gitconfig across multiple files. For example, you might have a "main" file which is used on many machines, but a small set of per-machine tweaks. Or you may want to make some of your config public (e.g., clever aliases) while keeping other data back (e.g., your name or other identifying information). Or you may want to include a number of config options in some subset of your repos without copying and pasting (e.g., you want to reference them from the .git/config of participating repos). This patch introduces an include directive for config files. It looks like: [include] path = /path/to/file This is syntactically backwards-compatible with existing git config parsers (i.e., they will see it as another config entry and ignore it unless you are looking up include.path). The implementation provides a "git_config_include" callback which wraps regular config callbacks. Callers can pass it to git_config_from_file, and it will transparently follow any include directives, passing all of the discovered options to the real callback. Include directives are turned on automatically for "regular" git config parsing. This includes calls to git_config, as well as calls to the "git config" program that do not specify a single file (e.g., using "-f", "--global", etc). They are not turned on in other cases, including: 1. Parsing of other config-like files, like .gitmodules. There isn't a real need, and I'd rather be conservative and avoid unnecessary incompatibility or confusion. 2. Reading single files via "git config". This is for two reasons: a. backwards compatibility with scripts looking at config-like files. b. inspection of a specific file probably means you care about just what's in that file, not a general lookup for "do we have this value anywhere at all". If that is not the case, the caller can always specify "--includes". 3. Writing files via "git config"; we want to treat include.* variables as literal items to be copied (or modified), and not expand them. So "git config --unset-all foo.bar" would operate _only_ on .git/config, not any of its included files (just as it also does not operate on ~/.gitconfig). Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-17config: provide a version of git_config with more optionsLibravatar Jeff King1-0/+12
Callers may want to provide a specific version of a file in which to look for config. Right now this can be done by setting the magic global config_exclusive_filename variable. By providing a version of git_config that takes a filename, we can take a step towards making this magic global go away. Furthermore, by providing a more "advanced" interface, we now have a a natural place to add new options for callers like git-config, which care about tweaking the specifics of config lookup, without disturbing the large number of "simple" users (i.e., every other part of git). The astute reader of this patch may notice that the logic for handling config_exclusive_filename was taken out of git_config_early, but added into git_config. This means that git_config_early will no longer respect config_exclusive_filename. That's OK, because the only other caller of git_config_early is check_repository_format_gently, but the only function which sets config_exclusive_filename is cmd_config, which does not call check_repository_format_gently (and if it did, it would have been a bug, anyway, as we would be checking the repository format in the wrong file). Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-17docs/api-config: minor clarificationsLibravatar Jeff King1-7/+8
The first change simply drops some parentheses to make a statement more clear. The seconds clarifies that almost nobody wants to call git_config_early. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-02-06docs: add a basic description of the config APILibravatar Jeff King1-0/+101
This wasn't documented at all; this is pretty bare-bones, but it should at least give new git hackers a basic idea of how the reading side works. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-12-11credential: add function for parsing url componentsLibravatar Jeff King1-0/+4
All of the components of a credential struct can be found in a URL. For example, the URL: http://foo:bar@example.com/repo.git contains: protocol=http host=example.com path=repo.git username=foo password=bar We want to be able to turn URLs into broken-down credential structs so that we know two things: 1. Which parts of the username/password we still need 2. What the context of the request is (for prompting or as a key for storing credentials). This code is based on http_auth_init in http.c, but needed a few modifications in order to get all of the components that the credential object is interested in. Once the http code is switched over to the credential API, then http_auth_init can just go away. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-12-11introduce credentials APILibravatar Jeff King1-0/+241
There are a few places in git that need to get a username and password credential from the user; the most notable one is HTTP authentication for smart-http pushing. Right now the only choices for providing credentials are to put them plaintext into your ~/.netrc, or to have git prompt you (either on the terminal or via an askpass program). The former is not very secure, and the latter is not very convenient. Unfortunately, there is no "always best" solution for password management. The details will depend on the tradeoff you want between security and convenience, as well as how git can integrate with other security systems (e.g., many operating systems provide a keychain or password wallet for single sign-on). This patch provides an abstract notion of credentials as a data item, and provides three basic operations: - fill (i.e., acquire from external storage or from the user) - approve (mark a credential as "working" for further storage) - reject (mark a credential as "not working", so it can be removed from storage) These operations can be backed by external helper processes that interact with system- or user-specific secure storage. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-10-12Merge branch 'nd/document-err-packet'Libravatar Junio C Hamano1-0/+7
* nd/document-err-packet: pack-protocol: document "ERR" line
2011-10-12Merge branch 'jc/parse-options-boolean'Libravatar Junio C Hamano1-5/+16
* jc/parse-options-boolean: apply: use OPT_NOOP_NOARG revert: use OPT_NOOP_NOARG parseopt: add OPT_NOOP_NOARG archive.c: use OPT_BOOL() parse-options: deprecate OPT_BOOLEAN Conflicts: builtin/revert.c
2011-10-05Merge branch 'jk/argv-array'Libravatar Junio C Hamano2-0/+125
* jk/argv-array: run_hook: use argv_array API checkout: use argv_array API bisect: use argv_array API quote: provide sq_dequote_to_argv_array refactor argv_array into generic code quote.h: fix bogus comment add sha1_array API docs
2011-10-03pack-protocol: document "ERR" lineLibravatar Nguyen Thai Ngoc Duy1-0/+7
Since a807328 (connect.c: add a way for git-daemon to pass an error back to client), git client recognizes "ERR" line and prints a friendly message to user if an error happens at server side. Document this. Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-09-28parseopt: add OPT_NOOP_NOARGLibravatar René Scharfe1-0/+5
Add OPT_NOOP_NOARG, a helper macro to define deprecated options in a standard way. The help text is taken from the no-op option -r of git revert. The callback could be made to emit a (conditional?) warning later. And we could also add OPT_NOOP (requiring an argument) etc. as needed. Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-09-27parse-options: deprecate OPT_BOOLEANLibravatar Junio C Hamano1-5/+11
It is natural to expect that an option defined with OPT_BOOLEAN() could be used in this way: int option = -1; /* unspecified */ struct option options[] = { OPT_BOOLEAN(0, "option", &option, "set option"), OPT_END() }; parse_options(ac, av, prefix, options, usage, 0); if (option < 0) ... do the default thing ... else if (!option) ... --no-option was given ... else ... --option was given ... to easily tell three cases apart: - There is no mention of the `--option` on the command line; - The variable is positively set with `--option`; or - The variable is explicitly negated with `--no-option`. Unfortunately, this is not the case. OPT_BOOLEAN() increments the variable every time `--option` is given, and resets it to zero when `--no-option` is given. As a first step to remedy this, introduce a true boolean OPT_BOOL(), and rename OPT_BOOLEAN() to OPT_COUNTUP(). To help transitioning, OPT_BOOLEAN and OPTION_BOOLEAN are defined as deprecated synonyms to OPT_COUNTUP and OPTION_COUNTUP respectively. This is what db7244b (parse-options new features., 2007-11-07) from four years ago started by marking OPTION_BOOLEAN as "INCR would have been a better name". Some existing users do depend on the count-up semantics; for example, users of OPT__VERBOSE() could use it to raise the verbosity level with repeated use of `-v` on the command line, but they probably should be rewritten to use OPT__VERBOSITY() instead these days. I suspect that some users of OPT__FORCE() may also use it to implement different level of forcibleness but I didn't check. On top of this patch, here are the remaining clean-up tasks that other people can help: - Look at each hit in "git grep -e OPT_BOOLEAN"; trace all uses of the value that is set to the underlying variable, and if it can proven that the variable is only used as a boolean, replace it with OPT_BOOL(). If the caller does depend on the count-up semantics, replace it with OPT_COUNTUP() instead. - Same for OPTION_BOOLEAN; replace it with OPTION_SET_INT and arrange to set 1 to the variable for a true boolean, and otherwise replace it with OPTION_COUNTUP. - Look at each hit in "git grep -e OPT__VERBOSE -e OPT__QUIET" and see if they can be replaced with OPT__VERBOSITY(). I'll follow this message up with a separate patch as an example. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-09-14refactor argv_array into generic codeLibravatar Jeff King1-0/+46
The submodule code recently grew generic code to build a dynamic argv array. Many other parts of the code can reuse this, too, so let's make it generically available. There are two enhancements not found in the original code: 1. We now handle the NULL-termination invariant properly, even when no strings have been pushed (before, you could have an empty, NULL argv). This was not a problem for the submodule code, which always pushed at least one argument, but was not sufficiently safe for generic code. 2. There is a formatted variant of the "push" function. This is a convenience function which was not needed by the submodule code, but will make it easier to port other users to the new code. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-09-14add sha1_array API docsLibravatar Jeff King1-0/+79
This API was introduced in 902bb36, but never documented. Let's be nice to future users of the code. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-09-02Merge branch 'en/merge-recursive-2'Libravatar Junio C Hamano1-0/+10
* en/merge-recursive-2: (57 commits) merge-recursive: Don't re-sort a list whose order we depend upon merge-recursive: Fix virtual merge base for rename/rename(1to2)/add-dest t6036: criss-cross + rename/rename(1to2)/add-dest + simple modify merge-recursive: Avoid unnecessary file rewrites t6022: Additional tests checking for unnecessary updates of files merge-recursive: Fix spurious 'refusing to lose untracked file...' messages t6022: Add testcase for spurious "refusing to lose untracked" messages t3030: fix accidental success in symlink rename merge-recursive: Fix working copy handling for rename/rename/add/add merge-recursive: add handling for rename/rename/add-dest/add-dest merge-recursive: Have conflict_rename_delete reuse modify/delete code merge-recursive: Make modify/delete handling code reusable merge-recursive: Consider modifications in rename/rename(2to1) conflicts merge-recursive: Create function for merging with branchname:file markers merge-recursive: Record more data needed for merging with dual renames merge-recursive: Defer rename/rename(2to1) handling until process_entry merge-recursive: Small cleanups for conflict_rename_rename_1to2 merge-recursive: Fix rename/rename(1to2) resolution for virtual merge base merge-recursive: Introduce a merge_file convenience function merge-recursive: Fix modify/delete resolution in the recursive case ...
2011-08-22Merge branch 'maint'Libravatar Junio C Hamano1-0/+81
* maint: add technical documentation about ref iteration Do not use C++-style comments
2011-08-22add technical documentation about ref iterationLibravatar Heiko Voigt1-0/+81
Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-17Merge branch 'mh/check-attr-relative'Libravatar Junio C Hamano1-22/+39
* mh/check-attr-relative: (29 commits) test-path-utils: Add subcommand "prefix_path" test-path-utils: Add subcommand "absolute_path" git-check-attr: Normalize paths git-check-attr: Demonstrate problems with relative paths git-check-attr: Demonstrate problems with unnormalized paths git-check-attr: test that no output is written to stderr Rename git_checkattr() to git_check_attr() git-check-attr: Fix command-line handling to match docs git-check-attr: Drive two tests using the same raw data git-check-attr: Add an --all option to show all attributes git-check-attr: Error out if no pathnames are specified git-check-attr: Process command-line args more systematically git-check-attr: Handle each error separately git-check-attr: Extract a function error_with_usage() git-check-attr: Introduce a new variable git-check-attr: Extract a function output_attr() Allow querying all attributes on a file Remove redundant check Remove redundant call to bootstrap_attr_stack() Extract a function collect_all_attrs() ...
2011-08-14string-list: Add API to remove an item from an unsorted listLibravatar Johannes Sixt1-0/+10
Teach the string-list API how to remove an entry in O(1) runtime by moving the last entry to the vacated spot. As such, the routine works only for unsorted lists. Signed-off-by: Johannes Sixt <j6t@kdbg.org> Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04Rename git_checkattr() to git_check_attr()Libravatar Michael Haggerty1-4/+4
Suggested by: Junio Hamano <gitster@pobox.com> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04Allow querying all attributes on a fileLibravatar Michael Haggerty1-14/+30
Add a function, git_all_attrs(), that reports on all attributes that are set on a path. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04Provide access to the name attribute of git_attrLibravatar Michael Haggerty1-1/+2
It will be present in any likely future reimplementation, and its availability simplifies other code. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-04doc: Correct git_attr() calls in example codeLibravatar Michael Haggerty1-5/+5
Commit 7fb0eaa2 (2010-01-17) changed git_attr() to take a string instead of a string and a length. Update the documentation accordingly. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-03add gitignore entry to description about how to write a builtinLibravatar Heiko Voigt1-0/+2
If the author forgets the gitignore entry the built result will show up as new file in the git working directory. Signed-off-by: Heiko Voigt <hvoigt@hvoigt.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-08-01Merge branch 'an/shallow-doc' into maintLibravatar Junio C Hamano1-29/+74
* an/shallow-doc: Document the underlying protocol used by shallow repositories and --depth commands. Fix documentation of fetch-pack that implies that the client can disconnect after sending wants.
2011-07-31Documentation: clarify the invalidated tree entry formatLibravatar Carlos Martín Nieto1-2/+3
When the entry_count is -1, the tree is invalidated and therefore has not associated hash (or object name). Explicitly state that the next entry starts after the newline. Signed-off-by: Carlos Martín Nieto <cmn@elego.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-06-08Document the underlying protocol used by shallow repositories and --depth ↵Libravatar Alex Neronskiy1-22/+66
commands. Explain the exchange that occurs between a client and server when the client is requesting shallow history and/or is already using a shallow repository. Signed-off-by: Alex Neronskiy <zakmagnus@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-06-08Fix documentation of fetch-pack that implies that the client can disconnect ↵Libravatar Alex Neronskiy1-14/+15
after sending wants. Specify conditions under which the client can terminate the connection early. Previously, an unintended behavior was possible which could confuse servers. Based-on-patch-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Alex Neronskiy <zakmagnus@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-05-26Documentation/technical/api-diff.txt: correct name of diff_unmerge()Libravatar Brandon Casey1-2/+2
Signed-off-by: Brandon Casey <casey@nrlssc.navy.mil> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-26Merge branch 'nd/index-doc'Libravatar Junio C Hamano1-0/+185
* nd/index-doc: doc: technical details about the index file format doc: technical details about the index file format
2011-03-23doc: technical details about the index file formatLibravatar Junio C Hamano1-37/+57
* Clarify "string of unsigned bytes"; * Blob has two variants (regular file vs symlink), not (blob vs symlink); * Clarify permission mode bits; * Clarify ce_namelen() "too long to fit in the length field" case; * Clarify "." etc are forbidden as path components; * Match the description with the internal wording "cache-tree"; * All types of extension begin with signature and length as explained in the first part. Don't repeat the "length" part in the description of each extension (can be mistaken as if there is a separate 32-bit size field inside the extension), but state what the signature for each extension is. * Don't say "Extension tag", as we have said "Extension signature" in the first part---be consistent; * Clarify the invalidation of cache-tree entries; * Correct description on subtree_nr field in the cache-tree; * Clarify the order of entries in cache-tree; Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-02-27doc: technical details about the index file formatLibravatar Nguyễn Thái Ngọc Duy1-0/+165
This bases on the original work by Robin Rosenberg. Signed-off-by: Robin Rosenberg <robin.rosenberg@dewire.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-01-04Fix typos in the documentationLibravatar Ralf Wildenhues1-1/+1
Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-24Merge branch 'rs/opt-help-text'Libravatar Junio C Hamano1-3/+6
* rs/opt-help-text: verify-tag: document --verbose branch: improve --verbose description archive: improve --verbose description Describe various forms of "be quiet" using OPT__QUIET add OPT__FORCE add description parameter to OPT__QUIET add description parameter to OPT__DRY_RUN add description parameter to OPT__VERBOSE
2010-11-17Merge branch 'maint'Libravatar Junio C Hamano1-0/+41
* maint: clean: remove redundant variable baselen Documentation/git-pull: clarify configuration Document that rev-list --graph triggers parent rewriting. clean: avoid quoting twice document sigchain api Keep together options controlling the behaviour of diffcore-rename. t3402: test "rebase -s<strategy> -X<opt>"
2010-11-16document sigchain apiLibravatar Jeff King1-0/+41
It's pretty straightforward, but a stripped-down example never hurts. And we should make clear that it is explicitly OK to use SIG_DFL and SIG_IGN. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-15add OPT__FORCELibravatar René Scharfe1-0/+3
Add OPT__FORCE as a helper macro in the same spirit as OPT__VERBOSE et.al. to simplify defining -f/--force options. Signed-off-by: Rene Scharfe <rene.scharfe@lstfire.ath.cx> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-15add description parameter to OPT__QUIETLibravatar René Scharfe1-1/+1
Allows better help text to be defined than "be quiet". Also make use of the macro in a place that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-15add description parameter to OPT__DRY_RUNLibravatar René Scharfe1-1/+1
Allows better help text to be defined than "dry run". Also make use of the macro in places that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-15add description parameter to OPT__VERBOSELibravatar René Scharfe1-1/+1
Allows better help text to be defined than "be verbose". Also make use of the macro in places that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-26Merge branch 'jf/merge-ignore-ws'Libravatar Junio C Hamano1-20/+51
* jf/merge-ignore-ws: merge-recursive: options to ignore whitespace changes merge-recursive --patience ll-merge: replace flag argument with options struct merge-recursive: expose merge options for builtin merge