From 01ead411966a83dfcfb35f9d2e8a9f7f215eaa65 Mon Sep 17 00:00:00 2001
From: Elijah Newren
Date: Mon, 10 Oct 2022 11:10:14 -0700
Subject: [PATCH] Update docs to cbc6535694380d3a3bf3e5c96410d4ce7e8de94f
---
html/MyFirstContribution.html | 220 ++-
html/MyFirstObjectWalk.html | 89 +-
html/ReviewingGuidelines.html | 981 +++++++++++++
html/SubmittingPatches.html | 114 +-
html/ToolsForGit.html | 812 +++++++++++
html/everyday.html | 2 +-
html/git-add.html | 41 +-
html/git-am.html | 72 +-
html/git-annotate.html | 2 +-
html/git-apply.html | 41 +-
html/git-archimport.html | 16 +-
html/git-archive.html | 61 +-
html/git-bisect-lk2009.html | 2 +-
html/git-bisect.html | 2 +-
html/git-blame.html | 90 +-
html/git-branch.html | 204 ++-
html/git-bugreport.html | 27 +-
html/git-bundle.html | 23 +-
html/git-cat-file.html | 99 +-
html/git-check-attr.html | 2 +-
html/git-check-ignore.html | 6 +-
html/git-check-mailmap.html | 2 +-
html/git-check-ref-format.html | 2 +-
html/git-checkout-index.html | 17 +-
html/git-checkout.html | 116 +-
html/git-cherry-pick.html | 17 +-
html/git-cherry.html | 2 +-
html/git-citool.html | 2 +-
html/git-clean.html | 21 +-
html/git-clone.html | 99 +-
html/git-column.html | 144 +-
html/git-commit-graph.html | 48 +-
html/git-commit-tree.html | 8 +-
html/git-commit.html | 67 +-
html/git-config.html | 1855 ++++++++++++++++++------
html/git-count-objects.html | 2 +-
html/git-credential-cache--daemon.html | 8 +-
html/git-credential-cache.html | 2 +-
html/git-credential-store.html | 2 +-
html/git-credential.html | 4 +-
html/git-cvsexportcommit.html | 6 +-
html/git-cvsimport.html | 10 +-
html/git-cvsserver.html | 34 +-
html/git-daemon.html | 23 +-
html/git-describe.html | 2 +-
html/git-diagnose.html | 865 +++++++++++
html/git-diff-files.html | 17 +-
html/git-diff-index.html | 23 +-
html/git-diff-tree.html | 91 +-
html/git-diff.html | 664 ++++++++-
html/git-difftool.html | 47 +-
html/git-fast-export.html | 2 +-
html/git-fast-import.html | 26 +-
html/git-fetch-pack.html | 11 +-
html/git-fetch.html | 228 ++-
html/git-filter-branch.html | 2 +-
html/git-filter-repo.html | 18 +-
html/git-fmt-merge-msg.html | 13 +-
html/git-for-each-ref.html | 2 +-
html/git-for-each-repo.html | 2 +-
html/git-format-patch.html | 29 +-
html/git-fsck-objects.html | 2 +-
html/git-fsck.html | 7 +-
html/git-fsmonitor--daemon.html | 855 +++++++++++
html/git-gc.html | 42 +-
html/git-get-tar-commit-id.html | 2 +-
html/git-grep.html | 24 +-
html/git-gui.html | 4 +-
html/git-hash-object.html | 2 +-
html/git-help.html | 64 +-
html/git-hook.html | 821 +++++++++++
html/git-http-backend.html | 2 +-
html/git-http-fetch.html | 4 +-
html/git-http-push.html | 17 +-
html/git-imap-send.html | 5 +-
html/git-index-pack.html | 15 +-
html/git-init-db.html | 4 +-
html/git-init.html | 57 +-
html/git-instaweb.html | 2 +-
html/git-interpret-trailers.html | 12 +-
html/git-log.html | 398 +++--
html/git-ls-files.html | 108 +-
html/git-ls-remote.html | 2 +-
html/git-ls-tree.html | 108 +-
html/git-mailinfo.html | 24 +-
html/git-mailsplit.html | 2 +-
html/git-maintenance.html | 187 ++-
html/git-merge-base.html | 2 +-
html/git-merge-file.html | 10 +-
html/git-merge-index.html | 4 +-
html/git-merge-one-file.html | 2 +-
html/git-merge-tree.html | 299 +++-
html/git-merge.html | 390 +++--
html/git-mergetool--lib.html | 2 +-
html/git-mergetool.html | 284 +++-
html/git-mktag.html | 2 +-
html/git-mktree.html | 4 +-
html/git-multi-pack-index.html | 6 +-
html/git-mv.html | 2 +-
html/git-name-rev.html | 36 +-
html/git-notes.html | 54 +-
html/git-p4.html | 57 +-
html/git-pack-objects.html | 44 +-
html/git-pack-redundant.html | 4 +-
html/git-pack-refs.html | 2 +-
html/git-patch-id.html | 2 +-
html/git-prune-packed.html | 2 +-
html/git-prune.html | 2 +-
html/git-pull.html | 13 +-
html/git-push.html | 222 ++-
html/git-quiltimport.html | 2 +-
html/git-range-diff.html | 7 +-
html/git-read-tree.html | 20 +-
html/git-rebase.html | 302 ++--
html/git-receive-pack.html | 2 +-
html/git-reflog.html | 6 +-
html/git-remote-ext.html | 2 +-
html/git-remote-fd.html | 2 +-
html/git-remote-helpers.html | 2 +-
html/git-remote.html | 14 +-
html/git-repack.html | 30 +-
html/git-replace.html | 2 +-
html/git-request-pull.html | 10 +-
html/git-rerere.html | 2 +-
html/git-reset.html | 16 +-
html/git-restore.html | 5 +-
html/git-rev-list.html | 163 ++-
html/git-rev-parse.html | 18 +-
html/git-revert.html | 43 +-
html/git-rm.html | 2 +-
html/git-send-email.html | 181 ++-
html/git-send-pack.html | 2 +-
html/git-sh-i18n--envsubst.html | 2 +-
html/git-sh-i18n.html | 2 +-
html/git-sh-setup.html | 2 +-
html/git-shell.html | 2 +-
html/git-shortlog.html | 90 +-
html/git-show-branch.html | 21 +-
html/git-show-index.html | 2 +-
html/git-show-ref.html | 2 +-
html/git-show.html | 105 +-
html/git-sparse-checkout.html | 473 ++++--
html/git-stage.html | 4 +-
html/git-stash.html | 85 +-
html/git-status.html | 11 +-
html/git-stripspace.html | 2 +-
html/git-submodule.html | 7 +-
html/git-svn.html | 4 +-
html/git-switch.html | 80 +-
html/git-symbolic-ref.html | 2 +-
html/git-tag.html | 8 +-
html/git-tools.html | 2 +-
html/git-unpack-file.html | 2 +-
html/git-unpack-objects.html | 2 +-
html/git-update-index.html | 62 +-
html/git-update-ref.html | 2 +-
html/git-update-server-info.html | 2 +-
html/git-upload-archive.html | 2 +-
html/git-upload-pack.html | 9 +-
html/git-var.html | 10 +-
html/git-verify-commit.html | 2 +-
html/git-verify-pack.html | 2 +-
html/git-verify-tag.html | 2 +-
html/git-version.html | 2 +-
html/git-web--browse.html | 4 +-
html/git-whatchanged.html | 2 +-
html/git-worktree.html | 295 ++--
html/git-write-tree.html | 2 +-
html/git.html | 227 ++-
html/gitattributes.html | 19 +-
html/gitcli.html | 24 +-
html/gitcore-tutorial.html | 2 +-
html/gitcredentials.html | 6 +-
html/gitcvs-migration.html | 2 +-
html/gitdiffcore.html | 2 +-
html/giteveryday.html | 2 +-
html/gitfaq.html | 2 +-
html/gitformat-bundle.html | 886 +++++++++++
html/gitformat-chunk.html | 895 ++++++++++++
html/gitformat-commit-graph.html | 1083 ++++++++++++++
html/gitformat-index.html | 1496 +++++++++++++++++++
html/gitformat-pack.html | 1602 ++++++++++++++++++++
html/gitformat-signature.html | 1042 +++++++++++++
html/gitglossary.html | 20 +-
html/githooks.html | 8 +-
html/gitignore.html | 2 +-
html/gitk.html | 2 +-
html/gitmailmap.html | 2 +-
html/gitmodules.html | 2 +-
html/gitnamespaces.html | 2 +-
html/gitprotocol-capabilities.html | 1161 +++++++++++++++
html/gitprotocol-common.html | 896 ++++++++++++
html/gitprotocol-http.html | 1286 ++++++++++++++++
html/gitprotocol-pack.html | 1501 +++++++++++++++++++
html/gitprotocol-v2.html | 1504 +++++++++++++++++++
html/gitremote-helpers.html | 21 +-
html/gitrepository-layout.html | 2 +-
html/gitrevisions.html | 18 +-
html/gitsubmodules.html | 4 +-
html/gittutorial-2.html | 2 +-
html/gittutorial.html | 2 +-
html/gitweb.conf.html | 2 +-
html/gitweb.html | 2 +-
html/gitworkflows.html | 8 +-
html/howto-index.html | 2 +-
html/scalar.html | 995 +++++++++++++
html/user-manual.html | 16 +-
man1/git-filter-repo.1 | 20 +-
208 files changed, 26619 insertions(+), 1946 deletions(-)
create mode 100644 html/ReviewingGuidelines.html
create mode 100644 html/ToolsForGit.html
create mode 100644 html/git-diagnose.html
create mode 100644 html/git-fsmonitor--daemon.html
create mode 100644 html/git-hook.html
create mode 100644 html/gitformat-bundle.html
create mode 100644 html/gitformat-chunk.html
create mode 100644 html/gitformat-commit-graph.html
create mode 100644 html/gitformat-index.html
create mode 100644 html/gitformat-pack.html
create mode 100644 html/gitformat-signature.html
create mode 100644 html/gitprotocol-capabilities.html
create mode 100644 html/gitprotocol-common.html
create mode 100644 html/gitprotocol-http.html
create mode 100644 html/gitprotocol-pack.html
create mode 100644 html/gitprotocol-v2.html
create mode 100644 html/scalar.html
diff --git a/html/MyFirstContribution.html b/html/MyFirstContribution.html
index af8a717..04e9019 100644
--- a/html/MyFirstContribution.html
+++ b/html/MyFirstContribution.html
@@ -1427,13 +1427,111 @@ dependencies. prove
also makes the output nicer.
-
Getting Ready to Share
+
Getting Ready to Share: Anatomy of a Patch Series
You may have noticed already that the Git project performs its code reviews via
emailed patches, which are then applied by the maintainer when they are ready
-and approved by the community. The Git project does not accept patches from
+and approved by the community. The Git project does not accept contributions from
pull requests, and the patches emailed for review need to be formatted a
-specific way. At this point the tutorial diverges, in order to demonstrate two
+specific way.
+
Before taking a look at how to convert your commits into emailed patches,
+let’s analyze what the end result, a "patch series", looks like. Here is an
+example of the summary view for a patch series on the web interface of
+the Git mailing list archive:
+
+
+
2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget
+2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget
+2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message]
+2022-02-18 19:39 ` Taylor Blau
+2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason
+2022-02-18 19:35 ` Taylor Blau
+2022-02-21 1:43 ` John Cai
+2022-02-21 1:50 ` Taylor Blau
+2022-02-23 19:50 ` John Cai
+2022-02-18 20:00 ` // other replies ellided
+2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget
+2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason
+2022-02-18 20:26 ` Junio C Hamano
+2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget
+2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason
+2022-02-19 0:21 ` Taylor Blau
+2022-02-22 2:36 ` John Cai
+2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason
+2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason
+2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget
+2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget
+2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason
+2022-02-23 21:27 ` Junio C Hamano
+// continued
+
+
We can note a few things:
+
+-
+
+Each commit is sent as a separate email, with the commit message title as
+ subject, prefixed with "[PATCH i/n]" for the i-th commit of an
+ n-commit series.
+
+
+-
+
+Each patch is sent as a reply to an introductory email called the cover
+ letter of the series, prefixed "[PATCH 0/n]".
+
+
+-
+
+Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH
+ v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of
+ three patches in the second iteration. Each iteration is sent with a new cover
+ letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the
+ previous iteration (more on that below).
+
+
+
+
+
+
+ Note
+ |
+A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without
+i/n numbering (in the above thread overview, no single-patch topic appears,
+though). |
+
+
+
+
The cover letter
+
In addition to an email per patch, the Git community also expects your patches
+to come with a cover letter. This is an important component of change
+submission as it explains to the community from a high level what you’re trying
+to do, and why, in a way that’s more apparent than just looking at your
+patches.
+
The title of your cover letter should be something which succinctly covers the
+purpose of your entire topic branch. It’s often in the imperative mood, just
+like our commit message titles. Here is how we’ll title our series:
+
---
+Add the psuh command
+---
+
The body of the cover letter is used to give additional context to reviewers.
+Be sure to explain anything your patches don’t make clear on their own, but
+remember that since the cover letter is not recorded in the commit history,
+anything that might be useful to future readers of the repository’s history
+should also be in your commit messages.
+
Here’s an example body for psuh
:
+
+
+
Our internal metrics indicate widespread interest in the command
+git-psuh - that is, many users are trying to use it, but finding it is
+unavailable, using some unknown workaround instead.
+
+The following handful of patches add the psuh command and implement some
+handy features on top of it.
+
+This patchset is part of the MyFirstContribution tutorial and should not
+be merged.
+
+
At this point the tutorial diverges, in order to demonstrate two
different methods of formatting your patchset and getting it reviewed.
The first method to be covered is GitGitGadget, which is useful for those
already familiar with GitHub’s common pull request workflow. This method
@@ -1447,6 +1545,7 @@ the same; the review process will be covered after the sections on GitGitGadget
and git send-email
.
+
Sending Patches via GitGitGadget
@@ -1511,8 +1610,27 @@ opening a Pull Request against
gitgitgadget/git
. Head to
https://github.com/gitgitgadget/git and open a PR either with the "New pull
request" button or the convenient "Compare & pull request" button that may
appear with the name of your newly pushed branch.
-
Review the PR’s title and description, as it’s used by GitGitGadget as the cover
-letter for your change. When you’re happy, submit your pull request.
+
Review the PR’s title and description, as they’re used by GitGitGadget
+respectively as the subject and body of the cover letter for your change. Refer
+to "The cover letter" above for advice on how to title your
+submission and what content to include in the description.
+
+
+
+ Note
+ |
+For single-patch contributions, your commit message should already be
+meaningful and explain at a high level the purpose (what is happening and why)
+of your patch, so you usually do not need any additional context. In that case,
+remove the PR description that GitHub automatically generates from your commit
+message (your PR description should be empty). If you do need to supply even
+more context, you can do so in that space and it will be appended to the email
+that GitGitGadget will send, between the three-dash line and the diffstat
+(see Bonus Chapter: One-Patch Changes for how this looks once
+submitted). |
+
+
+
When you’re happy, submit your pull request.
Running CI and Getting Ready to Send
@@ -1598,16 +1716,47 @@ is out of scope for the context of this tutorial.
themselves, you’ll need to prepare the patches. Luckily, this is pretty simple:
-
$ git format-patch --cover-letter -o psuh/ master..psuh
+
$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh
-The --cover-letter
parameter tells format-patch
to create a cover letter
-template for you. You will need to fill in the template before you’re ready
-to send - but for now, the template will be next to your other patches.
-The -o psuh/
parameter tells format-patch
to place the patch files into a
-directory. This is useful because git send-email
can take a directory and
-send out all the patches from there.
-master..psuh
tells format-patch
to generate patches for the difference
-between master
and psuh
. It will make one patch file per commit. After you
+
+-
+
+The --cover-letter
option tells format-patch
to create a
+ cover letter template for you. You will need to fill in the
+ template before you’re ready to send - but for now, the template
+ will be next to your other patches.
+
+
+-
+
+The -o psuh/
option tells format-patch
to place the patch
+ files into a directory. This is useful because git send-email
+ can take a directory and send out all the patches from there.
+
+
+-
+
+The --base=auto
option tells the command to record the "base
+ commit", on which the recipient is expected to apply the patch
+ series. The auto
value will cause format-patch
to compute
+ the base commit automatically, which is the merge base of tip
+ commit of the remote-tracking branch and the specified revision
+ range.
+
+
+-
+
+The psuh@{u}..psuh
option tells format-patch
to generate
+ patches for the commits you created on the psuh
branch since it
+ forked from its upstream (which is origin/master
if you
+ followed the example in the "Set up your workspace" section). If
+ you are already on the psuh
branch, you can just say @{u}
,
+ which means "commits on the current branch since it forked from
+ its upstream", which is the same thing.
+
+
+
+
The command will make one patch file per commit. After you
run, you can go have a look at each of the patches with your favorite text
editor and make sure everything looks alright; however, it’s not recommended to
make code fixups via the patch file. It’s a better idea to make the change the
@@ -1633,42 +1782,23 @@ but want reviewers to look at what they have so far. You can add this flag with
directory you specified - you’re nearly ready to send out your review!
-
Preparing Email
-
In addition to an email per patch, the Git community also expects your patches
-to come with a cover letter, typically with a subject line [PATCH 0/x] (where
-x is the number of patches you’re sending). Since you invoked format-patch
-with --cover-letter
, you’ve already got a template ready. Open it up in your
-favorite editor.
+
Preparing Email
+
Since you invoked format-patch
with --cover-letter
, you’ve already got a
+cover letter template ready. Open it up in your favorite editor.
You should see a number of headers present already. Check that your From:
-header is correct. Then modify your Subject:
to something which succinctly
-covers the purpose of your entire topic branch, for example:
+header is correct. Then modify your
Subject:
(see
above for
+how to choose good title for your patch series):
-
Subject: [PATCH 0/7] adding the 'psuh' command
+
Subject: [PATCH 0/7] Add the 'psuh' command
Make sure you retain the “[PATCH 0/X]” part; that’s what indicates to the Git
-community that this email is the beginning of a review, and many reviewers
-filter their email for this type of flag.
+community that this email is the beginning of a patch series, and many
+reviewers filter their email for this type of flag.
You’ll need to add some extra parameters when you invoke git send-email
to add
the cover letter.
-Next you’ll have to fill out the body of your cover letter. This is an important
-component of change submission as it explains to the community from a high level
-what you’re trying to do, and why, in a way that’s more apparent than just
-looking at your diff. Be sure to explain anything your diff doesn’t make clear
-on its own.
-Here’s an example body for psuh
:
-
-
-
Our internal metrics indicate widespread interest in the command
-git-psuh - that is, many users are trying to use it, but finding it is
-unavailable, using some unknown workaround instead.
-
-The following handful of patches add the psuh command and implement some
-handy features on top of it.
-
-This patchset is part of the MyFirstContribution tutorial and should not
-be merged.
-
+Next you’ll have to fill out the body of your cover letter. Again, see
+above for what content to include.
The template created by git format-patch --cover-letter
includes a diffstat.
This gives reviewers a summary of what they’re in for when reviewing your topic.
The one generated for psuh
from the sample implementation looks like this:
@@ -1750,7 +1880,7 @@ as version "2". For instance, you may notice that your v2 patches are
all named like v2-000n-my-commit-subject.patch
. -v2
will also format
your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]",
and your range-diff will be prefaced with "Range-diff against v1".
-Afer you run this command, format-patch
will output the patches to the psuh/
+
After you run this command, format-patch
will output the patches to the psuh/
directory, alongside the v1 patches. Using a single directory makes it easy to
refer to the old v1 patches while proofreading the v2 patches, but you will need
to be careful to send out only the v2 patches. We will use a pattern like
@@ -1930,7 +2060,7 @@ should generate your diffs from <topic>..<mybranch>
and