git-commit-vandalism/Documentation
Junio C Hamano 43966ab315 revert: optionally refer to commit in the "reference" format
A typical "git revert" commit uses the full title of the original
commit in its title, and starts its body of the message with:

    This reverts commit 8fa7f667cf61386257c00d6e954855cc3215ae91.

This does not encourage the best practice of describing not just
"what" (i.e. "Revert X" on the title says what we did) but "why"
(i.e. and it does not say why X was undesirable).

We can instead phrase this first line of the body to be more like

    This reverts commit 8fa7f667 (do this and that, 2022-04-25)

so that the title does not have to be

    Revert "do this and that"

We can instead use the title to describe "why" we are reverting the
original commit.

Introduce the "--reference" option to "git revert", and also the
revert.reference configuration variable, which defaults to false, to
tweak the title and the first line of the draft commit message for
when creating a "revert" commit.

When this option is in use, the first line of the pre-filled editor
buffer becomes a comment line that tells the user to say _why_.  If
the user exits the editor without touching this line by mistake,
what we prepare to become the first line of the body, i.e. "This
reverts commit 8fa7f667 (do this and that, 2022-04-25)", ends up to
be the title of the resulting commit.  This behaviour is designed to
help such a user to identify such a revert in "git log --oneline"
easily so that it can be further reworded with "git rebase -i" later.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-05-26 23:05:03 -07:00
..
config revert: optionally refer to commit in the "reference" format 2022-05-26 23:05:03 -07:00
howto Document how we do embargoed releases 2021-03-27 15:13:12 -07:00
RelNotes Merge branch 'jc/revert-ref-transaction-hook-changes' 2022-04-14 14:17:12 -07:00
technical Merge branch 'rc/fetch-refetch' 2022-04-04 10:56:23 -07:00
.gitattributes
.gitignore doc lint: make "lint-docs" non-.PHONY 2021-10-15 10:29:11 -07:00
asciidoc.conf
asciidoctor-extensions.rb
blame-options.txt Merge branch 'bs/doc-blame-color-lines' 2021-10-18 15:47:58 -07:00
build-docdep.perl
cat-texi.perl
cmd-list.perl git.txt: add list of guides 2020-08-04 18:34:02 -07:00
CodingGuidelines Merge branch 'jc/coding-guidelines-decl-in-for-loop' 2022-04-04 10:56:24 -07:00
config.txt Git 2.35.2 2022-04-11 16:44:45 -07:00
date-formats.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
diff-format.txt Documentation/diff-format: state in which cases porcelain status is T 2021-10-04 13:07:18 -07:00
diff-generate-patch.txt doc: point to diff attribute in patch format docs 2021-04-28 13:34:44 +09:00
diff-options.txt Merge branch 'js/diff-filter-negation-fix' 2022-02-16 15:14:30 -08:00
doc-diff
docbook-xsl.css
docbook.xsl
everyday.txto
fetch-options.txt Merge branch 'rc/fetch-refetch' 2022-04-04 10:56:23 -07:00
fix-texi.perl
git-add.txt add: implement the --sparse option 2021-09-28 10:31:02 -07:00
git-am.txt am: support --allow-empty to record specific empty patches 2021-12-15 17:04:19 -08:00
git-annotate.txt
git-apply.txt git-apply: add --allow-empty flag 2021-12-13 14:30:25 -08:00
git-archimport.txt doc: split placeholders as individual tokens 2021-10-28 09:57:09 -07:00
git-archive.txt archive: describe compression level option 2021-10-25 10:08:23 -07:00
git-bisect-lk2009.txt git-bisect-lk2009: make continuation of list indented 2020-10-08 14:01:15 -07:00
git-bisect.txt bisect: swap command-line options in documentation 2020-08-28 14:06:06 -07:00
git-blame.txt Merge branch 'bs/doc-blame-color-lines' 2021-10-18 15:47:58 -07:00
git-branch.txt branch: add --recurse-submodules option for branch creation 2022-02-04 08:16:39 -08:00
git-bugreport.txt Documentation: fix default directory of git bugreport -o 2021-09-07 14:25:13 -07:00
git-bundle.txt bundle: move capabilities to end of 'verify' 2022-03-23 13:13:59 -07:00
git-cat-file.txt Documentation: add --batch-command to cat-file synopsis 2022-04-07 13:31:54 -07:00
git-check-attr.txt
git-check-ignore.txt doc: check-ignore: code-quote an exclamation mark 2022-02-03 11:13:49 -08:00
git-check-mailmap.txt check-mailmap doc: note config options 2021-01-12 14:04:40 -08:00
git-check-ref-format.txt
git-checkout-index.txt checkout-index: add --ignore-skip-worktree-bits option 2022-01-13 13:49:45 -08:00
git-checkout.txt Merge branch 'js/branch-track-inherit' 2022-01-20 15:25:38 -08:00
git-cherry-pick.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-cherry.txt
git-citool.txt
git-clean.txt
git-clone.txt clone, submodule: pass partial clone filters to submodules 2022-02-09 15:38:36 -08:00
git-column.txt column: fix parsing of the '--nl' option 2021-08-26 14:36:27 -07:00
git-commit-graph.txt Merge branch 'ds/commit-graph-merging-fix' 2020-11-02 13:17:39 -08:00
git-commit-tree.txt
git-commit.txt Document positive variant of commit and merge option "--no-verify" 2021-10-29 11:22:56 -07:00
git-config.txt Documentation: add extensions.worktreeConfig details 2022-02-08 09:49:20 -08:00
git-count-objects.txt
git-credential-cache--daemon.txt doc: replace "--" with {litdd} in credential-cache/fsmonitor 2022-04-06 16:06:06 -07:00
git-credential-cache.txt
git-credential-store.txt
git-credential.txt doc: fix git credential synopsis 2021-10-28 09:57:09 -07:00
git-cvsexportcommit.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-cvsimport.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-cvsserver.txt Documentation: cleanup git-cvsserver 2021-09-16 20:47:48 -07:00
git-daemon.txt
git-describe.txt describe-doc: clarify default length of abbreviation 2021-05-17 15:56:29 +09:00
git-diff-files.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-diff-index.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-diff-tree.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-diff.txt git-diff: fix missing --merge-base docs 2021-07-12 13:55:29 -07:00
git-difftool.txt difftool.c: learn a new way start at specified file 2021-02-22 13:35:49 -08:00
git-fast-export.txt
git-fast-import.txt fast-import: fix typo in documentation 2020-10-04 12:56:29 -07:00
git-fetch-pack.txt builtin/fetch-pack: add --refetch option 2022-03-28 10:25:52 -07:00
git-fetch.txt fetch: fetch unpopulated, changed submodules 2022-03-16 16:08:59 -07:00
git-filter-branch.txt filter-branch doc: fix filter-repo typo 2020-10-20 12:22:25 -07:00
git-fmt-merge-msg.txt merge: allow to pretend a merge is made into a different branch 2021-12-20 14:55:02 -08:00
git-for-each-ref.txt ref-filter: --format=%(raw) support --perl 2021-07-26 12:01:25 -07:00
git-for-each-repo.txt for-each-repo: run subcommands on configured repos 2020-09-25 10:59:44 -07:00
git-format-patch.txt doc: git-format-patch: describe the option --always 2021-12-15 17:04:15 -08:00
git-fsck-objects.txt
git-fsck.txt doc: use three dots for indicating repetition instead of star 2021-11-09 09:39:11 -08:00
git-fsmonitor--daemon.txt doc: replace "--" with {litdd} in credential-cache/fsmonitor 2022-04-06 16:06:06 -07:00
git-gc.txt docs: clarify that refs/notes/ do not keep the attached objects alive 2021-02-10 23:43:55 -08:00
git-get-tar-commit-id.txt
git-grep.txt docs: fix linting issues due to incorrect relative section order 2021-04-10 23:36:34 -07:00
git-gui.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-hash-object.txt
git-help.txt help: add --no-[external-commands|aliases] for use with --all 2022-02-23 13:41:37 -08:00
git-hook.txt git hook run: add an --ignore-missing flag 2022-01-07 15:19:34 -08:00
git-http-backend.txt docs/http-backend: mention v2 protocol 2021-09-10 15:34:59 -07:00
git-http-fetch.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
git-http-push.txt doc: git-http-push: describe the refs as pattern pairs 2021-11-09 09:39:11 -08:00
git-imap-send.txt git-imap-send.txt: add note about localized Gmail folders 2020-08-31 11:44:33 -07:00
git-index-pack.txt index-pack: document and test the --promisor option 2022-03-09 10:25:26 -08:00
git-init-db.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-init.txt init doc: --shared=0xxx does not give umask but perm bits 2021-11-09 09:39:11 -08:00
git-instaweb.txt
git-interpret-trailers.txt trailer: add new .cmd config option 2021-05-04 12:09:43 +09:00
git-log.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-ls-files.txt ls-files: support --recurse-submodules --stage 2022-02-23 16:41:55 -08:00
git-ls-remote.txt
git-ls-tree.txt ls-tree doc: document interaction with submodules 2022-04-08 11:21:11 -07:00
git-mailinfo.txt mailinfo: allow stripping quoted CR without warning 2021-05-10 15:06:22 +09:00
git-mailsplit.txt
git-maintenance.txt maintenance: fix synopsis in documentation 2022-03-15 10:52:43 -07:00
git-merge-base.txt
git-merge-file.txt update documentation for new zdiff3 conflictStyle 2021-12-01 14:45:59 -08:00
git-merge-index.txt doc: use three dots for indicating repetition instead of star 2021-11-09 09:39:11 -08:00
git-merge-one-file.txt
git-merge-tree.txt
git-merge.txt Merge branch 'jc/merge-detached-head-name' 2022-01-05 14:01:30 -08:00
git-mergetool--lib.txt mergetool: break setup_tool out into separate initialization function 2021-02-09 14:09:16 -08:00
git-mergetool.txt doc: describe mergetool configuration in git-mergetool(1) 2021-03-13 15:34:32 -08:00
git-mktag.txt docs: fix linting issues due to incorrect relative section order 2021-04-10 23:36:34 -07:00
git-mktree.txt fix typo in git-mktree.txt 2022-02-02 14:50:09 -08:00
git-multi-pack-index.txt git-multi-pack-index.txt: change "folder" to "directory" 2021-10-25 11:06:56 -07:00
git-mv.txt
git-name-rev.txt name-rev: deprecate --stdin in favor of --annotate-stdin 2022-01-10 09:39:26 -08:00
git-notes.txt docs: improve the example that illustrates git-notes path names 2020-08-03 12:40:09 -07:00
git-p4.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-pack-objects.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-pack-redundant.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-pack-refs.txt
git-patch-id.txt
git-prune-packed.txt
git-prune.txt
git-pull.txt Merge branch 'js/retire-preserve-merges' 2021-10-18 15:47:56 -07:00
git-push.txt Merge branch 'ds/gender-neutral-doc' 2021-07-16 17:42:53 -07:00
git-quiltimport.txt
git-range-diff.txt Merge branch 'js/range-diff-one-side-only' 2021-02-17 17:21:41 -08:00
git-read-tree.txt Merge branch 'nj/read-tree-doc-reffix' 2022-03-13 22:56:18 +00:00
git-rebase.txt update documentation for new zdiff3 conflictStyle 2021-12-01 14:45:59 -08:00
git-receive-pack.txt upload-pack: document and rename --advertise-refs 2021-08-05 08:59:37 -07:00
git-reflog.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-remote-ext.txt
git-remote-fd.txt
git-remote-helpers.txto
git-remote.txt builtin/remote.c: show progress when renaming remote references 2022-03-03 14:44:05 -08:00
git-repack.txt repack: make '--quiet' disable progress 2021-12-20 11:59:17 -08:00
git-replace.txt
git-request-pull.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
git-rerere.txt
git-reset.txt reset: remove 'reset.refresh' config option 2022-03-23 14:39:45 -07:00
git-restore.txt update documentation for new zdiff3 conflictStyle 2021-12-01 14:45:59 -08:00
git-rev-list.txt docs/rev-list: add some examples of --disk-usage 2021-02-17 16:25:29 -08:00
git-rev-parse.txt rev-parse: add option for absolute or relative path formatting 2020-12-12 23:35:51 -08:00
git-revert.txt revert: optionally refer to commit in the "reference" format 2022-05-26 23:05:03 -07:00
git-rm.txt rm: add --sparse option 2021-09-28 10:31:02 -07:00
git-send-email.txt send-email docs: add format-patch options 2021-10-28 09:06:15 -07:00
git-send-pack.txt send-pack: properly use parse_options() API for usage string 2021-09-12 18:57:30 -07:00
git-sh-i18n--envsubst.txt
git-sh-i18n.txt
git-sh-setup.txt
git-shell.txt
git-shortlog.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-show-branch.txt
git-show-index.txt Documentation: mark --object-format=sha256 as experimental 2020-08-17 10:50:14 -07:00
git-show-ref.txt
git-show.txt doc/git-show: include --diff-merges description 2020-12-21 13:47:32 -08:00
git-sparse-checkout.txt Merge branch 'en/present-despite-skipped' 2022-03-09 13:38:23 -08:00
git-stage.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-stash.txt stash: implement '--staged' option for 'push' and 'save' 2021-10-18 13:09:21 -07:00
git-status.txt status: print stash info with --porcelain=v2 --show-stash 2021-10-21 17:24:30 -07:00
git-stripspace.txt
git-submodule.txt clone, submodule: pass partial clone filters to submodules 2022-02-09 15:38:36 -08:00
git-svn.txt Merge branch 'ja/doc-cleanup' 2021-12-10 14:35:03 -08:00
git-switch.txt Merge branch 'js/branch-track-inherit' 2022-01-10 11:52:54 -08:00
git-symbolic-ref.txt
git-tag.txt Documentation: typofix --column description 2021-02-19 19:36:47 -08:00
git-tools.txt
git-unpack-file.txt
git-unpack-objects.txt
git-update-index.txt doc: replace "--" with {litdd} in credential-cache/fsmonitor 2022-04-06 16:06:06 -07:00
git-update-ref.txt update-ref: allow creation of multiple transactions 2020-11-16 13:44:01 -08:00
git-update-server-info.txt
git-upload-archive.txt Documentation: match underline with the text 2015-10-22 10:16:12 -07:00
git-upload-pack.txt Merge branch 'jk/http-server-protocol-versions' 2021-09-23 13:44:47 -07:00
git-var.txt var: add GIT_DEFAULT_BRANCH variable 2021-11-03 13:25:36 -07:00
git-verify-commit.txt
git-verify-pack.txt
git-verify-tag.txt
git-version.txt documentation: add documentation for 'git version' 2021-09-14 10:05:40 -07:00
git-web--browse.txt doc: split placeholders as individual tokens 2021-10-28 09:57:09 -07:00
git-whatchanged.txt
git-worktree.txt Merge branch 'pw/worktree-list-with-z' 2022-04-04 10:56:25 -07:00
git-write-tree.txt
git.txt Merge branch 'if/redact-packfile-uri' 2021-12-10 14:35:04 -08:00
gitattributes.txt userdiff: add builtin diff driver for kotlin language. 2022-03-12 18:15:47 -08:00
gitcli.txt git-cli.txt: clarify "options first and then args" 2022-01-17 11:42:25 -08:00
gitcore-tutorial.txt
gitcredentials.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
gitcvs-migration.txt
gitdiffcore.txt Merge branch 'en/ort-perf-batch-8' 2021-03-22 14:00:24 -07:00
giteveryday.txt
gitfaq.txt Update docs for change of default merge backend 2021-08-05 15:35:02 -07:00
gitglossary.txt
githooks.txt hook: add 'run' subcommand 2022-01-07 15:19:34 -08:00
gitignore.txt gitignore.txt: change "folder" to "directory" 2021-10-25 11:06:56 -07:00
gitk.txt doc: log, gitk: move '-L' description to 'line-range-options.txt' 2020-11-01 15:54:14 -08:00
gitmailmap.txt docs: document symlink restrictions for dot-files 2021-05-04 11:52:03 +09:00
gitmodules.txt docs: document symlink restrictions for dot-files 2021-05-04 11:52:03 +09:00
gitnamespaces.txt doc lint: lint and fix missing "GIT" end sections 2021-04-10 23:36:34 -07:00
gitremote-helpers.txt
gitrepository-layout.txt
gitrevisions.txt
gitsubmodules.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
gittutorial-2.txt
gittutorial.txt Documentation: render special characters correctly 2021-07-30 09:08:12 -07:00
gitweb.conf.txt gitweb: add "e-mail privacy" feature to redact e-mail addresses 2021-04-08 15:54:26 -07:00
gitweb.txt gitweb.txt: change "folder" to "directory" 2021-10-25 11:06:57 -07:00
gitworkflows.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
glossary-content.txt glossary: describe "worktree" 2022-02-09 18:34:41 -08:00
howto-index.sh
i18n.txt i18n.txt: camel case and monospace "i18n.commitEncoding" 2021-02-24 15:21:25 -08:00
install-doc-quick.sh
install-webdoc.sh
line-range-format.txt doc: add more pointers to gitattributes(5) for userdiff 2020-11-01 15:54:14 -08:00
line-range-options.txt blame-options.txt: also mention 'funcname' in '-L' description 2020-11-01 15:54:14 -08:00
lint-gitlink.perl doc lint: make "lint-docs" non-.PHONY 2021-10-15 10:29:11 -07:00
lint-man-end-blurb.perl doc lint: emit errors on STDERR 2021-10-15 10:16:57 -07:00
lint-man-section-order.perl doc lint: emit errors on STDERR 2021-10-15 10:16:57 -07:00
Makefile Documentation/Makefile: fix "make info" regression in dad9cd7d51 2022-04-06 09:43:48 -07:00
manpage-base-url.xsl.in
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-quote-apos.xsl
manpage.xsl
merge-options.txt Document positive variant of commit and merge option "--no-verify" 2021-10-29 11:22:56 -07:00
merge-strategies.txt Update docs for change of default merge backend 2021-08-05 15:35:02 -07:00
MyFirstContribution.txt Merge branch 'jc/tutorial-format-patch-base' 2021-11-29 15:41:46 -08:00
MyFirstObjectWalk.txt MyFirstObjectWalk: update recommended usage 2022-03-09 10:25:27 -08:00
object-format-disclaimer.txt Documentation: mark --object-format=sha256 as experimental 2020-08-17 10:50:14 -07:00
pretty-formats.txt Merge branch 'es/pretty-describe-more' 2021-12-15 09:39:48 -08:00
pretty-options.txt log: document --encoding behavior on iconv() failure 2021-10-29 14:35:59 -07:00
pull-fetch-param.txt refspec: add support for negative refspecs 2020-09-30 14:52:00 -07:00
ref-reachability-filters.txt Doc: prefer more specific file name 2020-09-18 15:41:56 -07:00
rev-list-description.txt
rev-list-options.txt git-rev-list: add --exclude-first-parent-only flag 2022-01-12 11:08:42 -08:00
revisions.txt revisions(7): clarify that most commands take a single revision range 2021-05-18 10:08:03 +09:00
sequencer.txt
signoff-option.txt Documentation: stylistically normalize references to Signed-off-by: 2020-10-20 11:57:40 -07:00
SubmittingPatches SubmittingPatches: explain why we care about log messages 2022-01-27 17:50:04 -08:00
texi.xsl
trace2-target-values.txt
transfer-data-leaks.txt
urls-remotes.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
urls.txt
user-manual.conf
user-manual.txt Update docs for change of default merge backend 2021-08-05 15:35:02 -07:00