From 62908fd797899ccb5145cff3b16cc206d83b9b3f Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 4 Aug 2023 12:05:22 -0700 Subject: Autogenerated HTML docs for v2.42.0-rc0 --- MyFirstContribution.html | 39 +++++++- MyFirstContribution.txt | 32 ++++++ MyFirstObjectWalk.html | 2 +- RelNotes/2.42.0.txt | 23 +++++ ReviewingGuidelines.html | 2 +- SubmittingPatches.html | 141 ++++++++++++++++++++------- SubmittingPatches.txt | 141 +++++++++++++++++++-------- ToolsForGit.html | 2 +- everyday.html | 2 +- git-bisect-lk2009.html | 4 +- git-remote-helpers.html | 2 +- git-submodule.html | 32 +++--- git-submodule.txt | 31 +++--- git-tools.html | 4 +- gitmodules.html | 8 +- gitmodules.txt | 6 +- howto-index.html | 4 +- howto/coordinate-embargoed-releases.html | 2 +- howto/keep-canonical-history-correct.html | 4 +- howto/maintain-git.html | 4 +- howto/new-command.html | 4 +- howto/rebase-from-internal-branch.html | 4 +- howto/rebuild-from-update-hook.html | 4 +- howto/recover-corrupted-blob-object.html | 4 +- howto/recover-corrupted-object-harder.html | 4 +- howto/revert-a-faulty-merge.html | 4 +- howto/revert-branch-rebase.html | 4 +- howto/separating-topic-branches.html | 4 +- howto/setup-git-server-over-http.html | 4 +- howto/update-hook-example.html | 4 +- howto/use-git-daemon.html | 4 +- howto/using-merge-subtree.html | 4 +- howto/using-signed-tag-in-pull-request.html | 4 +- technical/api-error-handling.html | 2 +- technical/api-index.html | 4 +- technical/api-merge.html | 2 +- technical/api-parse-options.html | 2 +- technical/api-simple-ipc.html | 2 +- technical/api-trace2.html | 2 +- technical/bitmap-format.html | 2 +- technical/bundle-uri.html | 2 +- technical/hash-function-transition.html | 2 +- technical/long-running-process-protocol.html | 2 +- technical/multi-pack-index.html | 2 +- technical/pack-heuristics.html | 2 +- technical/parallel-checkout.html | 2 +- technical/partial-clone.html | 2 +- technical/racy-git.html | 2 +- technical/scalar.html | 2 +- technical/send-pack-pipeline.html | 2 +- technical/shallow.html | 2 +- technical/trivial-merge.html | 2 +- user-manual.html | 2 +- 53 files changed, 406 insertions(+), 173 deletions(-) diff --git a/MyFirstContribution.html b/MyFirstContribution.html index a97d70315..1224ab484 100644 --- a/MyFirstContribution.html +++ b/MyFirstContribution.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -1973,6 +1973,41 @@ index 88f126184c..38da593a60 100644

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.

Responding to Reviews

After a few days, you will hopefully receive a reply to your patchset with some @@ -2061,7 +2096,7 @@ should generate your diffs from <topic>..<mybranch> and

diff --git a/MyFirstContribution.txt b/MyFirstContribution.txt index 56130e4be..62d11a5cd 100644 --- a/MyFirstContribution.txt +++ b/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/MyFirstObjectWalk.html b/MyFirstObjectWalk.html index f25d0ad03..0717e5abd 100644 --- a/MyFirstObjectWalk.html +++ b/MyFirstObjectWalk.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/RelNotes/2.42.0.txt b/RelNotes/2.42.0.txt index 340f55b23..0d31aed9f 100644 --- a/RelNotes/2.42.0.txt +++ b/RelNotes/2.42.0.txt @@ -30,6 +30,14 @@ UI, Workflows & Features 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". + Performance, Internal Implementation, Development Support etc. @@ -73,6 +81,17 @@ Performance, Internal Implementation, Development Support etc. * "git branch --list --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 ----------------- @@ -229,6 +248,10 @@ Fixes since v2.41 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..update configuration variable. + (merge 7cebc5bd78 pv/doc-submodule-update-settings 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). diff --git a/ReviewingGuidelines.html b/ReviewingGuidelines.html index 8f5b6be00..c3561365b 100644 --- a/ReviewingGuidelines.html +++ b/ReviewingGuidelines.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/SubmittingPatches.html b/SubmittingPatches.html index 9fafcac83..5e37659cd 100644 --- a/SubmittingPatches.html +++ b/SubmittingPatches.html @@ -735,65 +735,127 @@ asciidoc.install();

Guidelines

-

Here are some guidelines for people who want to contribute their code to this -software. There is also a step-by-step tutorial +

Here are some guidelines for contributing back to this +project. There is also a step-by-step tutorial available which covers many of these same guidelines.

-

Decide what to base your work on.

-

In general, always base your work on the oldest branch that your -change is relevant to.

+

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 gitworkflows(7):

  • -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. +maint

  • -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... +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. +next

  • -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). +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 +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:

+

  • -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. +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.

-

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.

+
+ + + +
+
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 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).

Make separate commits for logically separate changes.

@@ -1096,10 +1158,19 @@ receiving end can handle them just fine.

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.
+

Sending your patches.

@@ -1447,7 +1518,7 @@ this problem around.

diff --git a/SubmittingPatches.txt b/SubmittingPatches.txt index b218e2735..973d7a81d 100644 --- a/SubmittingPatches.txt +++ b/SubmittingPatches.txt @@ -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/ToolsForGit.html b/ToolsForGit.html index f2de70cd4..06299a1ef 100644 --- a/ToolsForGit.html +++ b/ToolsForGit.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/everyday.html b/everyday.html index c7070742f..2717d8b65 100644 --- a/everyday.html +++ b/everyday.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/git-bisect-lk2009.html b/git-bisect-lk2009.html index 65a83894e..06c67ba23 100644 --- a/git-bisect-lk2009.html +++ b/git-bisect-lk2009.html @@ -737,7 +737,7 @@ asciidoc.install();

Fighting regressions with git bisect

Christian Couder
<chriscool@tuxfamily.org>
-2023-06-01 +2023-08-04
@@ -1983,7 +1983,7 @@ author to given a talk and for publishing this paper.

diff --git a/git-remote-helpers.html b/git-remote-helpers.html index e69038407..59617df48 100644 --- a/git-remote-helpers.html +++ b/git-remote-helpers.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/git-submodule.html b/git-submodule.html index a1034c215..5ca592e05 100644 --- a/git-submodule.html +++ b/git-submodule.html @@ -846,7 +846,7 @@ 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. @@ -855,9 +855,11 @@ init [--] [<path>…] 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 @@ -897,6 +899,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:

@@ -932,19 +936,20 @@ the commit recorded in the superproject will be merged

-

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. +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.

@@ -952,7 +957,8 @@ none

-the submodule is not updated. +the submodule is not updated. This update procedure is not + allowed on the command line.

@@ -1410,7 +1416,7 @@ for details.

diff --git a/git-submodule.txt b/git-submodule.txt index 4d3ab6b9f..695730609 100644 --- a/git-submodule.txt +++ b/git-submodule.txt @@ -95,7 +95,7 @@ too (and can also report changes to a submodule's work tree). init [--] [...]:: 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..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..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..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..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..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/git-tools.html b/git-tools.html index bdbb4cde6..a0e71ed9b 100644 --- a/git-tools.html +++ b/git-tools.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -753,7 +753,7 @@ more efficiently, so this manually-maintained list has been retired.

diff --git a/gitmodules.html b/gitmodules.html index 810766457..a5fae00b2 100644 --- a/gitmodules.html +++ b/gitmodules.html @@ -798,9 +798,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 - 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 + git-submodule(1) for more details.

@@ -948,7 +948,7 @@ submodules a URL is specified which can be used for cloning the submodules.

< diff --git a/gitmodules.txt b/gitmodules.txt index dcee09b50..d9bec8b18 100644 --- a/gitmodules.txt +++ b/gitmodules.txt @@ -43,9 +43,9 @@ submodule..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..branch:: A remote branch name for tracking updates in the upstream submodule. diff --git a/howto-index.html b/howto-index.html index 9d4096c50..d5c9a0cfa 100644 --- a/howto-index.html +++ b/howto-index.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -896,7 +896,7 @@ later validate it.

diff --git a/howto/coordinate-embargoed-releases.html b/howto/coordinate-embargoed-releases.html index 81b9e7a8c..12721e7b9 100644 --- a/howto/coordinate-embargoed-releases.html +++ b/howto/coordinate-embargoed-releases.html @@ -1038,7 +1038,7 @@ Thanks, diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html index 53df16254..9f4fa9e93 100644 --- a/howto/keep-canonical-history-correct.html +++ b/howto/keep-canonical-history-correct.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -939,7 +939,7 @@ tip of your master again and redo the two merges:

diff --git a/howto/maintain-git.html b/howto/maintain-git.html index 92957c4fb..1c11ee92f 100644 --- a/howto/maintain-git.html +++ b/howto/maintain-git.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -1479,7 +1479,7 @@ $ git update-ref -d $mf/ai/topic diff --git a/howto/new-command.html b/howto/new-command.html index eaba91f9c..57091f054 100644 --- a/howto/new-command.html +++ b/howto/new-command.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -864,7 +864,7 @@ letter [PATCH 0/n]. diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html index 80c679e0b..45cfa7bc8 100644 --- a/howto/rebase-from-internal-branch.html +++ b/howto/rebase-from-internal-branch.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -896,7 +896,7 @@ the #1' commit.

diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html index 59a2c607b..ec69c44db 100644 --- a/howto/rebuild-from-update-hook.html +++ b/howto/rebuild-from-update-hook.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -848,7 +848,7 @@ This is still crude and does not protect against simultaneous diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html index dd59e43e2..5a9fb393a 100644 --- a/howto/recover-corrupted-blob-object.html +++ b/howto/recover-corrupted-blob-object.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -881,7 +881,7 @@ thing.

diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html index 069ce383e..2af0a8ecb 100644 --- a/howto/recover-corrupted-object-harder.html +++ b/howto/recover-corrupted-object-harder.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -1190,7 +1190,7 @@ int main(int argc, char **argv) diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html index 306d98dd1..6fcb13c12 100644 --- a/howto/revert-a-faulty-merge.html +++ b/howto/revert-a-faulty-merge.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -1026,7 +1026,7 @@ P---o---o---M---x---x---W---x---M2 diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html index 8a8a0e98b..cb82b8735 100644 --- a/howto/revert-branch-rebase.html +++ b/howto/revert-branch-rebase.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -908,7 +908,7 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html index 684cac325..0cf1603b5 100644 --- a/howto/separating-topic-branches.html +++ b/howto/separating-topic-branches.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -842,7 +842,7 @@ o---o"master" diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index 102756562..c7354f319 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -1072,7 +1072,7 @@ help diagnosing the problem, but removes security checks.

diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html index e5fe09e81..151c4682f 100644 --- a/howto/update-hook-example.html +++ b/howto/update-hook-example.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -931,7 +931,7 @@ that JC can make non-fast-forward pushes on it.

diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html index ff312f4ce..3eca27f55 100644 --- a/howto/use-git-daemon.html +++ b/howto/use-git-daemon.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -792,7 +792,7 @@ a good practice to put the paths after a "--" separator.

diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html index 140bc4b92..4eb481738 100644 --- a/howto/using-merge-subtree.html +++ b/howto/using-merge-subtree.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -849,7 +849,7 @@ Please note that if the other project merges from you, then it will diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html index d83604540..8709b222b 100644 --- a/howto/using-signed-tag-in-pull-request.html +++ b/howto/using-signed-tag-in-pull-request.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -953,7 +953,7 @@ as part of the merge commit.

diff --git a/technical/api-error-handling.html b/technical/api-error-handling.html index 30791ab04..24ec33c91 100644 --- a/technical/api-error-handling.html +++ b/technical/api-error-handling.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/api-index.html b/technical/api-index.html index 4b0617b67..5200b4cac 100644 --- a/technical/api-index.html +++ b/technical/api-index.html @@ -735,7 +735,7 @@ asciidoc.install();
@@ -776,7 +776,7 @@ documents them.

diff --git a/technical/api-merge.html b/technical/api-merge.html index 1d6101078..d8e8592e6 100644 --- a/technical/api-merge.html +++ b/technical/api-merge.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/api-parse-options.html b/technical/api-parse-options.html index 7ff9d5668..95402e995 100644 --- a/technical/api-parse-options.html +++ b/technical/api-parse-options.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/api-simple-ipc.html b/technical/api-simple-ipc.html index c39a18342..b6250b4fc 100644 --- a/technical/api-simple-ipc.html +++ b/technical/api-simple-ipc.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/api-trace2.html b/technical/api-trace2.html index 3a398afca..6e3b3957b 100644 --- a/technical/api-trace2.html +++ b/technical/api-trace2.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/bitmap-format.html b/technical/bitmap-format.html index c1de78a9d..22f485aa8 100644 --- a/technical/bitmap-format.html +++ b/technical/bitmap-format.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/bundle-uri.html b/technical/bundle-uri.html index bc8448f17..8e73b8ee6 100644 --- a/technical/bundle-uri.html +++ b/technical/bundle-uri.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/hash-function-transition.html b/technical/hash-function-transition.html index dd8920275..191f05ad4 100644 --- a/technical/hash-function-transition.html +++ b/technical/hash-function-transition.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/long-running-process-protocol.html b/technical/long-running-process-protocol.html index b4a880377..916e5e128 100644 --- a/technical/long-running-process-protocol.html +++ b/technical/long-running-process-protocol.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/multi-pack-index.html b/technical/multi-pack-index.html index 854d63562..18d4606d0 100644 --- a/technical/multi-pack-index.html +++ b/technical/multi-pack-index.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/pack-heuristics.html b/technical/pack-heuristics.html index be42f4467..e81529620 100644 --- a/technical/pack-heuristics.html +++ b/technical/pack-heuristics.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/parallel-checkout.html b/technical/parallel-checkout.html index 11500f72f..fa4ab7a0b 100644 --- a/technical/parallel-checkout.html +++ b/technical/parallel-checkout.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/partial-clone.html b/technical/partial-clone.html index da7bce4cf..defd82b36 100644 --- a/technical/partial-clone.html +++ b/technical/partial-clone.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/racy-git.html b/technical/racy-git.html index d919aa145..829d41f73 100644 --- a/technical/racy-git.html +++ b/technical/racy-git.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/scalar.html b/technical/scalar.html index 7daadf137..2bd52654d 100644 --- a/technical/scalar.html +++ b/technical/scalar.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/send-pack-pipeline.html b/technical/send-pack-pipeline.html index 289bdbc26..228469cf9 100644 --- a/technical/send-pack-pipeline.html +++ b/technical/send-pack-pipeline.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/shallow.html b/technical/shallow.html index 98b1878a9..a5f2fbd6f 100644 --- a/technical/shallow.html +++ b/technical/shallow.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/technical/trivial-merge.html b/technical/trivial-merge.html index 92f8da0f1..ccbe2e79e 100644 --- a/technical/trivial-merge.html +++ b/technical/trivial-merge.html @@ -735,7 +735,7 @@ asciidoc.install();
diff --git a/user-manual.html b/user-manual.html index a2e89797c..af9bbe561 100644 --- a/user-manual.html +++ b/user-manual.html @@ -1,5 +1,5 @@ -Git User Manual

Git User Manual

Revision History
2023-08-02

Table of Contents

Introduction
1. Repositories and Branches
How to get a Git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring Git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with Git
Telling Git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by rewriting history
Checking out an old version of a file
Temporarily setting aside work in progress
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public Git repositories
Setting up a public repository
Exporting a Git repository via the Git protocol
Exporting a git repository via HTTP
Pushing changes to a public repository
What to do when a push fails
Setting up a shared repository
Allowing web browsing of a repository
How to get a Git repository with minimal history
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git rebase
Rewriting a single commit
Reordering or selecting from a patch series
Using interactive rebases
Other tools
Problems with rewriting history
Why bisecting merge commits can be harder than bisecting linear history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote-tracking branches
7. Git concepts
The Object Database
Commit Object
Tree Object
Blob Object
Trust
Tag Object
How Git stores objects efficiently: pack files
Dangling objects
Recovering from repository corruption
The index
8. Submodules
Pitfalls with submodules
9. Low-level Git operations
Object access and manipulation
The Workflow
working directory → index
index → object database
object database → index
index → working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
10. Hacking Git
Object storage format
A birds-eye view of Git’s source code
11. Git Glossary
Git explained
A. Git Quick Reference
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual
Todo list

Introduction

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic UNIX +Git User Manual

Git User Manual

Revision History
2023-08-04

Table of Contents

Introduction
1. Repositories and Branches
How to get a Git repository
How to check out a different version of a project
Understanding History: Commits
Understanding history: commits, parents, and reachability
Understanding history: History diagrams
Understanding history: What is a branch?
Manipulating branches
Examining an old version without creating a new branch
Examining branches from a remote repository
Naming branches, tags, and other references
Updating a repository with git fetch
Fetching branches from other repositories
2. Exploring Git history
How to use bisect to find a regression
Naming commits
Creating tags
Browsing revisions
Generating diffs
Viewing old file versions
Examples
Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release
Finding commits referencing a file with given content
3. Developing with Git
Telling Git your name
Creating a new repository
How to make a commit
Creating good commit messages
Ignoring files
How to merge
Resolving a merge
Getting conflict-resolution help during a merge
Undoing a merge
Fast-forward merges
Fixing mistakes
Fixing a mistake with a new commit
Fixing a mistake by rewriting history
Checking out an old version of a file
Temporarily setting aside work in progress
Ensuring good performance
Ensuring reliability
Checking the repository for corruption
Recovering lost changes
4. Sharing development with others
Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Public Git repositories
Setting up a public repository
Exporting a Git repository via the Git protocol
Exporting a git repository via HTTP
Pushing changes to a public repository
What to do when a push fails
Setting up a shared repository
Allowing web browsing of a repository
How to get a Git repository with minimal history
Examples
Maintaining topic branches for a Linux subsystem maintainer
5. Rewriting history and maintaining patch series
Creating the perfect patch series
Keeping a patch series up to date using git rebase
Rewriting a single commit
Reordering or selecting from a patch series
Using interactive rebases
Other tools
Problems with rewriting history
Why bisecting merge commits can be harder than bisecting linear history
6. Advanced branch management
Fetching individual branches
git fetch and fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote-tracking branches
7. Git concepts
The Object Database
Commit Object
Tree Object
Blob Object
Trust
Tag Object
How Git stores objects efficiently: pack files
Dangling objects
Recovering from repository corruption
The index
8. Submodules
Pitfalls with submodules
9. Low-level Git operations
Object access and manipulation
The Workflow
working directory → index
index → object database
object database → index
index → working directory
Tying it all together
Examining the data
Merging multiple trees
Merging multiple trees, continued
10. Hacking Git
Object storage format
A birds-eye view of Git’s source code
11. Git Glossary
Git explained
A. Git Quick Reference
Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance
B. Notes and todo list for this manual
Todo list

Introduction

Git is a fast distributed revision control system.

This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git.

Chapter 1, Repositories and Branches and Chapter 2, Exploring Git history explain how to fetch and study a project using git—read these chapters to learn how to build and test a particular version of a software project, search for -- cgit 1.2.3-korg