diff options
Diffstat (limited to 'Documentation')
34 files changed, 936 insertions, 389 deletions
diff --git a/Documentation/RelNotes/2.6.0.txt b/Documentation/RelNotes/2.6.0.txt new file mode 100644 index 0000000000..eb79a1815d --- /dev/null +++ b/Documentation/RelNotes/2.6.0.txt @@ -0,0 +1,351 @@ +Git 2.6 Release Notes +===================== + +Updates since v2.5 +------------------ + +UI, Workflows & Features + + * An asterisk as a substring (as opposed to the entirety) of a path + component for both side of a refspec, e.g. + "refs/heads/o*:refs/remotes/heads/i*", is now allowed. + + * New userdiff pattern definition for fountain screenwriting markup + format has been added. + + * "git log" and friends learned a new "--date=format:..." option to + format timestamps using system's strftime(3). + + * "git fast-import" learned to respond to the get-mark command via + its cat-blob-fd interface. + + * "git rebase -i" learned "drop commit-object-name subject" command + as another way to skip replaying of a commit. + + * A new configuration variable can enable "--follow" automatically + when "git log" is run with one pathspec argument. + + * "git status" learned to show a more detailed information regarding + the "rebase -i" session in progress. + + * "git cat-file" learned "--batch-all-objects" option to enumerate all + available objects in the repository more quickly than "rev-list + --all --objects" (the output includes unreachable objects, though). + + * "git fsck" learned to ignore errors on a set of known-to-be-bad + objects, and also allows the warning levels of various kinds of + non-critical breakages to be tweaked. + + * "git rebase -i"'s list of todo is made configurable. + + * "git send-email" now performs alias-expansion on names that are + given via --cccmd, etc. + + * An environment variable GIT_REPLACE_REF_BASE tells Git to look into + refs hierarchy other than refs/replace/ for the object replacement + data. + + * Allow untracked cache (experimental) to be used when sparse + checkout (experimental) is also in use. + + * "git pull --rebase" has been taught to pay attention to + rebase.autostash configuration. + + * The command-line completion script (in contrib/) has been updated. + + * A negative !ref entry in multi-value transfer.hideRefs + configuration can be used to say "don't hide this one". + + * After "git am" without "-3" stops, running "git am -" pays attention + to "-3" only for the patch that caused the original invocation + to stop. + + * When linked worktree is used, simultaneous "notes merge" instances + for the same ref in refs/notes/* are prevented from stomping on + each other. + + * "git send-email" learned a new option --smtp-auth to limit the SMTP + AUTH mechanisms to be used to a subset of what the system library + supports. + + * A new configuration variable http.sslVersion can be used to specify + what specific version of SSL/TLS to use to make a connection. + + * "git notes merge" can be told with "--strategy=<how>" option how to + automatically handle conflicts; this can now be configured by + setting notes.mergeStrategy configuration variable. + + * "git log --cc" did not show any patch, even though most of the time + the user meant "git log --cc -p -m" to see patch output for commits + with a single parent, and combined diff for merge commits. The + command is taught to DWIM "--cc" (without "--raw" and other forms + of output specification) to "--cc -p -m". + + * "git config --list" output was hard to parse when values consist of + multiple lines. "--name-only" option is added to help this. + + +Performance, Internal Implementation, Development Support etc. + + * In preparation for allowing different "backends" to store the refs + in a way different from the traditional "one ref per file in + $GIT_DIR or in a $GIT_DIR/packed-refs file" filesystem storage, + direct filesystem access to ref-like things like CHERRY_PICK_HEAD + from scripts and programs has been reduced. + + * Computation of untracked status indicator by bash prompt + script (in contrib/) has been optimized. + + * Memory use reduction when commit-slab facility is used to annotate + sparsely (which is not recommended in the first place). + + * Clean up refs API and make "git clone" less intimate with the + implementation detail. + + * "git pull" was reimplemented in C. + + * The packet tracing machinery allows to capture an incoming pack + data to a file for debugging. + + * Move machinery to parse human-readable scaled numbers like 1k, 4M, + and 2G as an option parameter's value from pack-objects to + parse-options API, to make it available to other codepaths. + + * "git verify-tag" and "git verify-commit" have been taught to share + more code, and then learned to optionally show the verification + message from the underlying GPG implementation. + + * Various enhancements around "git am" reading patches generated by + foreign SCM have been made. + + * Ref listing by "git branch -l" and "git tag -l" commands has + started to be rebuilt, based on the for-each-ref machinery. + + * The code to perform multi-tree merges has been taught to repopulate + the cache-tree upon a successful merge into the index, so that + subsequent "diff-index --cached" (hence "status") and "write-tree" + (hence "commit") will go faster. + + The same logic in "git checkout" may now be removed, but that is a + separate issue. + + * Tests that assume how reflogs are represented on the filesystem too + much have been corrected. + + * "git am" has been rewritten in "C". + + * git_path() and mkpath() are handy helper functions but it is easy + to misuse, as the callers need to be careful to keep the number of + active results below 4. Their uses have been reduced. + + * The "lockfile" API has been rebuilt on top of a new "tempfile" API. + + * To prepare for allowing a different "ref" backend to be plugged in + to the system, update_ref()/delete_ref() have been taught about + ref-like things like MERGE_HEAD that are per-worktree (they will + always be written to the filesystem inside $GIT_DIR). + + * The gitmodules API that is accessed from the C code learned to + cache stuff lazily. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.5 +---------------- + +Unless otherwise noted, all the fixes since v2.5 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git subtree" (in contrib/) depended on "git log" output to be + stable, which was a no-no. Apply a workaround to force a + particular date format. + (merge e7aac44 da/subtree-date-confusion later to maint). + + * An attempt to delete a ref by pushing into a repository whose HEAD + symbolic reference points at an unborn branch that cannot be + created due to ref D/F conflict (e.g. refs/heads/a/b exists, HEAD + points at refs/heads/a) failed. + (merge b112b14 jx/do-not-crash-receive-pack-wo-head later to maint). + + * The low-level "git send-pack" did not honor 'user.signingkey' + configuration variable when sending a signed-push. + (merge d830d39 db/send-pack-user-signingkey later to maint). + + * "sparse checkout" misbehaved for a path that is excluded from the + checkout when switching between branches that differ at the path. + (merge 7d78241 as/sparse-checkout-removal later to maint). + + * An experimental "untracked cache" feature used uname(2) in a + slightly unportable way. + (merge 100e433 cb/uname-in-untracked later to maint). + + * A "rebase" replays changes of the local branch on top of something + else, as such they are placed in stage #3 and referred to as + "theirs", while the changes in the new base, typically a foreign + work, are placed in stage #2 and referred to as "ours". Clarify + the "checkout --ours/--theirs". + (merge f303016 se/doc-checkout-ours-theirs later to maint). + + * The "rev-parse --parseopt" mode parsed the option specification + and the argument hint in a strange way to allow '=' and other + special characters in the option name while forbidding them from + the argument hint. This made it impossible to define an option + like "--pair <key>=<value>" with "pair=key=value" specification, + which instead would have defined a "--pair=key <value>" option. + (merge 2d893df ib/scripted-parse-opt-better-hint-string later to maint). + + * Often a fast-import stream builds a new commit on top of the + previous commit it built, and it often unconditionally emits a + "from" command to specify the first parent, which can be omitted in + such a case. This caused fast-import to forget the tree of the + previous commit and then re-read it from scratch, which was + inefficient. Optimize for this common case. + (merge 0df3245 mh/fast-import-optimize-current-from later to maint). + + * Running an aliased command from a subdirectory when the .git thing + in the working tree is a gitfile pointing elsewhere did not work. + (merge d95138e nd/export-worktree later to maint). + + * "Is this subdirectory a separate repository that should not be + touched?" check "git clean" was inefficient. This was replaced + with a more optimized check. + (merge fbf2fec ee/clean-remove-dirs later to maint). + + * The "new-worktree-mode" hack in "checkout" that was added in + nd/multiple-work-trees topic has been removed by updating the + implementation of new "worktree add". + (merge 65f9b75 es/worktree-add-cleanup later to maint). + + * Remove remaining cruft from "git checkout --to", which + transitioned to "git worktree add". + (merge 114ff88 es/worktree-add later to maint). + + * An off-by-one error made "git remote" to mishandle a remote with a + single letter nickname. + (merge bc598c3 mh/get-remote-group-fix later to maint). + + * "git clone $URL", when cloning from a site whose sole purpose is to + host a single repository (hence, no path after <scheme>://<site>/), + tried to use the site name as the new repository name, but did not + remove username or password when <site> part was of the form + <user>@<pass>:<host>. The code is taught to redact these. + (merge adef956 ps/guess-repo-name-at-root later to maint). + + * Running tests with the "-x" option to make them verbose had some + unpleasant interactions with other features of the test suite. + (merge 9b5fe78 jk/test-with-x later to maint). + + * t1509 test that requires a dedicated VM environment had some + bitrot, which has been corrected. + (merge faacc5a ps/t1509-chroot-test-fixup later to maint). + + * "git pull" in recent releases of Git has a regression in the code + that allows custom path to the --upload-pack=<program>. This has + been corrected. + + Note that this is irrelevant for 'master' with "git pull" rewritten + in C. + (merge 13e0e28 mm/pull-upload-pack later to maint). + + * When trying to see that an object does not exist, a state errno + leaked from our "first try to open a packfile with O_NOATIME and + then if it fails retry without it" logic on a system that refuses + O_NOATIME. This confused us and caused us to die, saying that the + packfile is unreadable, when we should have just reported that the + object does not exist in that packfile to the caller. + (merge dff6f28 cb/open-noatime-clear-errno later to maint). + + * The codepath to produce error messages had a hard-coded limit to + the size of the message, primarily to avoid memory allocation while + calling die(). + (merge f4c3edc jk/long-error-messages later to maint). + + * strbuf_read() used to have one extra iteration (and an unnecessary + strbuf_grow() of 8kB), which was eliminated. + (merge 3ebbd00 jh/strbuf-read-use-read-in-full later to maint). + + * We rewrote one of the build scripts in Perl but this reimplements + in Bourne shell. + (merge 82aec45 sg/help-group later to maint). + + * The experimental untracked-cache feature were buggy when paths with + a few levels of subdirectories are involved. + (merge 73f9145 dt/untracked-subdir later to maint). + + * "interpret-trailers" helper mistook a single-liner log message that + has a colon as the end of existing trailer. + + * The "interpret-trailers" helper mistook a multi-paragraph title of + a commit log message with a colon in it as the end of the trailer + block. + (merge 5c99995 cc/trailers-corner-case-fix later to maint). + + * "git describe" without argument defaulted to describe the HEAD + commit, but "git describe --contains" didn't. Arguably, in a + repository used for active development, such defaulting would not + be very useful as the tip of branch is typically not tagged, but it + is better to be consistent. + (merge 2bd0706 sg/describe-contains later to maint). + + * The client side codepaths in "git push" have been cleaned up + and the user can request to perform an optional "signed push", + i.e. sign only when the other end accepts signed push. + (merge 68c757f db/push-sign-if-asked later to maint). + + * Because the configuration system does not allow "alias.0foo" and + "pager.0foo" as the configuration key, the user cannot use '0foo' + as a custom command name anyway, but "git 0foo" tried to look these + keys up and emitted useless warnings before saying '0foo is not a + git command'. These warning messages have been squelched. + (merge 9e9de18 jk/fix-alias-pager-config-key-warnings later to maint). + + * "git rev-list" does not take "--notes" option, but did not complain + when one is given. + (merge 2aea7a5 jk/rev-list-has-no-notes later to maint). + + * When re-priming the cache-tree opportunistically while committing + the in-core index as-is, we mistakenly invalidated the in-core + index too aggressively, causing the experimental split-index code + to unnecessarily rewrite the on-disk index file(s). + (merge 475a344 dt/commit-preserve-base-index-upon-opportunistic-cache-tree-update later to maint). + + * "git archive" did not use zip64 extension when creating an archive + with more than 64k entries, which nobody should need, right ;-)? + (merge 88329ca rs/archive-zip-many later to maint). + + * The code in "multiple-worktree" support that attempted to recover + from an inconsistent state updated an incorrect file. + (merge 82fde87 nd/fixup-linked-gitdir later to maint). + + * On case insensitive systems, "git p4" did not work well with client + specs. + + * "git init empty && git -C empty log" said "bad default revision 'HEAD'", + which was found to be a bit confusing to new users. + (merge ce11360 jk/log-missing-default-HEAD later to maint). + + * Code cleanups and documentation updates. + (merge 1c601af es/doc-clean-outdated-tools later to maint). + (merge 3581304 kn/tag-doc-fix later to maint). + (merge 3a59e59 kb/i18n-doc later to maint). + (merge 45abdee sb/remove-unused-var-from-builtin-add later to maint). + (merge 14691e3 sb/parse-options-codeformat later to maint). + (merge 4a6ada3 ad/bisect-cleanup later to maint). + (merge da4c5ad ta/docfix-index-format-tech later to maint). + (merge ae25fd3 sb/check-return-from-read-ref later to maint). + (merge b3325df nd/dwim-wildcards-as-pathspecs later to maint). + (merge 7aa9b9b sg/wt-status-header-inclusion later to maint). + (merge f04c690 as/docfix-reflog-expire-unreachable later to maint). + (merge 1269847 sg/t3020-typofix later to maint). + (merge 8b54c23 jc/calloc-pathspec later to maint). + (merge a6926b8 po/po-readme later to maint). + (merge 54d160e ss/fix-config-fd-leak later to maint). + (merge b80fa84 ah/submodule-typofix-in-error later to maint). + (merge 99885bc ah/reflog-typofix-in-error later to maint). + (merge 9476c2c ah/read-tree-usage-string later to maint). + (merge b8c1d27 ah/pack-objects-usage-strings later to maint). + (merge 486e1e1 br/svn-doc-include-paths-config later to maint). + (merge 1733ed3 ee/clean-test-fixes later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index a65cdd43c2..0c351b9bcf 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -769,6 +769,14 @@ am.keepcr:: by giving '--no-keep-cr' from the command line. See linkgit:git-am[1], linkgit:git-mailsplit[1]. +am.threeWay:: + By default, `git am` will fail if the patch does not apply cleanly. When + set to true, this setting tells `git am` to fall back on 3-way merge if + the patch records the identity of blobs it is supposed to apply to and + we have those blobs available locally (equivalent to giving the `--3way` + option from the command line). Defaults to `false`. + See linkgit:git-am[1]. + apply.ignoreWhitespace:: When set to 'change', tells 'git apply' to ignore changes in whitespace, in the same way as the '--ignore-space-change' @@ -1242,6 +1250,25 @@ filter.<driver>.smudge:: object to a worktree file upon checkout. See linkgit:gitattributes[5] for details. +fsck.<msg-id>:: + Allows overriding the message type (error, warn or ignore) of a + specific message ID such as `missingEmail`. ++ +For convenience, fsck prefixes the error/warning with the message ID, +e.g. "missingEmail: invalid author/committer line - missing email" means +that setting `fsck.missingEmail = ignore` will hide that issue. ++ +This feature is intended to support working with legacy repositories +which cannot be repaired without disruptive changes. + +fsck.skipList:: + The path to a sorted list of object names (i.e. one SHA-1 per + line) that are known to be broken in a non-fatal way and should + be ignored. This feature is useful when an established project + should be accepted despite early commits containing errors that + can be safely ignored such as invalid committer email addresses. + Note: corrupt objects cannot be skipped with this setting. + gc.aggressiveDepth:: The depth parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults @@ -1280,20 +1307,24 @@ gc.packRefs:: gc.pruneExpire:: When 'git gc' is run, it will call 'prune --expire 2.weeks.ago'. Override the grace period with this config variable. The value - "now" may be used to disable this grace period and always prune - unreachable objects immediately. - -gc.pruneWorktreesExpire:: - When 'git gc' is run, it will call - 'prune --worktrees --expire 3.months.ago'. - Override the grace period with this config variable. The value - "now" may be used to disable the grace period and prune - $GIT_DIR/worktrees immediately. + "now" may be used to disable this grace period and always prune + unreachable objects immediately, or "never" may be used to + suppress pruning. + +gc.worktreePruneExpire:: + When 'git gc' is run, it calls + 'git worktree prune --expire 3.months.ago'. + This config variable can be used to set a different grace + period. The value "now" may be used to disable the grace + period and prune $GIT_DIR/worktrees immediately, or "never" + may be used to suppress pruning. gc.reflogExpire:: gc.<pattern>.reflogExpire:: 'git reflog expire' removes reflog entries older than - this time; defaults to 90 days. With "<pattern>" (e.g. + this time; defaults to 90 days. The value "now" expires all + entries immediately, and "never" suppresses expiration + altogether. With "<pattern>" (e.g. "refs/stash") in the middle the setting applies only to the refs that match the <pattern>. @@ -1301,7 +1332,9 @@ gc.reflogExpireUnreachable:: gc.<pattern>.reflogExpireUnreachable:: 'git reflog expire' removes reflog entries older than this time and are not reachable from the current tip; - defaults to 30 days. With "<pattern>" (e.g. "refs/stash") + defaults to 30 days. The value "now" expires all entries + immediately, and "never" suppresses expiration altogether. + With "<pattern>" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the <pattern>. @@ -1576,6 +1609,29 @@ http.saveCookies:: If set, store cookies received during requests to the file specified by http.cookieFile. Has no effect if http.cookieFile is unset. +http.sslVersion:: + The SSL version to use when negotiating an SSL connection, if you + want to force the default. The available and default version + depend on whether libcurl was built against NSS or OpenSSL and the + particular configuration of the crypto library in use. Internally + this sets the 'CURLOPT_SSL_VERSION' option; see the libcurl + documentation for more details on the format of this option and + for the ssl version supported. Actually the possible values of + this option are: + + - sslv2 + - sslv3 + - tlsv1 + - tlsv1.0 + - tlsv1.1 + - tlsv1.2 + ++ +Can be overridden by the 'GIT_SSL_VERSION' environment variable. +To force git to use libcurl's default ssl version and ignore any +explicit http.sslversion option, set 'GIT_SSL_VERSION' to the +empty string. + http.sslCipherList:: A list of SSL ciphers to use when negotiating an SSL connection. The available ciphers depend on whether libcurl was built against @@ -1886,6 +1942,18 @@ mergetool.writeToTemp:: mergetool.prompt:: Prompt before each invocation of the merge resolution program. +notes.mergeStrategy:: + Which merge strategy to choose by default when resolving notes + conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or + `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" + section of linkgit:git-notes[1] for more information on each strategy. + +notes.<name>.mergeStrategy:: + Which merge strategy to choose when doing a notes merge into + refs/notes/<name>. This overrides the more general + "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in + linkgit:git-notes[1] for more information on the available strategies. + notes.displayRef:: The (fully qualified) refname from which to show notes when showing commit messages. The value of this variable can be set @@ -1914,8 +1982,8 @@ notes.rewriteMode:: When copying notes during a rewrite (see the "notes.rewrite.<command>" option), determines what to do if the target commit already has a note. Must be one of - `overwrite`, `concatenate`, or `ignore`. Defaults to - `concatenate`. + `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. + Defaults to `concatenate`. + This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` environment variable. @@ -2145,6 +2213,14 @@ push.followTags:: may override this configuration at time of push by specifying '--no-follow-tags'. +push.gpgSign:: + May be set to a boolean value, or the string 'if-asked'. A true + value causes all pushes to be GPG signed, as if '--signed' is + passed to linkgit:git-push[1]. The string 'if-asked' causes + pushes to be signed if the server supports it, as if + '--signed=if-asked' is passed to 'git push'. A false value may + override a value from a lower-priority config file. An explicit + command-line flag always overrides this config option. rebase.stat:: Whether to show a diffstat of what changed upstream since the last @@ -2161,6 +2237,22 @@ rebase.autoStash:: successful rebase might result in non-trivial conflicts. Defaults to false. +rebase.missingCommitsCheck:: + If set to "warn", git rebase -i will print a warning if some + commits are removed (e.g. a line was deleted), however the + rebase will still proceed. If set to "error", it will print + the previous warning and stop the rebase, 'git rebase + --edit-todo' can then be used to correct the error. If set to + "ignore", no checking is done. + To drop a commit without warning or error, use the `drop` + command in the todo-list. + Defaults to "ignore". + +rebase.instructionFormat + A format string, as specified in linkgit:git-log[1], to be used for + the instruction list during an interactive rebase. The format will automatically + have the long commit hash prepended to the format. + receive.advertiseAtomic:: By default, git-receive-pack will advertise the atomic push capability to its clients. If you don't want to this capability @@ -2197,6 +2289,28 @@ receive.fsckObjects:: Defaults to false. If not set, the value of `transfer.fsckObjects` is used instead. +receive.fsck.<msg-id>:: + When `receive.fsckObjects` is set to true, errors can be switched + to warnings and vice versa by configuring the `receive.fsck.<msg-id>` + setting where the `<msg-id>` is the fsck message ID and the value + is one of `error`, `warn` or `ignore`. For convenience, fsck prefixes + the error/warning with the message ID, e.g. "missingEmail: invalid + author/committer line - missing email" means that setting + `receive.fsck.missingEmail = ignore` will hide that issue. ++ +This feature is intended to support working with legacy repositories +which would not pass pushing when `receive.fsckObjects = true`, allowing +the host to accept repositories with certain known issues but still catch +other issues. + +receive.fsck.skipList:: + The path to a sorted list of object names (i.e. one SHA-1 per + line) that are known to be broken in a non-fatal way and should + be ignored. This feature is useful when an established project + should be accepted despite early commits containing errors that + can be safely ignored such as invalid committer email addresses. + Note: corrupt objects cannot be skipped with this setting. + receive.unpackLimit:: If the number of objects received in a push is below this limit then the objects will be unpacked into loose object @@ -2242,13 +2356,10 @@ receive.denyNonFastForwards:: set when initializing a shared repository. receive.hideRefs:: - String(s) `receive-pack` uses to decide which refs to omit - from its initial advertisement. Use more than one - definitions to specify multiple prefix strings. A ref that - are under the hierarchies listed on the value of this - variable is excluded, and is hidden when responding to `git - push`, and an attempt to update or delete a hidden ref by - `git push` is rejected. + This variable is the same as `transfer.hideRefs`, but applies + only to `receive-pack` (and so affects pushes, but not fetches). + An attempt to update or delete a hidden ref by `git push` is + rejected. receive.updateServerInfo:: If set to true, git-receive-pack will run git-update-server-info @@ -2536,9 +2647,18 @@ transfer.fsckObjects:: Defaults to false. transfer.hideRefs:: - This variable can be used to set both `receive.hideRefs` - and `uploadpack.hideRefs` at the same time to the same - values. See entries for these other variables. + String(s) `receive-pack` and `upload-pack` use to decide which + refs to omit from their initial advertisements. Use more than + one definition to specify multiple prefix strings. A ref that is + under the hierarchies listed in the value of this variable is + excluded, and is hidden when responding to `git push` or `git + fetch`. See `receive.hideRefs` and `uploadpack.hideRefs` for + program-specific versions of this config. ++ +You may also include a `!` in front of the ref name to negate the entry, +explicitly exposing it, even if an earlier entry marked it as hidden. +If you have multiple hideRefs values, later entries override earlier ones +(and entries in more-specific config files override less-specific ones). transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are @@ -2553,13 +2673,10 @@ uploadarchive.allowUnreachable:: `false`. uploadpack.hideRefs:: - String(s) `upload-pack` uses to decide which refs to omit - from its initial advertisement. Use more than one - definitions to specify multiple prefix strings. A ref that - are under the hierarchies listed on the value of this - variable is excluded, and is hidden from `git ls-remote`, - `git fetch`, etc. An attempt to fetch a hidden ref by `git - fetch` will fail. See also `uploadpack.allowTipSHA1InWant`. + This variable is the same as `transfer.hideRefs`, but applies + only to `upload-pack` (and so affects only fetches, not pushes). + An attempt to fetch a hidden ref by `git fetch` will fail. See + also `uploadpack.allowTipSHA1InWant`. uploadpack.allowTipSHA1InWant:: When `uploadpack.hideRefs` is in effect, allow `upload-pack` diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 0d8ba48f79..dbea6e7ae9 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] - [--3way] [--interactive] [--committer-date-is-author-date] + [--[no-]3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] @@ -90,10 +90,13 @@ default. You can use `--no-utf8` to override this. -3:: --3way:: +--no-3way:: When the patch does not apply cleanly, fall back on 3-way merge if the patch records the identity of blobs it is supposed to apply to and we have those blobs - available locally. + available locally. `--no-3way` can be used to override + am.threeWay configuration variable. For more information, + see am.threeWay in linkgit:git-config[1]. --ignore-space-change:: --ignore-whitespace:: diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 4cb52a7302..e97f2de21b 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -3,7 +3,7 @@ git-bisect(1) NAME ---- -git-bisect - Find by binary search the change that introduced a bug +git-bisect - Use binary search to find the commit that introduced a bug SYNOPSIS @@ -16,7 +16,6 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: - git bisect help git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] git bisect bad [<rev>] git bisect good [<rev>...] @@ -26,64 +25,71 @@ on the subcommand: git bisect replay <logfile> git bisect log git bisect run <cmd>... + git bisect help -This command uses 'git rev-list --bisect' to help drive the -binary search process to find which change introduced a bug, given an -old "good" commit object name and a later "bad" commit object name. - -Getting help -~~~~~~~~~~~~ - -Use "git bisect" to get a short usage description, and "git bisect -help" or "git bisect -h" to get a long usage description. +This command uses a binary search algorithm to find which commit in +your project's history introduced a bug. You use it by first telling +it a "bad" commit that is known to contain the bug, and a "good" +commit that is known to be before the bug was introduced. Then `git +bisect` picks a commit between those two endpoints and asks you +whether the selected commit is "good" or "bad". It continues narrowing +down the range until it finds the exact commit that introduced the +change. Basic bisect commands: start, bad, good ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Using the Linux kernel tree as an example, basic use of the bisect -command is as follows: +As an example, suppose you are trying to find the commit that broke a +feature that was known to work in version `v2.6.13-rc2` of your +project. You start a bisect session as follows: ------------------------------------------------ $ git bisect start $ git bisect bad # Current version is bad -$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version - # tested that was good +$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 is known to be good ------------------------------------------------ -When you have specified at least one bad and one good version, the -command bisects the revision tree and outputs something similar to -the following: +Once you have specified at least one bad and one good commit, `git +bisect` selects a commit in the middle of that range of history, +checks it out, and outputs something similar to the following: ------------------------------------------------ -Bisecting: 675 revisions left to test after this +Bisecting: 675 revisions left to test after this (roughly 10 steps) ------------------------------------------------ -The state in the middle of the set of revisions is then checked out. -You would now compile that kernel and boot it. If the booted kernel -works correctly, you would then issue the following command: +You should now compile the checked-out version and test it. If that +version works correctly, type ------------------------------------------------ -$ git bisect good # this one is good +$ git bisect good ------------------------------------------------ -The output of this command would be something similar to the following: +If that version is broken, type ------------------------------------------------ -Bisecting: 337 revisions left to test after this +$ git bisect bad ------------------------------------------------ -You keep repeating this process, compiling the tree, testing it, and -depending on whether it is good or bad issuing the command "git bisect good" -or "git bisect bad" to ask for the next bisection. +Then `git bisect` will respond with something like + +------------------------------------------------ +Bisecting: 337 revisions left to test after this (roughly 9 steps) +------------------------------------------------ + +Keep repeating the process: compile the tree, test it, and depending +on whether it is good or bad run `git bisect good` or `git bisect bad` +to ask for the next commit that needs testing. + +Eventually there will be no more revisions left to inspect, and the +command will print out a description of the first bad commit. The +reference `refs/bisect/bad` will be left pointing at that commit. -Eventually there will be no more revisions left to bisect, and you -will have been left with the first bad kernel revision in "refs/bisect/bad". Bisect reset ~~~~~~~~~~~~ After a bisect session, to clean up the bisection state and return to -the original HEAD (i.e., to quit bisecting), issue the following command: +the original HEAD, issue the following command: ------------------------------------------------ $ git bisect reset @@ -100,9 +106,10 @@ instead: $ git bisect reset <commit> ------------------------------------------------ -For example, `git bisect reset HEAD` will leave you on the current -bisection commit and avoid switching commits at all, while `git bisect -reset bisect/bad` will check out the first bad revision. +For example, `git bisect reset bisect/bad` will check out the first +bad revision, while `git bisect reset HEAD` will leave you on the +current bisection commit and avoid switching commits at all. + Bisect visualize ~~~~~~~~~~~~~~~~ @@ -147,17 +154,17 @@ $ git bisect replay that-file Avoiding testing a commit ~~~~~~~~~~~~~~~~~~~~~~~~~ -If, in the middle of a bisect session, you know that the next suggested -revision is not a good one to test (e.g. the change the commit -introduces is known not to work in your environment and you know it -does not have anything to do with the bug you are chasing), you may -want to find a nearby commit and try that instead. +If, in the middle of a bisect session, you know that the suggested +revision is not a good one to test (e.g. it fails to build and you +know that the failure does not have anything to do with the bug you +are chasing), you can manually select a nearby commit and test that +one instead. For example: ------------ $ git bisect good/bad # previous round was good or bad. -Bisecting: 337 revisions left to test after this +Bisecting: 337 revisions left to test after this (roughly 9 steps) $ git bisect visualize # oops, that is uninteresting. $ git reset --hard HEAD~3 # try 3 revisions before what # was suggested @@ -169,18 +176,19 @@ the revision as good or bad in the usual manner. Bisect skip ~~~~~~~~~~~~ -Instead of choosing by yourself a nearby commit, you can ask Git -to do it for you by issuing the command: +Instead of choosing a nearby commit by yourself, you can ask Git to do +it for you by issuing the command: ------------ $ git bisect skip # Current version cannot be tested ------------ -But Git may eventually be unable to tell the first bad commit among -a bad commit and one or more skipped commits. +However, if you skip a commit adjacent to the one you are looking for, +Git will be unable to tell exactly which of those commits was the +first bad one. -You can even skip a range of commits, instead of just one commit, -using the "'<commit1>'..'<commit2>'" notation. For example: +You can also skip a range of commits, instead of just one commit, +using range notation. For example: ------------ $ git bisect skip v2.5..v2.6 @@ -196,8 +204,8 @@ would issue the command: $ git bisect skip v2.5 v2.5..v2.6 ------------ -This tells the bisect process that the commits between `v2.5` included -and `v2.6` included should be skipped. +This tells the bisect process that the commits between `v2.5` and +`v2.6` (inclusive) should be skipped. Cutting down bisection by giving more parameters to bisect start @@ -231,14 +239,14 @@ or bad, you can bisect by issuing the command: $ git bisect run my_script arguments ------------ -Note that the script (`my_script` in the above example) should -exit with code 0 if the current source code is good, and exit with a -code between 1 and 127 (inclusive), except 125, if the current -source code is bad. +Note that the script (`my_script` in the above example) should exit +with code 0 if the current source code is good/old, and exit with a +code between 1 and 127 (inclusive), except 125, if the current source +code is bad/new. Any other exit code will abort the bisect process. It should be noted -that a program that terminates via "exit(-1)" leaves $? = 255, (see the -exit(3) manual page), as the value is chopped with "& 0377". +that a program that terminates via `exit(-1)` leaves $? = 255, (see the +exit(3) manual page), as the value is chopped with `& 0377`. The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current @@ -247,7 +255,7 @@ as the highest sensible value to use for this purpose, because 126 and 127 are used by POSIX shells to signal specific error status (127 is for command not found, 126 is for command found but not executable---these details do not matter, as they are normal errors in the script, as far as -"bisect run" is concerned). +`bisect run` is concerned). You may often find that during a bisect session you want to have temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a @@ -260,7 +268,7 @@ next revision to test, the script can apply the patch before compiling, run the real test, and afterwards decide if the revision (possibly with the needed patch) passed the test and then rewind the tree to the pristine state. Finally the script should exit -with the status of the real test to let the "git bisect run" command loop +with the status of the real test to let the `git bisect run` command loop determine the eventual outcome of the bisect session. OPTIONS @@ -307,12 +315,12 @@ $ git bisect run ~/test.sh $ git bisect reset # quit the bisect session ------------ + -Here we use a "test.sh" custom script. In this script, if "make" +Here we use a `test.sh` custom script. In this script, if `make` fails, we skip the current commit. -"check_test_case.sh" should "exit 0" if the test case passes, -and "exit 1" otherwise. +`check_test_case.sh` should `exit 0` if the test case passes, +and `exit 1` otherwise. + -It is safer if both "test.sh" and "check_test_case.sh" are +It is safer if both `test.sh` and `check_test_case.sh` are outside the repository to prevent interactions between the bisect, make and test processes and the scripts. @@ -379,6 +387,11 @@ In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit has at least one parent whose reachable graph is fully traversable in the sense required by 'git pack objects'. +Getting help +~~~~~~~~~~~~ + +Use `git bisect` to get a short usage description, and `git bisect +help` or `git bisect -h` to get a long usage description. SEE ALSO -------- diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 319ab4cb08..3105fc0720 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -69,6 +69,20 @@ OPTIONS not be combined with any other options or arguments. See the section `BATCH OUTPUT` below for details. +--batch-all-objects:: + Instead of reading a list of objects on stdin, perform the + requested batch operation on all objects in the repository and + any alternate object stores (not just reachable objects). + Requires `--batch` or `--batch-check` be specified. Note that + the objects are visited in order sorted by their hashes. + +--buffer:: + Normally batch output is flushed after each object is output, so + that a process can interactively read and write from + `cat-file`. With this option, the output uses normal stdio + buffering; this is much more efficient when invoking + `--batch-check` on a large number of objects. + --allow-unknown-type:: Allow -s or -t to query broken/corrupt objects of unknown type. diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index fc02959ba4..9044dfaada 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -94,8 +94,8 @@ OPTIONS Interpret <refname> as a reference name pattern for a refspec (as used with remote repositories). If this option is enabled, <refname> is allowed to contain a single `*` - in place of a one full pathname component (e.g., - `foo/*/bar` but not `foo/bar*`). + in the refspec (e.g., `foo/bar*/baz` or `foo/bar*baz/` + but not `foo/bar*/baz*`). --normalize:: Normalize 'refname' by removing any leading slash (`/`) diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 02ec096faa..2608ca74ac 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -14,13 +14,13 @@ SYNOPSIS 'git config' [<file-option>] [type] --replace-all name value [value_regex] 'git config' [<file-option>] [type] [-z|--null] --get name [value_regex] 'git config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] -'git config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [type] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] 'git config' [<file-option>] [type] [-z|--null] --get-urlmatch name URL 'git config' [<file-option>] --unset name [value_regex] 'git config' [<file-option>] --unset-all name [value_regex] 'git config' [<file-option>] --rename-section old_name new_name 'git config' [<file-option>] --remove-section name -'git config' [<file-option>] [-z|--null] -l | --list +'git config' [<file-option>] [-z|--null] [--name-only] -l | --list 'git config' [<file-option>] --get-color name [default] 'git config' [<file-option>] --get-colorbool name [stdout-is-tty] 'git config' [<file-option>] -e | --edit @@ -159,7 +159,7 @@ See also <<FILES>>. -l:: --list:: - List all variables set in config file. + List all variables set in config file, along with their values. --bool:: 'git config' will ensure that the output is "true" or "false" @@ -190,6 +190,10 @@ See also <<FILES>>. output without getting confused e.g. by values that contain line breaks. +--name-only:: + Output only the names of config variables for `--list` or + `--get-regexp`. + --get-colorbool name [stdout-is-tty]:: Find the color setting for `name` (e.g. `color.diff`) and output diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index e045fc73f8..c8f28c8c86 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -9,7 +9,7 @@ git-describe - Describe a commit using the most recent tag reachable from it SYNOPSIS -------- [verse] -'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <commit-ish>... +'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] DESCRIPTION @@ -27,7 +27,7 @@ see the -a and -s options to linkgit:git-tag[1]. OPTIONS ------- <commit-ish>...:: - Commit-ish object names to describe. + Commit-ish object names to describe. Defaults to HEAD if omitted. --dirty[=<mark>]:: Describe the working tree. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index fd32895255..66910aa2fa 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -54,7 +54,7 @@ Options for Frontends ~~~~~~~~~~~~~~~~~~~~~ --cat-blob-fd=<fd>:: - Write responses to `cat-blob` and `ls` queries to the + Write responses to `get-mark`, `cat-blob`, and `ls` queries to the file descriptor <fd> instead of `stdout`. Allows `progress` output intended for the end-user to be separated from other output. @@ -350,6 +350,11 @@ and control the current import process. More detailed discussion unless the `done` feature was requested using the `--done` command-line option or `feature done` command. +`get-mark`:: + Causes fast-import to print the SHA-1 corresponding to a mark + to the file descriptor set with `--cat-blob-fd`, or `stdout` if + unspecified. + `cat-blob`:: Causes fast-import to print a blob in 'cat-file --batch' format to the file descriptor set with `--cat-blob-fd` or @@ -930,6 +935,25 @@ Placing a `progress` command immediately after a `checkpoint` will inform the reader when the `checkpoint` has been completed and it can safely access the refs that fast-import updated. +`get-mark` +~~~~~~~~~~ +Causes fast-import to print the SHA-1 corresponding to a mark to +stdout or to the file descriptor previously arranged with the +`--cat-blob-fd` argument. The command otherwise has no impact on the +current import; its purpose is to retrieve SHA-1s that later commits +might want to refer to in their commit messages. + +.... + 'get-mark' SP ':' <idnum> LF +.... + +This command can be used anywhere in the stream that comments are +accepted. In particular, the `get-mark` command can be used in the +middle of a commit but not in the middle of a `data` command. + +See ``Responses To Commands'' below for details about how to read +this output safely. + `cat-blob` ~~~~~~~~~~ Causes fast-import to print a blob to a file descriptor previously @@ -1000,7 +1024,8 @@ Output uses the same format as `git ls-tree <tree> -- <path>`: ==== The <dataref> represents the blob, tree, or commit object at <path> -and can be used in later 'cat-blob', 'filemodify', or 'ls' commands. +and can be used in later 'get-mark', 'cat-blob', 'filemodify', or +'ls' commands. If there is no file or subtree at that path, 'git fast-import' will instead report @@ -1042,9 +1067,11 @@ import-marks-if-exists:: "feature import-marks-if-exists" like a corresponding command-line option silently skips a nonexistent file. +get-mark:: cat-blob:: ls:: - Require that the backend support the 'cat-blob' or 'ls' command. + Require that the backend support the 'get-mark', 'cat-blob', + or 'ls' command respectively. Versions of fast-import not supporting the specified command will exit with a message indicating so. This lets the import error out early with a clear message, @@ -1124,11 +1151,11 @@ bidirectional pipes: git fast-import >fast-import-output ==== -A frontend set up this way can use `progress`, `ls`, and `cat-blob` -commands to read information from the import in progress. +A frontend set up this way can use `progress`, `get-mark`, `ls`, and +`cat-blob` commands to read information from the import in progress. To avoid deadlock, such frontends must completely consume any -pending output from `progress`, `ls`, and `cat-blob` before +pending output from `progress`, `ls`, `get-mark`, and `cat-blob` before performing writes to fast-import that might block. Crash Reports diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 25c431d3c5..84ee92e158 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] - [--[no-]dangling] [--[no-]progress] [<object>*] + [--[no-]dangling] [--[no-]progress] [--connectivity-only] [<object>*] DESCRIPTION ----------- @@ -60,6 +60,11 @@ index file, all SHA-1 references in `refs` namespace, and all reflogs object pools. This is now default; you can turn it off with --no-full. +--connectivity-only:: + Check only the connectivity of tags, commits and tree objects. By + avoiding to unpack blobs, this speeds up the operation, at the + expense of missing corrupt objects or other problematic issues. + --strict:: Enable more strict checking, namely to catch a file mode recorded with g+w bit set, which was created by older diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 5692945a0b..97b9993ee8 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -184,6 +184,12 @@ log.date:: `--date` option.) Defaults to "default", which means to write dates like `Sat May 8 19:35:34 2010 -0500`. +log.follow:: + If a single <path> is given to git log, it will act as + if the `--follow` option was also used. This has the same + limitations as `--follow`, i.e. it cannot be used to follow + multiple files and does not work well on non-linear history. + log.showRoot:: If `false`, `git log` and related commands will not treat the initial commit as a big creation event. Any root commits in diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 851518d531..a9a916f360 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -101,7 +101,7 @@ merge:: any) into the current notes ref (called "local"). + If conflicts arise and a strategy for automatically resolving -conflicting notes (see the -s/--strategy option) is not given, +conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given, the "manual" resolver is used. This resolver checks out the conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to manually resolve the conflicts there. @@ -183,6 +183,7 @@ OPTIONS When merging notes, resolve notes conflicts using the given strategy. The following strategies are recognized: "manual" (default), "ours", "theirs", "union" and "cat_sort_uniq". + This option overrides the "notes.mergeStrategy" configuration setting. See the "NOTES MERGE STRATEGIES" section below for more information on each notes merge strategy. @@ -247,6 +248,9 @@ When done, the user can either finalize the merge with 'git notes merge --commit', or abort the merge with 'git notes merge --abort'. +Users may select an automated merge strategy from among the following using +either -s/--strategy option or configuring notes.mergeStrategy accordingly: + "ours" automatically resolves conflicting notes in favor of the local version (i.e. the current notes ref). @@ -310,6 +314,20 @@ core.notesRef:: This setting can be overridden through the environment and command line. +notes.mergeStrategy:: + Which merge strategy to choose by default when resolving notes + conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or + `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" + section above for more information on each strategy. ++ +This setting can be overridden by passing the `--strategy` option. + +notes.<name>.mergeStrategy:: + Which merge strategy to choose when doing a notes merge into + refs/notes/<name>. This overrides the more general + "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above + for more information on each available strategy. + notes.displayRef:: Which ref (or refs, if a glob or specified more than once), in addition to the default set by `core.notesRef` or @@ -331,7 +349,8 @@ environment variable. notes.rewriteMode:: When copying notes during a rewrite, what to do if the target commit already has a note. Must be one of `overwrite`, - `concatenate`, and `ignore`. Defaults to `concatenate`. + `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to + `concatenate`. + This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` environment variable. @@ -368,7 +387,7 @@ does not match any refs is silently ignored. 'GIT_NOTES_REWRITE_MODE':: When copying notes during a rewrite, what to do if the target commit already has a note. - Must be one of `overwrite`, `concatenate`, and `ignore`. + Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. This overrides the `core.rewriteMode` setting. 'GIT_NOTES_REWRITE_REF':: diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 135d810b7a..1495e3416c 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -11,7 +11,8 @@ SYNOPSIS [verse] 'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] - [-u | --set-upstream] [--signed] + [-u | --set-upstream] + [--[no-]signed|--sign=(true|false|if-asked)] [--force-with-lease[=<refname>[:<expect>]]] [--no-verify] [<repository> [<refspec>...]] @@ -132,12 +133,16 @@ already exists on the remote side. with configuration variable 'push.followTags'. For more information, see 'push.followTags' in linkgit:git-config[1]. - ---signed:: +--[no-]signed:: +--sign=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be - logged. See linkgit:git-receive-pack[1] for the details - on the receiving end. + logged. If `false` or `--no-signed`, no signing will be + attempted. If `true` or `--signed`, the push will fail if the + server does not support signed pushes. If set to `if-asked`, + sign if and only if the server supports signed pushes. The push + will also fail if the actual call to `gpg --sign` fails. See + linkgit:git-receive-pack[1] for the details on the receiving end. --[no-]atomic:: Use an atomic transaction on the remote side if available. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 1d01baa5fc..ca039546a4 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -213,6 +213,15 @@ rebase.autoSquash:: rebase.autoStash:: If set to true enable '--autostash' option by default. +rebase.missingCommitsCheck:: + If set to "warn", print warnings about removed commits in + interactive mode. If set to "error", print the warnings and + stop the rebase. If set to "ignore", no checking is + done. "ignore" by default. + +rebase.instructionFormat:: + Custom commit list format to use during an '--interactive' rebase. + OPTIONS ------- --onto <newbase>:: @@ -359,6 +368,10 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. Make a list of the commits which are about to be rebased. Let the user edit that list before rebasing. This mode can also be used to split commits (see SPLITTING COMMITS below). ++ +The commit list format can be changed by setting the configuration option +rebase.instructionFormat. A customized instruction format will automatically +have the long commit hash prepended to the format. -p:: --preserve-merges:: @@ -514,6 +527,9 @@ rebasing. If you just want to edit the commit message for a commit, replace the command "pick" with the command "reword". +To drop a commit, replace the command "pick" with "drop", or just +delete the matching line. + If you want to fold two or more commits into one, replace the command "pick" for the second and subsequent commits with "squash" or "fixup". If the commits had different authors, the folded commit will be diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 5e7908e4f7..44c736f1a8 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -23,6 +23,7 @@ depending on the subcommand: [--dry-run] [--verbose] [--all | <refs>...] 'git reflog delete' [--rewrite] [--updateref] [--dry-run] [--verbose] ref@\{specifier\}... +'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches and other references were updated in the local repository. Reflogs are @@ -52,6 +53,9 @@ argument must be an _exact_ entry (e.g. "`git reflog delete master@{2}`"). This subcommand is also typically not used directly by end users. +The "exists" subcommand checks whether a ref has a reflog. It exits +with zero status if the reflog exists, and non-zero status if it does +not. OPTIONS ------- diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 7ae467ba41..b9134d234f 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -49,17 +49,17 @@ Composing of 'sendemail.annotate'. See the CONFIGURATION section for 'sendemail.multiEdit'. ---bcc=<address>:: +--bcc=<address>,...:: Specify a "Bcc:" value for each email. Default is the value of 'sendemail.bcc'. + -The --bcc option must be repeated for each user you want on the bcc list. +This option may be specified multiple times. ---cc=<address>:: +--cc=<address>,...:: Specify a starting "Cc:" value for each email. Default is the value of 'sendemail.cc'. + -The --cc option must be repeated for each user you want on the cc list. +This option may be specified multiple times. --compose:: Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) @@ -110,13 +110,13 @@ is not set, this will be prompted for. Only necessary if --compose is also set. If --compose is not set, this will be prompted for. ---to=<address>:: +--to=<address>,...:: Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the project involved. Default is the value of the 'sendemail.to' configuration value; if that is unspecified, and --to-cmd is not specified, this will be prompted for. + -The --to option must be repeated for each user you want on the to list. +This option may be specified multiple times. --8bit-encoding=<encoding>:: When encountering a non-ASCII message or subject that does not @@ -171,6 +171,19 @@ Sending to determine your FQDN automatically. Default is the value of 'sendemail.smtpDomain'. +--smtp-auth=<mechanisms>:: + Whitespace-separated list of allowed SMTP-AUTH mechanisms. This setting + forces using only the listed mechanisms. Example: ++ +------ +$ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ... +------ ++ +If at least one of the specified mechanisms matches the ones advertised by the +SMTP server and if it is supported by the utilized SASL library, the mechanism +is used for authentication. If neither 'sendemail.smtpAuth' nor '--smtp-auth' +is specified, all mechanisms supported by the SASL library can be used. + --smtp-pass[=<password>]:: Password for SMTP-AUTH. The argument is optional: If no argument is specified, then the empty string is used as diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index b5d09f79ee..6aa91e830c 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -9,7 +9,10 @@ git-send-pack - Push objects over Git protocol to another repository SYNOPSIS -------- [verse] -'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [--atomic] [<host>:]<directory> [<ref>...] +'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] + [--verbose] [--thin] [--atomic] + [--[no-]signed|--sign=(true|false|if-asked)] + [<host>:]<directory> [<ref>...] DESCRIPTION ----------- @@ -67,6 +70,17 @@ be in a separate packet, and the list must end with a flush packet. fails to update then the entire push will fail without changing any refs. +--[no-]signed:: +--sign=(true|false|if-asked):: + GPG-sign the push request to update refs on the receiving + side, to allow it to be checked by the hooks and/or be + logged. If `false` or `--no-signed`, no signing will be + attempted. If `true` or `--signed`, the push will fail if the + server does not support signed pushes. If set to `if-asked`, + sign if and only if the server supports signed pushes. The push + will also fail if the actual call to `gpg --sign` fails. See + linkgit:git-receive-pack[1] for the details on the receiving end. + <host>:: A remote host to house the repository. When this part is specified, 'git-receive-pack' is invoked via diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 11d1e2fc66..0c0f60b20e 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -174,6 +174,9 @@ Skip "branches" and "tags" of first level directories;; (including automatic fetches due to 'clone', 'dcommit', 'rebase', etc) on a given repository. '--ignore-paths' takes precedence over '--include-paths'. ++ +[verse] +config key: svn-remote.<name>.include-paths --log-window-size=<n>;; Fetch <n> log entries per request when scanning Subversion history. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 4b04c2b7d5..84f6496bf2 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -13,7 +13,7 @@ SYNOPSIS <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>] - [--column[=<options>] | --no-column] [<pattern>...] + [--column[=<options>] | --no-column] [--create-reflog] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION @@ -142,6 +142,9 @@ This option is only applicable when listing tags without annotation lines. all, 'whitespace' removes just leading/trailing whitespace lines and 'strip' removes both whitespace and commentary. +--create-reflog:: + Create a reflog for the tag. + <tagname>:: The name of the tag to create, delete, or describe. The new tag name must pass all checks defined by diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index c8f5ae5cb3..969bfab2ab 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -8,7 +8,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- [verse] -'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) +'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) DESCRIPTION ----------- @@ -67,6 +67,9 @@ performs all modifications together. Specify commands of the form: verify SP <ref> [SP <oldvalue>] LF option SP <opt> LF +With `--create-reflog`, update-ref will create a reflog for each ref +even if one would not ordinarily be created. + Quote fields containing whitespace as if they were strings in C source code; i.e., surrounded by double-quotes and with backslash escapes. Use 40 "0" characters or the empty string to specify a zero value. To diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt index 9413e2802a..ecf4da16cf 100644 --- a/Documentation/git-verify-commit.txt +++ b/Documentation/git-verify-commit.txt @@ -16,6 +16,10 @@ Validates the gpg signature created by 'git commit -S'. OPTIONS ------- +--raw:: + Print the raw gpg status output to standard error instead of the normal + human-readable output. + -v:: --verbose:: Print the contents of the commit object before validating it. diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index f88ba96f02..d590edcebd 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -16,6 +16,10 @@ Validates the gpg signature created by 'git tag'. OPTIONS ------- +--raw:: + Print the raw gpg status output to standard error instead of the normal + human-readable output. + -v:: --verbose:: Print the contents of the tag object before validating it. diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 3387e2f037..fb68156cf8 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -3,7 +3,7 @@ git-worktree(1) NAME ---- -git-worktree - Manage multiple worktrees +git-worktree - Manage multiple working trees SYNOPSIS @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION ----------- -Manage multiple worktrees attached to the same repository. +Manage multiple working trees attached to the same repository. A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With `git worktree add` a new working @@ -27,19 +27,19 @@ bare repository) and zero or more linked working trees. When you are done with a linked working tree you can simply delete it. The working tree's administrative files in the repository (see "DETAILS" below) will eventually be removed automatically (see -`gc.pruneworktreesexpire` in linkgit::git-config[1]), or you can run +`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run `git worktree prune` in the main or any linked working tree to clean up any stale administrative files. -If you move a linked working directory to another file system, or +If you move a linked working tree to another file system, or within a file system that does not support hard links, you need to run -at least one git command inside the linked working directory +at least one git command inside the linked working tree (e.g. `git status`) in order to update its administrative files in the repository so that they do not get automatically pruned. If a linked working tree is stored on a portable device or network share which is not always mounted, you can prevent its administrative files from -being pruned by creating a file named 'lock' alongside the other +being pruned by creating a file named 'locked' alongside the other administrative files, optionally containing a plain text reason that pruning should be suppressed. See section "DETAILS" for more information. @@ -51,9 +51,9 @@ Create `<path>` and checkout `<branch>` into it. The new working directory is linked to the current repository, sharing everything except working directory specific files such as HEAD, index, etc. + -If `<branch>` is omitted and neither `-b` nor `-B` is used, then, as a -convenience, a new branch based at HEAD is created automatically, as if -`-b $(basename <path>)` was specified. +If `<branch>` is omitted and neither `-b` nor `-B` nor `--detached` used, +then, as a convenience, a new branch based at HEAD is created automatically, +as if `-b $(basename <path>)` was specified. prune:: @@ -64,22 +64,22 @@ OPTIONS -f:: --force:: - By default, `add` refuses to create a new worktree when `<branch>` - is already checked out by another worktree. This option overrides + By default, `add` refuses to create a new working tree when `<branch>` + is already checked out by another working tree. This option overrides that safeguard. -b <new-branch>:: -B <new-branch>:: With `add`, create a new branch named `<new-branch>` starting at - `<branch>`, and check out `<new-branch>` into the new worktree. + `<branch>`, and check out `<new-branch>` into the new working tree. If `<branch>` is omitted, it defaults to HEAD. By default, `-b` refuses to create a new branch if it already exists. `-B` overrides this safeguard, resetting `<new-branch>` to `<branch>`. --detach:: - With `add`, detach HEAD in the new worktree. See "DETACHED HEAD" in - linkgit:git-checkout[1]. + With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" + in linkgit:git-checkout[1]. -n:: --dry-run:: @@ -91,7 +91,7 @@ OPTIONS With `prune`, report all removals. --expire <time>:: - With `prune`, only expire unused worktrees older than <time>. + With `prune`, only expire unused working trees older than <time>. DETAILS ------- @@ -124,7 +124,7 @@ thumb is do not make any assumption about whether a path belongs to $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. -To prevent a $GIT_DIR/worktrees entry from from being pruned (which +To prevent a $GIT_DIR/worktrees entry from being pruned (which can be useful in some situations, such as when the entry's working tree is stored on a portable device), add a file named 'locked' to the entry's directory. The file contains the reason in @@ -139,9 +139,9 @@ EXAMPLES You are in the middle of a refactoring session and your boss comes in and demands that you fix something immediately. You might typically use linkgit:git-stash[1] to store your changes away temporarily, however, your -worktree is in such a state of disarray (with new, moved, and removed files, -and other bits and pieces strewn around) that you don't want to risk -disturbing any of it. Instead, you create a temporary linked worktree to +working tree is in such a state of disarray (with new, moved, and removed +files, and other bits and pieces strewn around) that you don't want to risk +disturbing any of it. Instead, you create a temporary linked working tree to make the emergency fix, remove it when done, and then resume your earlier refactoring session. @@ -164,12 +164,12 @@ checkouts of a superproject. git-worktree could provide more automation for tasks currently performed manually, such as: -- `remove` to remove a linked worktree and its administrative files (and - warn if the worktree is dirty) -- `mv` to move or rename a worktree and update its administrative files -- `list` to list linked worktrees +- `remove` to remove a linked working tree and its administrative files (and + warn if the working tree is dirty) +- `mv` to move or rename a working tree and update its administrative files +- `list` to list linked working trees - `lock` to prevent automatic pruning of administrative files (for instance, - for a worktree on a portable device) + for a working tree on a portable device) GIT --- diff --git a/Documentation/git.txt b/Documentation/git.txt index 5a78d77533..4e5d55be6a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -1011,9 +1011,20 @@ Unsetting the variable, or setting it to empty, "0" or Enables trace messages for all packets coming in or out of a given program. This can help with debugging object negotiation or other protocol issues. Tracing is turned off at a packet - starting with "PACK". + starting with "PACK" (but see 'GIT_TRACE_PACKFILE' below). See 'GIT_TRACE' for available trace output options. +'GIT_TRACE_PACKFILE':: + Enables tracing of packfiles sent or received by a + given program. Unlike other trace output, this trace is + verbatim: no headers, and no quoting of binary data. You almost + certainly want to direct into a file (e.g., + `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on + the terminal or mixing it with other trace output. ++ +Note that this is currently only implemented for the client side +of clones and fetches. + 'GIT_TRACE_PERFORMANCE':: Enables performance related trace messages, e.g. total execution time of each Git command. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 81fe586948..e3b1de8033 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -527,6 +527,8 @@ patterns are available: - `fortran` suitable for source code in the Fortran language. +- `fountain` suitable for Fountain documents. + - `html` suitable for HTML/XHTML documents. - `java` suitable for source code in the Java language. diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 82e2d15435..78e0b27c18 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -448,6 +448,9 @@ set by Git if the remote helper has the 'option' capability. 'option update-shallow {'true'|'false'}:: Allow to extend .git/shallow if the new refs require it. +'option pushcert {'true'|'false'}:: + GPG sign pushes. + SEE ALSO -------- linkgit:git-remote[1] diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 7173b38830..577ee844e0 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -251,25 +251,25 @@ modules:: Contains the git-repositories of the submodules. worktrees:: - Contains worktree specific information of linked - checkouts. Each subdirectory contains the worktree-related - part of a linked checkout. This directory is ignored if - $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/worktrees" will be - used instead. + Contains administrative data for linked + working trees. Each subdirectory contains the working tree-related + part of a linked working tree. This directory is ignored if + $GIT_COMMON_DIR is set, in which case + "$GIT_COMMON_DIR/worktrees" will be used instead. worktrees/<id>/gitdir:: A text file containing the absolute path back to the .git file that points to here. This is used to check if the linked repository has been manually removed and there is no need to - keep this directory any more. mtime of this file should be + keep this directory any more. The mtime of this file should be updated every time the linked repository is accessed. worktrees/<id>/locked:: - If this file exists, the linked repository may be on a - portable device and not available. It does not mean that the - linked repository is gone and `worktrees/<id>` could be - removed. The file's content contains a reason string on why - the repository is locked. + If this file exists, the linked working tree may be on a + portable device and not available. The presence of this file + prevents `worktrees/<id>` from being pruned either automatically + or manually by `git worktree prune`. The file may contain a string + explaining why the repository is locked. worktrees/<id>/link:: If this file exists, it is a hard link to the linked .git diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index ab18f4baca..8c6478b2f2 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -411,6 +411,27 @@ exclude;; core Git. Porcelains expose more of a <<def_SCM,SCM>> interface than the <<def_plumbing,plumbing>>. +[[def_per_worktree_ref]]per-worktree ref:: + Refs that are per-<<def_working_tree,worktree>>, rather than + global. This is presently only <<def_HEAD,HEAD>>, but might + later include other unusual refs. + +[[def_pseudoref]]pseudoref:: + Pseudorefs are a class of files under `$GIT_DIR` which behave + like refs for the purposes of rev-parse, but which are treated + specially by git. Pseudorefs both have names that are all-caps, + and always start with a line consisting of a + <<def_SHA1,SHA-1>> followed by whitespace. So, HEAD is not a + pseudoref, because it is sometimes a symbolic ref. They might + optionally contain some additional data. `MERGE_HEAD` and + `CHERRY_PICK_HEAD` are examples. Unlike + <<def_per_worktree_ref,per-worktree refs>>, these files cannot + be symbolic refs, and never have reflogs. They also cannot be + updated through the normal ref update machinery. Instead, + they are updated by directly writing to the files. However, + they can be read as if they were refs, so `git rev-parse + MERGE_HEAD` will work. + [[def_pull]]pull:: Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and <<def_merge,merge>> it. See also linkgit:git-pull[1]. diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index e9a1d5d25a..2dd79db5cb 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -1,18 +1,31 @@ -At the core level, Git is character encoding agnostic. - - - The pathnames recorded in the index and in the tree objects - are treated as uninterpreted sequences of non-NUL bytes. - What readdir(2) returns are what are recorded and compared - with the data Git keeps track of, which in turn are expected - to be what lstat(2) and creat(2) accepts. There is no such - thing as pathname encoding translation. +Git is to some extent character encoding agnostic. - The contents of the blob objects are uninterpreted sequences of bytes. There is no encoding translation at the core level. - - The commit log messages are uninterpreted sequences of non-NUL - bytes. + - Path names are encoded in UTF-8 normalization form C. This + applies to tree objects, the index file, ref names, as well as + path names in command line arguments, environment variables + and config files (`.git/config` (see linkgit:git-config[1]), + linkgit:gitignore[5], linkgit:gitattributes[5] and + linkgit:gitmodules[5]). ++ +Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly. + + - Commit log messages are typically encoded in UTF-8, but other + extended ASCII encodings are also supported. This includes + ISO-8859-x, CP125x and many others, but _not_ UTF-16/32, + EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, + EUC-x, CP9xx etc.). Although we encourage that the commit log messages are encoded in UTF-8, both the core and Git Porcelain are designed not to diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 31bee069aa..f1c52208f0 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -729,6 +729,11 @@ format, often found in email messages. + `--date=raw` shows the date in the internal raw Git format `%s %z` format. + +`--date=format:...` feeds the format `...` to your system `strftime`. +Use `--date=format:%c` to show the date in your system locale's +preferred format. See the `strftime` manual for a complete list of +format placeholders. ++ `--date=default` shows timestamps in the original time zone (either committer's or author's). diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 1a797812fb..8076172a08 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -46,6 +46,9 @@ Functions Format a string and push it onto the end of the array. This is a convenience wrapper combining `strbuf_addf` and `argv_array_push`. +`argv_array_pushv`:: + Push a null-terminated array of strings onto the end of the array. + `argv_array_pop`:: Remove the final element from the array. If there are no elements in the array, do nothing. diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt deleted file mode 100644 index 93b5f23e4c..0000000000 --- a/Documentation/technical/api-lockfile.txt +++ /dev/null @@ -1,220 +0,0 @@ -lockfile API -============ - -The lockfile API serves two purposes: - -* Mutual exclusion and atomic file updates. When we want to change a - file, we create a lockfile `<filename>.lock`, write the new file - contents into it, and then rename the lockfile to its final - destination `<filename>`. We create the `<filename>.lock` file with - `O_CREAT|O_EXCL` so that we can notice and fail if somebody else has - already locked the file, then atomically rename the lockfile to its - final destination to commit the changes and unlock the file. - -* Automatic cruft removal. If the program exits after we lock a file - but before the changes have been committed, we want to make sure - that we remove the lockfile. This is done by remembering the - lockfiles we have created in a linked list and setting up an - `atexit(3)` handler and a signal handler that clean up the - lockfiles. This mechanism ensures that outstanding lockfiles are - cleaned up if the program exits (including when `die()` is called) - or if the program dies on a signal. - -Please note that lockfiles only block other writers. Readers do not -block, but they are guaranteed to see either the old contents of the -file or the new contents of the file (assuming that the filesystem -implements `rename(2)` atomically). - - -Calling sequence ----------------- - -The caller: - -* Allocates a `struct lock_file` either as a static variable or on the - heap, initialized to zeros. Once you use the structure to call the - `hold_lock_file_*` family of functions, it belongs to the lockfile - subsystem and its storage must remain valid throughout the life of - the program (i.e. you cannot use an on-stack variable to hold this - structure). - -* Attempts to create a lockfile by passing that variable and the path - of the final destination (e.g. `$GIT_DIR/index`) to - `hold_lock_file_for_update` or `hold_lock_file_for_append`. - -* Writes new content for the destination file by either: - - * writing to the file descriptor returned by the `hold_lock_file_*` - functions (also available via `lock->fd`). - - * calling `fdopen_lock_file` to get a `FILE` pointer for the open - file and writing to the file using stdio. - -When finished writing, the caller can: - -* Close the file descriptor and rename the lockfile to its final - destination by calling `commit_lock_file` or `commit_lock_file_to`. - -* Close the file descriptor and remove the lockfile by calling - `rollback_lock_file`. - -* Close the file descriptor without removing or renaming the lockfile - by calling `close_lock_file`, and later call `commit_lock_file`, - `commit_lock_file_to`, `rollback_lock_file`, or `reopen_lock_file`. - -Even after the lockfile is committed or rolled back, the `lock_file` -object must not be freed or altered by the caller. However, it may be -reused; just pass it to another call of `hold_lock_file_for_update` or -`hold_lock_file_for_append`. - -If the program exits before you have called one of `commit_lock_file`, -`commit_lock_file_to`, `rollback_lock_file`, or `close_lock_file`, an -`atexit(3)` handler will close and remove the lockfile, rolling back -any uncommitted changes. - -If you need to close the file descriptor you obtained from a -`hold_lock_file_*` function yourself, do so by calling -`close_lock_file`. You should never call `close(2)` or `fclose(3)` -yourself! Otherwise the `struct lock_file` structure would still think -that the file descriptor needs to be closed, and a commit or rollback -would result in duplicate calls to `close(2)`. Worse yet, if you close -and then later open another file descriptor for a completely different -purpose, then a commit or rollback might close that unrelated file -descriptor. - - -Error handling --------------- - -The `hold_lock_file_*` functions return a file descriptor on success -or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see below). On -errors, `errno` describes the reason for failure. Errors can be -reported by passing `errno` to one of the following helper functions: - -unable_to_lock_message:: - - Append an appropriate error message to a `strbuf`. - -unable_to_lock_error:: - - Emit an appropriate error message using `error()`. - -unable_to_lock_die:: - - Emit an appropriate error message and `die()`. - -Similarly, `commit_lock_file`, `commit_lock_file_to`, and -`close_lock_file` return 0 on success. On failure they set `errno` -appropriately, do their best to roll back the lockfile, and return -1. - - -Flags ------ - -The following flags can be passed to `hold_lock_file_for_update` or -`hold_lock_file_for_append`: - -LOCK_NO_DEREF:: - - Usually symbolic links in the destination path are resolved - and the lockfile is created by adding ".lock" to the resolved - path. If `LOCK_NO_DEREF` is set, then the lockfile is created - by adding ".lock" to the path argument itself. This option is - used, for example, when locking a symbolic reference, which - for backwards-compatibility reasons can be a symbolic link - containing the name of the referred-to-reference. - -LOCK_DIE_ON_ERROR:: - - If a lock is already taken for the file, `die()` with an error - message. If this option is not specified, trying to lock a - file that is already locked returns -1 to the caller. - - -The functions -------------- - -hold_lock_file_for_update:: - - Take a pointer to `struct lock_file`, the path of the file to - be locked (e.g. `$GIT_DIR/index`) and a flags argument (see - above). Attempt to create a lockfile for the destination and - return the file descriptor for writing to the file. - -hold_lock_file_for_append:: - - Like `hold_lock_file_for_update`, but before returning copy - the existing contents of the file (if any) to the lockfile and - position its write pointer at the end of the file. - -fdopen_lock_file:: - - Associate a stdio stream with the lockfile. Return NULL - (*without* rolling back the lockfile) on error. The stream is - closed automatically when `close_lock_file` is called or when - the file is committed or rolled back. - -get_locked_file_path:: - - Return the path of the file that is locked by the specified - lock_file object. The caller must free the memory. - -commit_lock_file:: - - Take a pointer to the `struct lock_file` initialized with an - earlier call to `hold_lock_file_for_update` or - `hold_lock_file_for_append`, close the file descriptor, and - rename the lockfile to its final destination. Return 0 upon - success. On failure, roll back the lock file and return -1, - with `errno` set to the value from the failing call to - `close(2)` or `rename(2)`. It is a bug to call - `commit_lock_file` for a `lock_file` object that is not - currently locked. - -commit_lock_file_to:: - - Like `commit_lock_file()`, except that it takes an explicit - `path` argument to which the lockfile should be renamed. The - `path` must be on the same filesystem as the lock file. - -rollback_lock_file:: - - Take a pointer to the `struct lock_file` initialized with an - earlier call to `hold_lock_file_for_update` or - `hold_lock_file_for_append`, close the file descriptor and - remove the lockfile. It is a NOOP to call - `rollback_lock_file()` for a `lock_file` object that has - already been committed or rolled back. - -close_lock_file:: - - Take a pointer to the `struct lock_file` initialized with an - earlier call to `hold_lock_file_for_update` or - `hold_lock_file_for_append`. Close the file descriptor (and - the file pointer if it has been opened using - `fdopen_lock_file`). Return 0 upon success. On failure to - `close(2)`, return a negative value and roll back the lock - file. Usually `commit_lock_file`, `commit_lock_file_to`, or - `rollback_lock_file` should eventually be called if - `close_lock_file` succeeds. - -reopen_lock_file:: - - Re-open a lockfile that has been closed (using - `close_lock_file`) but not yet committed or rolled back. This - can be used to implement a sequence of operations like the - following: - - * Lock file. - - * Write new contents to lockfile, then `close_lock_file` to - cause the contents to be written to disk. - - * Pass the name of the lockfile to another program to allow it - (and nobody else) to inspect the contents you wrote, while - still holding the lock yourself. - - * `reopen_lock_file` to reopen the lockfile. Make further - updates to the contents. - - * `commit_lock_file` to make the final version permanent. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 1f2db31312..5f0757dcc9 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -168,6 +168,12 @@ There are some macros to easily define options: Introduce an option with integer argument. The integer is put into `int_var`. +`OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`:: + Introduce an option with a size argument. The argument must be a + non-negative integer and may include a suffix of 'k', 'm' or 'g' to + scale the provided value by 1024, 1024^2 or 1024^3 respectively. + The scaled value is put into `unsigned_long_var`. + `OPT_DATE(short, long, &int_var, description)`:: Introduce an option with date argument, see `approxidate()`. The timestamp is put into `int_var`. @@ -212,6 +218,19 @@ There are some macros to easily define options: Use it to hide deprecated options that are still to be recognized and ignored silently. +`OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`:: + Introduce an option that will be reconstructed into a char* string, + which must be initialized to NULL. This is useful when you need to + pass the command-line option to another command. Any previous value + will be overwritten, so this should only be used for options where + the last one specified on the command line wins. + +`OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`:: + Introduce an option where all instances of it on the command-line will + be reconstructed into an argv_array. This is useful when you need to + pass the command-line option, which can be specified multiple times, + to another command. + The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/api-submodule-config.txt b/Documentation/technical/api-submodule-config.txt new file mode 100644 index 0000000000..941fa178dd --- /dev/null +++ b/Documentation/technical/api-submodule-config.txt @@ -0,0 +1,62 @@ +submodule config cache API +========================== + +The submodule config cache API allows to read submodule +configurations/information from specified revisions. Internally +information is lazily read into a cache that is used to avoid +unnecessary parsing of the same .gitmodule files. Lookups can be done by +submodule path or name. + +Usage +----- + +To initialize the cache with configurations from the worktree the caller +typically first calls `gitmodules_config()` to read values from the +worktree .gitmodules and then to overlay the local git config values +`parse_submodule_config_option()` from the config parsing +infrastructure. + +The caller can look up information about submodules by using the +`submodule_from_path()` or `submodule_from_name()` functions. They return +a `struct submodule` which contains the values. The API automatically +initializes and allocates the needed infrastructure on-demand. If the +caller does only want to lookup values from revisions the initialization +can be skipped. + +If the internal cache might grow too big or when the caller is done with +the API, all internally cached values can be freed with submodule_free(). + +Data Structures +--------------- + +`struct submodule`:: + + This structure is used to return the information about one + submodule for a certain revision. It is returned by the lookup + functions. + +Functions +--------- + +`void submodule_free()`:: + + Use these to free the internally cached values. + +`int parse_submodule_config_option(const char *var, const char *value)`:: + + Can be passed to the config parsing infrastructure to parse + local (worktree) submodule configurations. + +`const struct submodule *submodule_from_path(const unsigned char *commit_sha1, const char *path)`:: + + Lookup values for one submodule by its commit_sha1 and path. + +`const struct submodule *submodule_from_name(const unsigned char *commit_sha1, const char *name)`:: + + The same as above but lookup by name. + +If given the null_sha1 as commit_sha1 the local configuration of a +submodule will be returned (e.g. consolidated values from local git +configuration and the .gitmodules file in the worktree). + +For an example usage see test-submodule-config.c. |