diff options
Diffstat (limited to 'Documentation')
34 files changed, 788 insertions, 181 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index ad0e1905a5..65af8d82ce 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -448,7 +448,7 @@ For C programs: - The first #include in C files, except in platform specific compat/ implementations and sha1dc/, must be either "git-compat-util.h" or one of the approved headers that includes it first for you. (The - approved headers currently include "cache.h", "builtin.h", + approved headers currently include "builtin.h", "t/helper/test-tool.h", "xdiff/xinclude.h", or "reftable/system.h"). You do not have to include more than one of these. diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 56130e4bec..62d11a5cd7 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1256,6 +1256,38 @@ index 88f126184c..38da593a60 100644 [[now-what]] == My Patch Got Emailed - Now What? +Please give reviewers enough time to process your initial patch before +sending an updated version. That is, resist the temptation to send a new +version immediately, because others may have already started reviewing +your initial version. + +While waiting for review comments, you may find mistakes in your initial +patch, or perhaps realize a different and better way to achieve the goal +of the patch. In this case you may communicate your findings to other +reviewers as follows: + + - If the mistakes you found are minor, send a reply to your patch as if + you were a reviewer and mention that you will fix them in an + updated version. + + - On the other hand, if you think you want to change the course so + drastically that reviews on the initial patch would be a waste of + time (for everyone involved), retract the patch immediately with + a reply like "I am working on a much better approach, so please + ignore this patch and wait for the updated version." + +Now, the above is a good practice if you sent your initial patch +prematurely without polish. But a better approach of course is to avoid +sending your patch prematurely in the first place. + +Please be considerate of the time needed by reviewers to examine each +new version of your patch. Rather than seeing the initial version right +now (followed by several "oops, I like this version better than the +previous one" patches over 2 days), reviewers would strongly prefer if a +single polished version came 2 days later instead, and that version with +fewer mistakes were the only one they would need to review. + + [[reviewing]] === Responding to Reviews diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index eee513e86f..c68cdb11b9 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -41,6 +41,7 @@ Open up a new file `builtin/walken.c` and set up the command handler: */ #include "builtin.h" +#include "trace.h" int cmd_walken(int argc, const char **argv, const char *prefix) { @@ -49,12 +50,13 @@ int cmd_walken(int argc, const char **argv, const char *prefix) } ---- -NOTE: `trace_printf()` differs from `printf()` in that it can be turned on or -off at runtime. For the purposes of this tutorial, we will write `walken` as -though it is intended for use as a "plumbing" command: that is, a command which -is used primarily in scripts, rather than interactively by humans (a "porcelain" -command). So we will send our debug output to `trace_printf()` instead. When -running, enable trace output by setting the environment variable `GIT_TRACE`. +NOTE: `trace_printf()`, defined in `trace.h`, differs from `printf()` in +that it can be turned on or off at runtime. For the purposes of this +tutorial, we will write `walken` as though it is intended for use as +a "plumbing" command: that is, a command which is used primarily in +scripts, rather than interactively by humans (a "porcelain" command). +So we will send our debug output to `trace_printf()` instead. +When running, enable trace output by setting the environment variable `GIT_TRACE`. Add usage text and `-h` handling, like all subcommands should consistently do (our test suite will notice and complain if you fail to do so). @@ -124,7 +126,7 @@ parameters provided by the user over the CLI. `nr` represents the number of `rev_cmdline_entry` present in the array. -`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is +`alloc` is used by the `ALLOC_GROW` macro. Check `alloc.h` - this variable is used to track the allocated size of the list. Per entry, we find: @@ -341,6 +343,10 @@ the walk loop below the `prepare_revision_walk()` call within your `walken_commit_walk()`: ---- +#include "pretty.h" + +... + static void walken_commit_walk(struct rev_info *rev) { struct commit *commit; @@ -754,6 +760,10 @@ reachable objects are walked in order to populate the list. First, add the `struct oidset` and related items we will use to iterate it: ---- +#include "oidset.h" + +... + static void walken_object_walk( ... @@ -805,6 +815,10 @@ just walks of commits. First, we'll make our handlers chattier - modify go: ---- +#include "hex.h" + +... + static void walken_show_commit(struct commit *cmt, void *buf) { trace_printf("commit: %s\n", oid_to_hex(&cmt->object.oid)); diff --git a/Documentation/RelNotes/2.42.0.txt b/Documentation/RelNotes/2.42.0.txt index 85e078839c..0f1897ad5f 100644 --- a/Documentation/RelNotes/2.42.0.txt +++ b/Documentation/RelNotes/2.42.0.txt @@ -13,6 +13,37 @@ UI, Workflows & Features enumerates extra objects to be used as anchoring points to keep otherwise unreachable objects in cruft packs. + * Add more "git var" for toolsmiths to learn various locations Git is + configured with either via the configuration or hard-coded defaults. + + * 'git notes append' was taught '--separator' to specify string to insert + between paragraphs. + + * The "git for-each-ref" family of commands learned placeholders + related to GPG signature verification. + + * "git diff --no-index" learned to read from named pipes as if they + were regular files, to allow "git diff <(process) <(substitution)" + some shells support. + + * Help newbies by suggesting that there are cases where force-pushing + is a valid and sensible thing to update a branch at a remote + repository, rather than reconciling with merge/rebase. + + * "git blame --contents=file" has been taught to work in a bare + repository. + + * "git branch -f X" to repoint the branch X said that X was "checked + out" in another worktree, even when branch X was not and instead + being bisected or rebased. The message was reworded to say the + branch was "in use". + + * Tone down the warning on SHA-256 repositories being an experimental + curiosity. We do not have support for them to interoperate with + traditional SHA-1 repositories, but at this point, we do not plan + to make breaking changes to SHA-256 repositories and there is no + longer need for such a strongly phrased warning. + Performance, Internal Implementation, Development Support etc. @@ -31,6 +62,42 @@ Performance, Internal Implementation, Development Support etc. * "git worktree" learned to work better with sparse index feature. + * When the external merge driver is killed by a signal, its output + should not be trusted as a resolution with conflicts that is + proposed by the driver, but the code did. + + * The set-up code for the get_revision() API now allows feeding + options like --all and --not in the --stdin mode. + + * Move functions that are not about pure string manipulation out of + strbuf.[ch] + + * "imap-send" codepaths got cleaned up to get rid of unused + parameters. + + * Enumerating refs in the packed-refs file, while excluding refs that + match certain patterns, has been optimized. + + * Mark-up unused parameters in the code so that we can eventually + enable -Wunused-parameter by default. + + * Instead of inventing a custom counter variables for debugging, + use existing trace2 facility in the fsync customization codepath. + + * "git branch --list --format=<format>" and friends are taught + a new "%(describe)" placeholder. + + * Clarify how to choose the starting point for a new topic in + developer guidance document. + + * The implementation of "get_sha1_hex()" that reads a hexadecimal + string that spells a full object name has been extended to cope + with any hash function used in the repository, but the "sha1" in + its name survived. Rename it to get_hash_hex(), a name that is + more consistent within its friends like get_hash_hex_algop(). + + * Command line parser fix, and a small parse-options API update. + Fixes since v2.41 ----------------- @@ -117,6 +184,110 @@ Fixes since v2.41 between the way the code enumerates packfiles in the repository. (merge 73320e49ad tb/collect-pack-filenames-fix later to maint). + * We create .pack and then .idx, we consider only packfiles that have + .idx usable (those with only .pack are not ready yet), so we should + remove .idx before removing .pack for consistency. + (merge 0dd1324a73 ds/remove-idx-before-pack later to maint). + + * Partially revert a sanity check that the rest of the config code + was not ready, to avoid triggering it in a corner case. + (merge a53f43f900 gc/config-partial-submodule-kvi-fix later to maint). + + * "git apply" punts when it is fed too large a patch input; the error + message it gives when it happens has been clarified. + (merge 42612e18d2 pw/apply-too-large later to maint). + + * During a cherry-pick or revert session that works on multiple + commits, "git status" did not give correct information, which has + been corrected. + (merge a096a889f4 jk/cherry-pick-revert-status later to maint). + + * A few places failed to differentiate the case where the index is + truly empty (nothing added) and we haven't yet read from the + on-disk index file, which have been corrected. + (merge 2ee045eea1 js/empty-index-fixes later to maint). + + * "git bugreport" tests did not test what it wanted to test, which + has been corrected. + (merge 1aa92b8500 ma/t0091-fixup later to maint). + + * Code snippets in a tutorial document no longer compiled after + recent header shuffling, which have been corrected. + (merge bbd7c7b7c0 vd/adjust-mfow-doc-to-updated-headers later to maint). + + * "git ls-files '(attr:X)D/'" that triggers the common prefix + optimization codepath failed to read from "D/.gitattributes", + which has been corrected. + (merge f4a8fde057 jc/pathspec-match-with-common-prefix later to maint). + + * "git fsck --no-progress" still spewed noise from the commit-graph + subsystem, which has been corrected. + (merge 9281cd07f0 tb/fsck-no-progress later to maint). + + * Various offset computation in the code that accesses the packfiles + and other data in the object layer has been hardened against + arithmetic overflow, especially on 32-bit systems. + (merge 9a25cad7e0 tb/object-access-overflow-protection later to maint). + + * Names of MinGW header files are spelled in mixed case in some + source files, but the build host can be using case sensitive + filesystem with header files with their name spelled in all + lowercase. + (merge 4a53d0d0bc mh/mingw-case-sensitive-build later to maint). + + * Update message mark-up for i18n in "git bundle". + (merge bbb6acd998 dk/bundle-i18n-more later to maint). + + * "git tag --list --points-at X" showed tags that directly refers to + object X, but did not list a tag that points at such a tag, which + has been corrected. + + * "./configure --with-expat=no" did not work as a way to refuse use + of the expat library on a system with the library installed, which + has been corrected. + (merge fb8f7269c2 ah/autoconf-fixes later to maint). + + * When the user edits "rebase -i" todo file so that it starts with a + "fixup", which would make it invalid, the command truncated the + rest of the file before giving an error and returning the control + back to the user. Stop truncating to make it easier to correct + such a malformed todo file. + (merge 9645a087c2 ah/sequencer-rewrite-todo-fix later to maint). + + * Rewrite the description of giving a custom command to the + submodule.<name>.update configuration variable. + (merge 7cebc5bd78 pv/doc-submodule-update-settings later to maint). + + * Adjust to OpenSSL 3+, which deprecates its SHA-1 functions based on + its traditional API, by using its EVP API instead. + (merge bda9c12073 ew/hash-with-openssl-evp later to maint). + + * Exclude "." from the set of characters to be removed from the + beginning and the end of the human-readable name. + (merge 1c04cb0744 bc/ident-dot-is-no-longer-crud-letter later to maint). + + * "git bisect visualize" stopped running "gitk" on Git for Windows + when the command was reimplemented in C around Git 2.34 timeframe. + This has been corrected. + (merge fff1594fa7 ma/locate-in-path-for-windows later to maint). + + * "git rebase -i" with a series of squash/fixup, when one of the + steps stopped in conflicts and ended up getting skipped, did not + handle the accumulated commit log messages, which has been + corrected. + (merge 6ce7afe163 pw/rebase-skip-commit-message-fix later to maint). + + * Adjust to newer Term::ReadLine to prevent it from breaking + the interactive prompt code in send-email. + (merge c016726c2d jk/send-email-with-new-readline later to maint). + + * Windows updates. + (merge 0050f8e401 ds/maintenance-on-windows-fix later to maint). + + * Correct use of lstat() that assumed a failing call would not + clobber the statbuf. + (merge 72695d8214 st/mv-lstat-fix later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 51f9d2e563 sa/doc-ls-remote later to maint). (merge c6d26a9dda jk/format-patch-message-id-unleak later to maint). @@ -134,3 +305,25 @@ Fixes since v2.41 (merge 6c26da8404 mh/credential-erase-improvements later to maint). (merge 78e56cff69 tz/lib-gpg-prereq-fix later to maint). (merge 80d32e84b5 rj/leakfixes later to maint). + (merge 0a868031ed pb/complete-diff-options later to maint). + (merge d4f28279ad jc/doc-hash-object-types later to maint). + (merge 1876a5ae15 ks/t4205-test-describe-with-abbrev-fix later to maint). + (merge 6e6a529b57 jk/fsck-indices-in-worktrees later to maint). + (merge 3e81b896f7 rs/packet-length-simplify later to maint). + (merge 4c9cb51fe7 mh/doc-credential-helpers later to maint). + (merge 3437f549dd jr/gitignore-doc-example-markup later to maint). + (merge 947ebd62a0 jc/am-parseopt-fix later to maint). + (merge e12cb98e1e jc/branch-parseopt-fix later to maint). + (merge d6f598e443 jc/gitignore-doc-pattern-markup later to maint). + (merge a2dad4868b jc/transport-parseopt-fix later to maint). + (merge 68cbb20e73 jc/parse-options-show-branch later to maint). + (merge 3821eb6c3d jc/parse-options-reset later to maint). + (merge c48af99a3e bb/trace2-comment-fix later to maint). + (merge c95ae3ff9c rs/describe-parseopt-fix later to maint). + (merge 36f76d2a25 rs/pack-objects-parseopt-fix later to maint). + (merge 30c8c55cbf jc/tree-walk-drop-base-offset later to maint). + (merge d089a06421 rs/bundle-parseopt-cleanup later to maint). + (merge 823839bda1 ew/sha256-gcrypt-leak-fixes later to maint). + (merge a5c01603b3 bc/ignore-clangd-cache later to maint). + (merge 12009a182b js/allow-t4000-to-be-indented-with-spaces later to maint). + (merge b3dcd24b8a jc/send-email-pre-process-fix later to maint). diff --git a/Documentation/RelNotes/2.43.0.txt b/Documentation/RelNotes/2.43.0.txt new file mode 100644 index 0000000000..7ed39b4700 --- /dev/null +++ b/Documentation/RelNotes/2.43.0.txt @@ -0,0 +1,157 @@ +Git v2.43 Release Notes +======================= + +Backward Compatibility Notes + + * The "--rfc" option of "git format-patch" used to be a valid way to + override an earlier "--subject-prefix=<something>" on the command + line and replace it with "[RFC PATCH]", but from this release, it + merely prefixes the string "RFC " in front of the given subject + prefix. If you are negatively affected by this change, please use + "--subject-prefix=PATCH --rfc" as a replacement. + + +UI, Workflows & Features + + * A message written in olden time prevented a branch from getting + checked out saying it is already checked out elsewhere, but these + days, we treat a branch that is being bisected or rebased just like + a branch that is checked out and protect it. Rephrase the message + to say that the branch is in use. + + * Hourly and other schedule of "git maintenance" jobs are randomly + distributed now. + + * "git cmd -h" learned to signal which options can be negated by + listing such options like "--[no-]opt". + + * The way authentication related data other than passwords (e.g. + oath token and password expiration data) are stored in libsecret + keyrings has been rethought. + + * Update two credential helpers to correctly match which credential + to erase; they dropped not the ones with stale password. + + * Git GUI updates. + + * "git format-patch" learns a way to feed cover letter description, + that (1) can be used on detached HEAD where there is no branch + description available, and (2) also can override the branch + description if there is one. + + * Use of --max-pack-size to allow multiple packfiles to be created is + now supported even when we are sending unreachable objects to cruft + packs. + + * "git format-patch --rfc --subject-prefix=<foo>" used to ignore the + "--subject-prefix" option and used "[RFC PATCH]"; now we will add + "RFC" prefix to whatever subject prefix is specified. + + * "git log --format" has been taught the %(decorate) placeholder. + + * The default log message created by "git revert", when reverting a + commit that records a revert, has been tweaked, to encourage people + describe complex "revert of revert of revert" situation better in + their own words. + + +Performance, Internal Implementation, Development Support etc. + + * "git check-attr" has been taught to work better with sparse-index. + + * It may be tempting to leave the help text NULL for a command line + option that is either hidden or too obvious, but "git subcmd -h" + and "git subcmd --help-all" would have segfaulted if done so. Now + the help text is optional. + + * Tests that are known to pass with LSan are now marked as such. + (merge 5fafe8c95f tb/mark-more-tests-as-leak-free later to maint). + + * Flakey "git p4" tests, as well as "git svn" tests, are now skipped + in the (rather expensive) sanitizer CI job. + (merge 6ba913629f js/ci-san-skip-p4-and-svn-tests later to maint). + + * Tests with LSan from time to time seem to emit harmless message + that makes our tests unnecessarily flakey; we work it around by + filtering the uninteresting output. + (merge 370ef7e40d jk/test-lsan-denoise-output later to maint). + + * Unused parameters to functions are marked as such, and/or removed, + in order to bring us closer to -Wunused-parameter clean. + + +Fixes since v2.42 +----------------- + + * Overly long label names used in the sequencer machinery are now + chopped to fit under filesystem limitation. + (merge ac300bda10 mp/rebase-label-length-limit later to maint). + + * Scalar updates. + (merge f9a547d3a7 ds/scalar-updates later to maint). + + * Tweak GitHub Actions CI so that pushing the same commit to multiple + branch tips at the same time will not waste building and testing + the same thing twice. + (merge 99fe06cbfd jc/ci-skip-same-commit later to maint). + + * The commit-graph verification code that detects mixture of zero and + non-zero generation numbers has been updated. + (merge db6044d762 tb/commit-graph-verify-fix later to maint). + + * "git diff -w --exit-code" with various options did not work + correctly, which is being addressed. + (merge a64f8b2595 jc/diff-exit-code-with-w-fixes later to maint). + + * transfer.unpackLimit ought to be used as a fallback, but overrode + fetch.unpackLimit and receive.unpackLimit instead. + (merge f3d33f8cfe ts/unpacklimit-config-fix later to maint). + + * The use of API between two calls to require_clean_work_tree() from + the sequencer code has been cleaned up for consistency. + (merge a9b5955e07 ob/sequencer-empty-hint-fix later to maint). + + * "git diff --no-such-option" and other corner cases around the exit + status of the "diff" command has been corrected. + (merge 5cc6b2d70b jk/diff-result-code-cleanup later to maint). + + * "git for-each-ref --sort='contents:size'" sorts the refs according + to size numerically, giving a ref that points at a blob twelve-byte + (12) long before showing a blob hundred-byte (100) long. + (merge 6d79cd8474 ks/ref-filter-sort-numerically later to maint). + + * We now limit depth of the tree objects and maximum length of + pathnames recorded in tree objects. + (merge 4d5693ba05 jk/tree-name-and-depth-limit later to maint). + + * Various fixes to the behaviour of "rebase -i" when the command got + interrupted by conflicting changes. + (merge 203573b024 pw/rebase-i-after-failure later to maint). + + * References from description of the `--patch` option in various + manual pages have been simplified and improved. + (merge 11422f23e3 so/diff-doc-for-patch-update later to maint). + + * "git grep -e A --no-or -e B" is accepted, even though the negation + of "or" did not mean anything, which has been tightened. + (merge aae8558b10 rs/grep-no-no-or later to maint). + + * The completion script (in contrib/) has been taught to treat the + "-t" option to "git checkout" and "git switch" just like the + "--track" option, to complete remote-tracking branches. + (merge 9f892830d6 js/complete-checkout-t later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge fd3ba590d8 ws/git-push-doc-grammofix later to maint). + (merge 5f33a843de ds/upload-pack-error-sequence-fix later to maint). + (merge beaa1d952b jk/function-pointer-mismatches-fix later to maint). + (merge b46d806ea5 ob/t9001-indent-fix later to maint). + (merge fdc9914c28 ja/worktree-orphan later to maint). + (merge c2cbefc510 jc/mv-d-to-d-error-message-fix later to maint). + (merge d0fc552bfc ch/t6300-verify-commit-test-cleanup later to maint). + (merge aa4b83dd5e ws/git-svn-retire-faketerm later to maint). + (merge edf80d23f1 jk/ci-retire-allow-ref later to maint). + (merge 256a94ef6c bc/more-git-var later to maint). + (merge 82af2c639c ob/sequencer-reword-error-message later to maint). + (merge 2a63c79dae rs/grep-parseopt-simplify later to maint). + (merge 078c42531e rs/name-rev-use-opt-hidden-bool later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b218e27357..973d7a81d4 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -3,45 +3,101 @@ Submitting Patches == Guidelines -Here are some guidelines for people who want to contribute their code to this -software. There is also a link:MyFirstContribution.html[step-by-step tutorial] +Here are some guidelines for contributing back to this +project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. -[[base-branch]] -=== Decide what to base your work on. - -In general, always base your work on the oldest branch that your -change is relevant to. - -* A bugfix should be based on `maint` in general. If the bug is not - present in `maint`, base it on `master`. For a bug that's not yet - in `master`, find the topic that introduces the regression, and - base your work on the tip of the topic. - -* A new feature should be based on `master` in general. If the new - feature depends on other topics that are in `next`, but not in - `master`, fork a branch from the tip of `master`, merge these topics - to the branch, and work on that branch. You can remind yourself of - how you prepared the base with `git log --first-parent master..`. - -* Corrections and enhancements to a topic not yet in `master` should - be based on the tip of that topic. If the topic has not been merged - to `next`, it's alright to add a note to squash minor corrections - into the series. - -* In the exceptional case that a new feature depends on several topics - not in `master`, start working on `next` or `seen` privately and - send out patches only for discussion. Once your new feature starts - to stabilize, you would have to rebase it (see the "depends on other - topics" above). - -* Some parts of the system have dedicated maintainers with their own - repositories (see the section "Subsystems" below). Changes to - these parts should be based on their trees. - -To find the tip of a topic branch, run `git log --first-parent -master..seen` and look for the merge commit. The second parent of this -commit is the tip of the topic branch. +[[choose-starting-point]] +=== Choose a starting point. + +As a preliminary step, you must first choose a starting point for your +work. Typically this means choosing a branch, although technically +speaking it is actually a particular commit (typically the HEAD, or tip, +of the branch). + +There are several important branches to be aware of. Namely, there are +four integration branches as discussed in linkgit:gitworkflows[7]: + +* maint +* master +* next +* seen + +The branches lower on the list are typically descendants of the ones +that come before it. For example, `maint` is an "older" branch than +`master` because `master` usually has patches (commits) on top of +`maint`. + +There are also "topic" branches, which contain work from other +contributors. Topic branches are created by the Git maintainer (in +their fork) to organize the current set of incoming contributions on +the mailing list, and are itemized in the regular "What's cooking in +git.git" announcements. To find the tip of a topic branch, run `git log +--first-parent master..seen` and look for the merge commit. The second +parent of this commit is the tip of the topic branch. + +There is one guiding principle for choosing the right starting point: in +general, always base your work on the oldest integration branch that +your change is relevant to (see "Merge upwards" in +linkgit:gitworkflows[7]). What this principle means is that for the +vast majority of cases, the starting point for new work should be the +latest HEAD commit of `maint` or `master` based on the following cases: + +* If you are fixing bugs in the released version, use `maint` as the + starting point (which may mean you have to fix things without using + new API features on the cutting edge that recently appeared in + `master` but were not available in the released version). + +* Otherwise (such as if you are adding new features) use `master`. + + +NOTE: In exceptional cases, a bug that was introduced in an old +version may have to be fixed for users of releases that are much older +than the recent releases. `git describe --contains X` may describe +`X` as `v2.30.0-rc2-gXXXXXX` for the commit `X` that introduced the +bug, and the bug may be so high-impact that we may need to issue a new +maintenance release for Git 2.30.x series, when "Git 2.41.0" is the +current release. In such a case, you may want to use the tip of the +maintenance branch for the 2.30.x series, which may be available in the +`maint-2.30` branch in https://github.com/gitster/git[the maintainer's +"broken out" repo]. + +This also means that `next` or `seen` are inappropriate starting points +for your work, if you want your work to have a realistic chance of +graduating to `master`. They are simply not designed to be used as a +base for new work; they are only there to make sure that topics in +flight work well together. This is why both `next` and `seen` are +frequently re-integrated with incoming patches on the mailing list and +force-pushed to replace previous versions of themselves. A topic that is +literally built on top of `next` cannot be merged to `master` without +dragging in all the other topics in `next`, some of which may not be +ready. + +For example, if you are making tree-wide changes, while somebody else is +also making their own tree-wide changes, your work may have severe +overlap with the other person's work. This situation may tempt you to +use `next` as your starting point (because it would have the other +person's work included in it), but doing so would mean you'll not only +depend on the other person's work, but all the other random things from +other contributors that are already integrated into `next`. And as soon +as `next` is updated with a new version, all of your work will need to +be rebased anyway in order for them to be cleanly applied by the +maintainer. + +Under truly exceptional circumstances where you absolutely must depend +on a select few topic branches that are already in `next` but not in +`master`, you may want to create your own custom base-branch by forking +`master` and merging the required topic branches to it. You could then +work on top of this base-branch. But keep in mind that this base-branch +would only be known privately to you. So when you are ready to send +your patches to the list, be sure to communicate how you created it in +your cover letter. This critical piece of information would allow +others to recreate your base-branch on their end in order for them to +try out your work. + +Finally, note that some parts of the system have dedicated maintainers +with their own separate source code repositories (see the section +"Subsystems" below). [[separate-commits]] === Make separate commits for logically separate changes. @@ -317,10 +373,13 @@ Please make sure your patch does not add commented out debugging code, or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the base you -have chosen in the "Decide what to base your work on" section, -and unless it targets the `master` branch (which is the default), -mark your patches as such. +sending out, please make sure it cleanly applies to the starting point you +have chosen in the "Choose a starting point" section. + +NOTE: From the perspective of those reviewing your patch, the `master` +branch is the default expected starting point. So if you have chosen a +different starting point, please communicate this choice in your cover +letter. [[send-patches]] diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index dfbdaf00b8..0e8c2832bf 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -736,3 +736,9 @@ core.abbrev:: If set to "no", no abbreviation is made and the object names are shown in their full length. The minimum length is 4. + +core.maxTreeDepth:: + The maximum depth Git is willing to recurse while traversing a + tree (e.g., "a/b/cde/f" has a depth of 4). This is a fail-safe + to allow Git to abort cleanly, and should not generally need to + be adjusted. The default is 4096. diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt index afaf6dad99..9c248accec 100644 --- a/Documentation/config/rebase.txt +++ b/Documentation/config/rebase.txt @@ -77,3 +77,9 @@ rebase.rebaseMerges:: equivalent to `--no-rebase-merges`. Passing `--rebase-merges` on the command line, with or without an argument, overrides any `rebase.rebaseMerges` configuration. + +rebase.maxLabelLength:: + When generating label names from commit subjects, truncate the names to + this length. By default, the names are truncated to a little less than + `NAME_MAX` (to allow e.g. `.lock` files to be written for the + corresponding loose refs). diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 9f33f88771..c07488b123 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -22,13 +22,7 @@ ifndef::git-format-patch[] -p:: -u:: --patch:: - Generate patch (see section titled -ifdef::git-log[] -<<generate_patch_text_with_p, "Generating patch text with -p">>). -endif::git-log[] -ifndef::git-log[] -"Generating patch text with -p"). -endif::git-log[] + Generate patch (see <<generate_patch_text_with_p>>). ifdef::git-diff[] This is the default. endif::git-diff[] diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.txt index 12eae8a222..09b0aecbf8 100644 --- a/Documentation/fsck-msgids.txt +++ b/Documentation/fsck-msgids.txt @@ -103,6 +103,13 @@ `hasDotgit`:: (WARN) A tree contains an entry named `.git`. +`largePathname`:: + (WARN) A tree contains an entry with a very long path name. If + the value of `fsck.largePathname` contains a colon, that value + is used as the maximum allowable length (e.g., "warn:10" would + complain about any path component of 11 or more bytes). The + default value is 4096. + `mailmapSymlink`:: (INFO) `.mailmap` is a symlink. diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index fbb39fbdf5..7872dba3ae 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -204,9 +204,14 @@ as an alternative to `visualize`): $ git bisect visualize ------------ -If the `DISPLAY` environment variable is not set, 'git log' is used -instead. You can also give command-line options such as `-p` and -`--stat`. +Git detects a graphical environment through various environment variables: +`DISPLAY`, which is set in X Window System environments on Unix systems. +`SESSIONNAME`, which is set under Cygwin in interactive desktop sessions. +`MSYSTEM`, which is set under Msys2 and Git for Windows. +`SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions. + +If none of these environment variables is set, 'git log' is used instead. +You can also give command-line options such as `-p` and `--stat`. ------------ $ git bisect visualize --stat diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 1e215d4e73..11b2bc3121 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -14,6 +14,7 @@ SYNOPSIS [--points-at=<object>] [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] + [--exclude=<pattern> ...] DESCRIPTION ----------- @@ -102,6 +103,11 @@ OPTIONS Do not print a newline after formatted refs where the format expands to the empty string. +--exclude=<pattern>:: + If one or more patterns are given, only refs which do not match + any excluded pattern(s) are shown. Matching is done using the + same rules as `<pattern>` above. + FIELD NAMES ----------- @@ -221,6 +227,33 @@ symref:: `:lstrip` and `:rstrip` options in the same way as `refname` above. +signature:: + The GPG signature of a commit. + +signature:grade:: + Show "G" for a good (valid) signature, "B" for a bad + signature, "U" for a good signature with unknown validity, "X" + for a good signature that has expired, "Y" for a good + signature made by an expired key, "R" for a good signature + made by a revoked key, "E" if the signature cannot be + checked (e.g. missing key) and "N" for no signature. + +signature:signer:: + The signer of the GPG signature of a commit. + +signature:key:: + The key of the GPG signature of a commit. + +signature:fingerprint:: + The fingerprint of the GPG signature of a commit. + +signature:primarykeyfingerprint:: + The primary key fingerprint of the GPG signature of a commit. + +signature:trustlevel:: + The trust level of the GPG signature of a commit. Possible + outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. + worktreepath:: The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree. Empty string @@ -231,6 +264,29 @@ ahead-behind:<committish>:: commits ahead and behind, respectively, when comparing the output ref to the `<committish>` specified in the format. +describe[:options]:: + A human-readable name, like linkgit:git-describe[1]; + empty string for undescribable commits. The `describe` string may + be followed by a colon and one or more comma-separated options. ++ +-- +tags=<bool-value>;; + Instead of only considering annotated tags, consider + lightweight tags as well; see the corresponding option in + linkgit:git-describe[1] for details. +abbrev=<number>;; + Use at least <number> hexadecimal digits; see the corresponding + option in linkgit:git-describe[1] for details. +match=<pattern>;; + Only consider tags matching the given `glob(7)` pattern, + excluding the "refs/tags/" prefix; see the corresponding option + in linkgit:git-describe[1] for details. +exclude=<pattern>;; + Do not consider tags matching the given `glob(7)` pattern, + excluding the "refs/tags/" prefix; see the corresponding option + in linkgit:git-describe[1] for details. +-- + In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can be used to specify the value in the header field. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 373b46fc0d..711823a7f4 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -215,11 +215,21 @@ is greater than 100 bytes, then the mode will be `message`, otherwise If `<mode>` is `none`, both the cover letter subject and body will be populated with placeholder text. +--description-file=<file>:: + Use the contents of <file> instead of the branch's description + for generating the cover letter. + --subject-prefix=<subject prefix>:: Instead of the standard '[PATCH]' prefix in the subject - line, instead use '[<subject prefix>]'. This - allows for useful naming of a patch series, and can be - combined with the `--numbered` option. + line, instead use '[<subject prefix>]'. This can be used + to name a patch series, and can be combined with the + `--numbered` option. ++ +The configuration variable `format.subjectPrefix` may also be used +to configure a subject prefix to apply to a given repository for +all patches. This is often useful on mailing lists which receive +patches for several repositories and can be used to disambiguate +the patches (with a value of e.g. "PATCH my-project"). --filename-max-length=<n>:: Instead of the standard 64 bytes, chomp the generated output @@ -229,9 +239,9 @@ populated with placeholder text. variable, or 64 if unconfigured. --rfc:: - Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For - Comments"; use this when sending an experimental patch for - discussion rather than application. + Prepends "RFC" to the subject prefix (producing "RFC PATCH" by + default). RFC means "Request For Comments"; use this when sending + an experimental patch for discussion rather than application. -v <n>:: --reroll-count=<n>:: diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 472b5bb995..8577f7a7d4 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -3,7 +3,7 @@ git-hash-object(1) NAME ---- -git-hash-object - Compute object ID and optionally creates a blob from a file +git-hash-object - Compute object ID and optionally create an object from a file SYNOPSIS @@ -25,7 +25,8 @@ OPTIONS ------- -t <type>:: - Specify the type (default: "blob"). + Specify the type of object to be created (default: "blob"). Possible + values are `commit`, `tree`, `blob`, and `tag`. -w:: Actually write the object into the object database. diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index efbc10f0f5..f8310e56a8 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -9,10 +9,10 @@ SYNOPSIS -------- [verse] 'git notes' [list [<object>]] -'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] 'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] ) -'git notes' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] -'git notes' edit [--allow-empty] [<object>] +'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace] 'git notes' show [<object>] 'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref> 'git notes' merge --commit [-v | -q] @@ -65,7 +65,9 @@ add:: However, if you're using `add` interactively (using an editor to supply the notes contents), then - instead of aborting - the existing notes will be opened in the editor (like the `edit` - subcommand). + subcommand). If you specify multiple `-m` and `-F`, a blank + line will be inserted between the messages. Use the `--separator` + option to insert other delimiters. copy:: Copy the notes for the first object onto the second object (defaults to @@ -85,8 +87,12 @@ corresponding <to-object>. (The optional `<rest>` is ignored so that the command can read the input given to the `post-rewrite` hook.) append:: - Append to the notes of an existing object (defaults to HEAD). - Creates a new notes object if needed. + Append new message(s) given by `-m` or `-F` options to an + existing note, or add them as a new note if one does not + exist, for the object (defaults to HEAD). When appending to + an existing note, a blank line is added before each new + message as an inter-paragraph separator. The separator can + be customized with the `--separator` option. edit:: Edit the notes for a given object (defaults to HEAD). @@ -136,6 +142,7 @@ OPTIONS are concatenated as separate paragraphs. Lines starting with `#` and empty lines other than a single line between paragraphs will be stripped out. + If you wish to keep them verbatim, use `--no-stripspace`. -F <file>:: --file=<file>:: @@ -143,12 +150,16 @@ OPTIONS read the note message from the standard input. Lines starting with `#` and empty lines other than a single line between paragraphs will be stripped out. + If you wish to keep them verbatim, use `--no-stripspace`. -C <object>:: --reuse-message=<object>:: Take the given blob object (for example, another note) as the note message. (Use `git notes copy <object>` instead to - copy notes between objects.) + copy notes between objects.). By default, message will be + copied verbatim, but if you wish to strip out the lines + starting with `#` and empty lines other than a single line + between paragraphs, use with`--stripspace` option. -c <object>:: --reedit-message=<object>:: @@ -159,6 +170,19 @@ OPTIONS Allow an empty note object to be stored. The default behavior is to automatically remove empty notes. +--[no-]separator, --separator=<paragraph-break>:: + Specify a string used as a custom inter-paragraph separator + (a newline is added at the end as needed). If `--no-separator`, no + separators will be added between paragraphs. Defaults to a blank + line. + +--[no-]stripspace:: + Strip leading and trailing whitespace from the note message. + Also strip out empty lines other than a single line between + paragraphs. Lines starting with `#` will be stripped out + in non-editor cases like `-m`, `-F` and `-C`, but not in + editor case like `git notes edit`, `-c`, etc. + --ref <ref>:: Manipulate the notes tree in <ref>. This overrides `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index a9995a932c..dea7eacb0f 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -116,9 +116,7 @@ unreachable object whose mtime is newer than the `--cruft-expiration`). + Incompatible with `--unpack-unreachable`, `--keep-unreachable`, `--pack-loose-unreachable`, `--stdin-packs`, as well as any other -options which imply `--revs`. Also incompatible with `--max-pack-size`; -when this option is set, the maximum pack size is not inferred from -`pack.packSizeLimit`. +options which imply `--revs`. --cruft-expiration=<approxidate>:: If specified, objects are eliminated from the cruft pack if they diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 297927d866..5b4edaf4a8 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -37,7 +37,7 @@ the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide what to push (See linkgit:git-config[1] for the meaning of `push.default`). -When neither the command-line nor the configuration specify what to +When neither the command-line nor the configuration specifies what to push, the default behavior is used, which corresponds to the `simple` value for `push.default`: the current branch is pushed to the corresponding upstream branch, but as a safety measure, the push is diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index f26a7591e3..6a4968f68a 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -398,7 +398,7 @@ some-command [<options>] <args>... some-command does foo and bar! -- -h,help show the help +h,help! show the help foo some nifty option --foo bar= some cool option --bar with an argument @@ -424,10 +424,10 @@ usage: some-command [<options>] <args>... some-command does foo and bar! -h, --help show the help - --foo some nifty option --foo - --bar ... some cool option --bar with an argument - --baz <arg> another cool option --baz with a named argument - --qux[=<path>] qux may take a path argument but has meaning by itself + --[no-]foo some nifty option --foo + --[no-]bar ... some cool option --bar with an argument + --[no-]baz <arg> another cool option --baz with a named argument + --[no-]qux[=<path>] qux may take a path argument but has meaning by itself An option group Header -C[...] option C with an optional argument diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index d2e10d3dce..cbe0208834 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -142,6 +142,16 @@ EXAMPLES changes. The revert only modifies the working tree and the index. +DISCUSSION +---------- + +While git creates a basic commit message automatically, it is +_strongly_ recommended to explain why the original commit is being +reverted. +In addition, repeatedly reverting reverts will result in increasingly +unwieldy subject lines, for example 'Reapply "Reapply "<original subject>""'. +Please consider rewording these to be shorter and more unique. + CONFIGURATION ------------- diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 44c7387d78..2fe274b8fa 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -47,7 +47,7 @@ OPTIONS -d:: --dereference:: - Dereference tags into object IDs as well. They will be shown with `{caret}{}` + Dereference tags into object IDs as well. They will be shown with `^{}` appended. -s:: @@ -78,7 +78,7 @@ OPTIONS Make `git show-ref` act as a filter that reads refs from stdin of the form `^(?:<anything>\s)?<refname>(?:\^{})?$` and performs the following actions on each: - (1) strip `{caret}{}` at the end of line if any; + (1) strip `^{}` at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; (4) ignore if refname is a ref that exists in the local repository; diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 4d3ab6b9f9..695730609a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree). init [--] [<path>...]:: Initialize the submodules recorded in the index (which were added and committed elsewhere) by setting `submodule.$name.url` - in .git/config. It uses the same setting from `.gitmodules` as + in `.git/config`, using the same setting from `.gitmodules` as a template. If the URL is relative, it will be resolved using the default remote. If there is no default remote, the current repository will be assumed to be upstream. @@ -105,9 +105,12 @@ If no path is specified and submodule.active has been configured, submodules configured to be active will be initialized, otherwise all submodules are initialized. + -When present, it will also copy the value of `submodule.$name.update`. -This command does not alter existing information in .git/config. -You can then customize the submodule clone URLs in .git/config +It will also copy the value of `submodule.$name.update`, if present in +the `.gitmodules` file, to `.git/config`, but (1) this command does not +alter existing information in `.git/config`, and (2) `submodule.$name.update` +that is set to a custom command is *not* copied for security reasons. ++ +You can then customize the submodule clone URLs in `.git/config` for your local setup and proceed to `git submodule update`; you can also just use `git submodule update --init` without the explicit 'init' step if you do not intend to customize @@ -143,6 +146,8 @@ the submodules. The "updating" can be done in several ways depending on command line options and the value of `submodule.<name>.update` configuration variable. The command line option takes precedence over the configuration variable. If neither is given, a 'checkout' is performed. +(note: what is in `.gitmodules` file is irrelevant at this point; +see `git submodule init` above for how `.gitmodules` is used). The 'update' procedures supported both from the command line as well as through the `submodule.<name>.update` configuration are: @@ -160,16 +165,18 @@ checked out in the submodule. merge;; the commit recorded in the superproject will be merged into the current branch in the submodule. -The following 'update' procedures are only available via the -`submodule.<name>.update` configuration variable: +The following update procedures have additional limitations: - custom command;; arbitrary shell command that takes a single - argument (the sha1 of the commit recorded in the - superproject) is executed. When `submodule.<name>.update` - is set to '!command', the remainder after the exclamation mark - is the custom command. + custom command;; mechanism for running arbitrary commands with the + commit ID as an argument. Specifically, if the + `submodule.<name>.update` configuration variable is set to + `!custom command`, the object name of the commit recorded in the + superproject for the submodule is appended to the `custom command` + string and executed. Note that this mechanism is not supported in + the `.gitmodules` file or on the command line. - none;; the submodule is not updated. + none;; the submodule is not updated. This update procedure is not + allowed on the command line. If the submodule is not yet initialized, and you just want to use the setting as stored in `.gitmodules`, you can automatically initialize the diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index f40202b8e3..c38fb3968b 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -71,6 +71,29 @@ endif::git-default-pager[] GIT_DEFAULT_BRANCH:: The name of the first branch created in newly initialized repositories. +GIT_SHELL_PATH:: + The path of the binary providing the POSIX shell for commands which use the shell. + +GIT_ATTR_SYSTEM:: + The path to the system linkgit:gitattributes[5] file, if one is enabled. + +GIT_ATTR_GLOBAL:: + The path to the global (per-user) linkgit:gitattributes[5] file. + +GIT_CONFIG_SYSTEM:: + The path to the system configuration file, if one is enabled. + +GIT_CONFIG_GLOBAL:: + The path to the global (per-user) configuration files, if any. + +Most path values contain only one value. However, some can contain multiple +values, which are separated by newlines, and are listed in order from highest to +lowest priority. Callers should be prepared for any such path value to contain +multiple items. + +Note that paths are printed even if they do not exist, but not if they are +disabled by other environment variables. + SEE ALSO -------- linkgit:git-commit-tree[1] diff --git a/Documentation/git.txt b/Documentation/git.txt index f0cafa2290..11228956cd 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -553,8 +553,8 @@ double-quotes and respecting backslash escapes. E.g., the value If this variable is set, the default hash algorithm for new repositories will be set to this value. This value is ignored when cloning and the setting of the remote repository - is always used. The default is "sha1". THIS VARIABLE IS - EXPERIMENTAL! See `--object-format` in linkgit:git-init[1]. + is always used. The default is "sha1". + See `--object-format` in linkgit:git-init[1]. Git Commits ~~~~~~~~~~~ diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 02a3ec83e4..6deb89a296 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -1132,7 +1132,10 @@ size (see below). The merge driver is expected to leave the result of the merge in the file named with `%A` by overwriting it, and exit with zero status if it managed to merge them cleanly, or non-zero if there -were conflicts. +were conflicts. When the driver crashes (e.g. killed by SEGV), +it is expected to exit with non-zero status that are higher than +128, and in such a case, the merge results in a failure (which is +different from producing a conflict). The `merge.*.recursive` variable specifies what other merge driver to use when the merge driver is called for an internal diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 65d652dc40..71dd19731a 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -104,6 +104,17 @@ $ git help credential-foo $ git config --global credential.helper foo ------------------------------------------- +=== Available helpers + +The community maintains a comprehensive list of Git credential helpers at +https://git-scm.com/doc/credential-helpers. + +=== OAuth + +An alternative to inputting passwords or personal access tokens is to use an +OAuth credential helper. Initial authentication opens a browser window to the +host. Subsequent authentication happens in the background. Many popular Git +hosts support OAuth. CREDENTIAL CONTEXTS ------------------- diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt index 0c1be2dbe8..870e00f298 100644 --- a/Documentation/gitformat-pack.txt +++ b/Documentation/gitformat-pack.txt @@ -588,51 +588,17 @@ later on. It is linkgit:git-gc[1] that is typically responsible for removing expired unreachable objects. -=== Caution for mixed-version environments - -Repositories that have cruft packs in them will continue to work with any older -version of Git. Note, however, that previous versions of Git which do not -understand the `.mtimes` file will use the cruft pack's mtime as the mtime for -all of the objects in it. In other words, do not expect older (pre-cruft pack) -versions of Git to interpret or even read the contents of the `.mtimes` file. - -Note that having mixed versions of Git GC-ing the same repository can lead to -unreachable objects never being completely pruned. This can happen under the -following circumstances: - - - An older version of Git running GC explodes the contents of an existing - cruft pack loose, using the cruft pack's mtime. - - A newer version running GC collects those loose objects into a cruft pack, - where the .mtime file reflects the loose object's actual mtimes, but the - cruft pack mtime is "now". - -Repeating this process will lead to unreachable objects not getting pruned as a -result of repeatedly resetting the objects' mtimes to the present time. - -If you are GC-ing repositories in a mixed version environment, consider omitting -the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and -setting the `gc.cruftPacks` configuration to "false" until all writers -understand cruft packs. - === Alternatives Notable alternatives to this design include: - - The location of the per-object mtime data, and - - Storing unreachable objects in multiple cruft packs. + - The location of the per-object mtime data. On the location of mtime data, a new auxiliary file tied to the pack was chosen to avoid complicating the `.idx` format. If the `.idx` format were ever to gain support for optional chunks of data, it may make sense to consolidate the `.mtimes` format into the `.idx` itself. -Storing unreachable objects among multiple cruft packs (e.g., creating a new -cruft pack during each repacking operation including only unreachable objects -which aren't already stored in an earlier cruft pack) is significantly more -complicated to construct, and so aren't pursued here. The obvious drawback to -the current implementation is that the entire cruft pack must be re-written from -scratch. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 4c17f2356c..5e0964ef41 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -88,7 +88,7 @@ PATTERN FORMAT Put a backslash ("`\`") in front of the first "`!`" for patterns that begin with a literal "`!`", for example, "`\!important!.txt`". - - The slash '/' is used as the directory separator. Separators may + - The slash "`/`" is used as the directory separator. Separators may occur at the beginning, middle or end of the `.gitignore` search pattern. - If there is a separator at the beginning or middle (or both) of the @@ -174,10 +174,10 @@ EXAMPLES is not relevant if there is already a middle slash in the pattern. - - The pattern "foo/*", matches "foo/test.json" - (a regular file), "foo/bar" (a directory), but it does not match - "foo/bar/hello.c" (a regular file), as the asterisk in the - pattern does not match "bar/hello.c" which has a slash in it. + - The pattern `foo/*`, matches `foo/test.json` + (a regular file), `foo/bar` (a directory), but it does not match + `foo/bar/hello.c` (a regular file), as the asterisk in the + pattern does not match `bar/hello.c` which has a slash in it. -------------------------------------------------------------- $ git status diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index dcee09b500..d9bec8b187 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -43,9 +43,9 @@ submodule.<name>.update:: command in the superproject. This is only used by `git submodule init` to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', - 'merge' or 'none'. See description of 'update' command in - linkgit:git-submodule[1] for their meaning. For security - reasons, the '!command' form is not accepted here. + 'merge' or 'none', but not '!command' (for security reasons). + See the description of the 'update' command in + linkgit:git-submodule[1] for more details. submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. diff --git a/Documentation/object-format-disclaimer.txt b/Documentation/object-format-disclaimer.txt index 4cb106f0d1..e561e6668c 100644 --- a/Documentation/object-format-disclaimer.txt +++ b/Documentation/object-format-disclaimer.txt @@ -1,6 +1,9 @@ -THIS OPTION IS EXPERIMENTAL! SHA-256 support is experimental and still -in an early stage. A SHA-256 repository will in general not be able to -share work with "regular" SHA-1 repositories. It should be assumed -that, e.g., Git internal file formats in relation to SHA-256 -repositories may change in backwards-incompatible ways. Only use -`--object-format=sha256` for testing purposes. +Note: At present, there is no interoperability between SHA-256 +repositories and SHA-1 repositories. + +Historically, we warned that SHA-256 repositories may later need +backward incompatible changes when we introduce such interoperability +features. Today, we only expect compatible changes. Furthermore, if such +changes prove to be necessary, it can be expected that SHA-256 repositories +created with today's Git will be usable by future versions of Git +without data loss. diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 3b71334459..d38b4ab566 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -122,7 +122,9 @@ The placeholders are: - Placeholders that expand to a single literal character: '%n':: newline '%%':: a raw '%' -'%x00':: print a byte from a hex code +'%x00':: '%x' followed by two hexadecimal digits is replaced with a + byte with the hexadecimal digits' value (we will call this + "literal formatting code" in the rest of this document). - Placeholders that affect formatting of later placeholders: '%Cred':: switch color to red @@ -222,13 +224,30 @@ The placeholders are: linkgit:git-rev-list[1]) '%d':: ref names, like the --decorate option of linkgit:git-log[1] '%D':: ref names without the " (", ")" wrapping. -'%(describe[:options])':: human-readable name, like - linkgit:git-describe[1]; empty string for - undescribable commits. The `describe` string - may be followed by a colon and zero or more - comma-separated options. Descriptions can be - inconsistent when tags are added or removed at - the same time. +'%(decorate[:<options>])':: +ref names with custom decorations. The `decorate` string may be followed by a +colon and zero or more comma-separated options. Option values may contain +literal formatting codes. These must be used for commas (`%x2C`) and closing +parentheses (`%x29`), due to their role in the option syntax. ++ +** 'prefix=<value>': Shown before the list of ref names. Defaults to "{nbsp}`(`". +** 'suffix=<value>': Shown after the list of ref names. Defaults to "`)`". +** 'separator=<value>': Shown between ref names. Defaults to "`,`{nbsp}". +** 'pointer=<value>': Shown between HEAD and the branch it points to, if any. + Defaults to "{nbsp}`->`{nbsp}". +** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}". + ++ +For example, to produce decorations with no wrapping +or tag annotations, and spaces as separators: ++ +`%(decorate:prefix=,suffix=,tag=,separator= )` + +'%(describe[:<options>])':: +human-readable name, like linkgit:git-describe[1]; empty string for +undescribable commits. The `describe` string may be followed by a colon and +zero or more comma-separated options. Descriptions can be inconsistent when +tags are added or removed at the same time. + ** 'tags[=<bool-value>]': Instead of only considering annotated tags, consider lightweight tags as well. @@ -281,13 +300,11 @@ endif::git-rev-list[] '%gE':: reflog identity email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) '%gs':: reflog subject -'%(trailers[:options])':: display the trailers of the body as - interpreted by - linkgit:git-interpret-trailers[1]. The - `trailers` string may be followed by a colon - and zero or more comma-separated options. - If any option is provided multiple times the - last occurrence wins. +'%(trailers[:<options>])':: +display the trailers of the body as interpreted by +linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by +a colon and zero or more comma-separated options. If any option is provided +multiple times, the last occurrence wins. + ** 'key=<key>': only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 3000888a90..a4a0cb93b2 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -236,10 +236,11 @@ ifndef::git-rev-list[] endif::git-rev-list[] --stdin:: - In addition to the '<commit>' listed on the command - line, read them from the standard input. If a `--` separator is - seen, stop reading commits and start reading paths to limit the - result. + In addition to getting arguments from the command line, read + them from standard input as well. This accepts commits and + pseudo-options like `--all` and `--glob=`. When a `--` separator + is seen, the following input is treated as paths and used to + limit the result. ifdef::git-rev-list[] --quiet:: diff --git a/Documentation/scalar.txt b/Documentation/scalar.txt index f33436c7f6..361f51a647 100644 --- a/Documentation/scalar.txt +++ b/Documentation/scalar.txt @@ -8,7 +8,8 @@ scalar - A tool for managing large Git repositories SYNOPSIS -------- [verse] -scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>] +scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] + [--[no-]src] <url> [<enlistment>] scalar list scalar register [<enlistment>] scalar unregister [<enlistment>] @@ -80,6 +81,11 @@ remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any branch when `--single-branch` clone was made, no remote-tracking branch is created. +--[no-]src:: + By default, `scalar clone` places the cloned repository within a + `<entlistment>/src` directory. Use `--no-src` to place the cloned + repository directly in the `<enlistment>` directory. + --[no-]full-clone:: A sparse-checkout is initialized by default. This behavior can be turned off via `--full-clone`. diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index 487d4d83ff..c2ba01828c 100644 --- a/Documentation/technical/api-merge.txt +++ b/Documentation/technical/api-merge.txt @@ -28,9 +28,9 @@ and `diff.c` for examples. * `struct ll_merge_options` -Check ll-merge.h for details. +Check merge-ll.h for details. Low-level (single file) merge ----------------------------- -Check ll-merge.h for details. +Check merge-ll.h for details. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index aa385137ad..4281396093 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -4129,13 +4129,11 @@ Note that terminology has changed since that revision. For example, the README in that revision uses the word "changeset" to describe what we now call a <<def_commit_object,commit>>. -Also, we do not call it "cache" any more, but rather "index"; however, the -file is still called `cache.h`. Remark: Not much reason to change it now, -especially since there is no good single name for it anyway, because it is -basically _the_ header file which is included by _all_ of Git's C sources. +Also, we do not call it "cache" any more, but rather "index"; however, +the file is still called `read-cache.h`. If you grasp the ideas in that initial commit, you should check out a -more recent version and skim `cache.h`, `object.h` and `commit.h`. +more recent version and skim `read-cache-ll.h`, `object.h` and `commit.h`. In the early days, Git (in the tradition of UNIX) was a bunch of programs which were extremely simple, and which you used in scripts, piping the @@ -4146,11 +4144,11 @@ many of these parts have become builtins, and some of the core has been and to avoid code duplication. By now, you know what the index is (and find the corresponding data -structures in `cache.h`), and that there are just a couple of object types -(blobs, trees, commits and tags) which inherit their common structure from -`struct object`, which is their first member (and thus, you can cast e.g. -`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e. -get at the object name and flags). +structures in `read-cache-ll.h`), and that there are just a couple of +object types (blobs, trees, commits and tags) which inherit their +common structure from `struct object`, which is their first member +(and thus, you can cast e.g. `(struct object *)commit` to achieve the +_same_ as `&commit->object`, i.e. get at the object name and flags). Now is a good point to take a break to let this information sink in. |