git/Documentation
Junio C Hamano bd2bc94252 merge: allow to pretend a merge is made into a different branch
When a series of patches for a topic-B depends on having topic-A,
the workflow to prepare the topic-B branch would look like this:

    $ git checkout -b topic-B main
    $ git merge --no-ff --no-edit topic-A
    $ git am <mbox-for-topic-B

When topic-A gets updated, recreating the first merge and rebasing
the rest of the topic-B, all on detached HEAD, is a useful
technique.  After updating topic-A with its new round of patches:

    $ git checkout topic-B
    $ prev=$(git rev-parse 'HEAD^{/^Merge branch .topic-A. into}')
    $ git checkout --detach $prev^1
    $ git merge --no-ff --no-edit topic-A
    $ git rebase --onto HEAD $prev @{-1}^0
    $ git checkout -B @{-1}

This will

 (0) check out the current topic-B.
 (1) find the previous merge of topic-A into topic-B.
 (2) detach the HEAD to the parent of the previous merge.
 (3) merge the updated topic-A to it.
 (4) reapply the patches to rebuild the rest of topic-B.
 (5) update topic-B with the result.

without contaminating the reflog of topic-B too much.  topic-B@{1}
is the "logically previous" state before topic-A got updated, for
example.  At (4), comparison (e.g. range-diff) between HEAD and
@{-1} is a meaningful way to sanity check the result, and the same
can be done at (5) by comparing topic-B and topic-B@{1}.

But there is one glitch.  The merge into the detached HEAD done in
the step (3) above gives us "Merge branch 'topic-A' into HEAD", and
does not say "into topic-B".

Teach the "--into-name=<branch>" option to "git merge" and its
underlying "git fmt-merge-message", to pretend as if we were merging
into <branch>, no matter what branch we are actually merging into,
when they prepare the merge message.  The pretend name honors the
usual "into <target>" suppression mechanism, which can be seen in
the tests added here.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-12-20 14:55:02 -08:00
..
config Merge branch 'hm/paint-hits-in-log-grep' 2021-11-01 13:48:08 -07:00
howto Document how we do embargoed releases 2021-03-27 15:13:12 -07:00
RelNotes Git 2.34 2021-11-14 22:50:52 -08:00
technical Merge branch 'js/trace2-raise-format-version' 2021-11-12 15:29:25 -08: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
CodingGuidelines Merge branch 'ds/gender-neutral-doc-guidelines' 2021-07-28 13:18:02 -07:00
config.txt config.txt: fix typo 2021-10-25 09:12:56 -07:00
date-formats.txt
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 'jn/log-m-does-not-imply-p' 2021-08-11 12:36:18 -07:00
doc-diff
docbook-xsl.css
docbook.xsl
everyday.txto
fetch-options.txt fetch: document the --negotiate-only option 2021-06-30 14:57:22 -07:00
fix-texi.perl
git-add.txt add: implement the --sparse option 2021-09-28 10:31:02 -07:00
git-am.txt git-am.txt: clarify --abort behavior 2021-09-10 15:51:14 -07:00
git-annotate.txt
git-apply.txt git-apply: allow simultaneous --cached and --3way options 2021-04-07 22:20:33 -07:00
git-archimport.txt
git-archive.txt archive: describe compression level option 2021-10-25 10:08:23 -07:00
git-bisect-lk2009.txt
git-bisect.txt
git-blame.txt Merge branch 'bs/doc-blame-color-lines' 2021-10-18 15:47:58 -07:00
git-branch.txt branch (doc): -m/-c copies config and reflog 2021-10-23 17:12:41 -07:00
git-bugreport.txt Documentation: fix default directory of git bugreport -o 2021-09-07 14:25:13 -07:00
git-bundle.txt git-bundle.txt: add missing words and punctuation 2021-10-27 17:06:12 -07:00
git-cat-file.txt cat-file: disable refs/replace with --batch-all-objects 2021-10-08 15:45:14 -07:00
git-check-attr.txt
git-check-ignore.txt
git-check-mailmap.txt
git-check-ref-format.txt
git-checkout-index.txt
git-checkout.txt Documentation: call out commands that nuke untracked files/directories 2021-09-27 13:38:37 -07:00
git-cherry-pick.txt
git-cherry.txt
git-citool.txt
git-clean.txt
git-clone.txt builtin/clone.c: add --reject-shallow option 2021-04-01 12:58:58 -07:00
git-column.txt column: fix parsing of the '--nl' option 2021-08-26 14:36:27 -07:00
git-commit-graph.txt
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 doc: config, tell readers of git help --config 2021-09-13 14:51:07 -07:00
git-count-objects.txt
git-credential-cache--daemon.txt
git-credential-cache.txt
git-credential-store.txt
git-credential.txt doc lint: lint and fix missing "GIT" end sections 2021-04-10 23:36:34 -07:00
git-cvsexportcommit.txt
git-cvsimport.txt
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
git-diff-index.txt
git-diff-tree.txt
git-diff.txt git-diff: fix missing --merge-base docs 2021-07-12 13:55:29 -07:00
git-difftool.txt
git-fast-export.txt
git-fast-import.txt
git-fetch-pack.txt
git-fetch.txt Documentation: render special characters correctly 2021-07-30 09:08:12 -07:00
git-filter-branch.txt
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
git-format-patch.txt format-patch (doc): clarify --base=auto 2021-10-23 14:33:20 -07:00
git-fsck-objects.txt
git-fsck.txt
git-gc.txt
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
git-hash-object.txt
git-help.txt help: correct logic error in combining --all and --config 2021-09-23 10:30:43 -07:00
git-http-backend.txt docs/http-backend: mention v2 protocol 2021-09-10 15:34:59 -07:00
git-http-fetch.txt
git-http-push.txt
git-imap-send.txt
git-index-pack.txt index-pack: add --progress-title option 2021-09-07 10:59:23 -07:00
git-init-db.txt
git-init.txt
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/log: correct default for --decorate 2021-06-08 13:34:48 +09:00
git-ls-files.txt
git-ls-remote.txt
git-ls-tree.txt
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: add support for systemd timers on Linux 2021-09-07 10:57:04 -07:00
git-merge-base.txt
git-merge-file.txt
git-merge-index.txt
git-merge-one-file.txt
git-merge-tree.txt
git-merge.txt merge: allow to pretend a merge is made into a different branch 2021-12-20 14:55:02 -08:00
git-mergetool--lib.txt
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 Documentation: normalize spelling of 'normalised' 2018-04-09 14:15:07 +09: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
git-notes.txt
git-p4.txt doc lint: lint and fix missing "GIT" end sections 2021-04-10 23:36:34 -07:00
git-pack-objects.txt Merge branch 'jk/doc-max-pack-size' 2021-07-08 13:15:03 -07:00
git-pack-redundant.txt
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
git-read-tree.txt Documentation: call out commands that nuke untracked files/directories 2021-09-27 13:38:37 -07:00
git-rebase.txt Merge branch 'js/retire-preserve-merges' 2021-10-18 15:47:56 -07:00
git-receive-pack.txt upload-pack: document and rename --advertise-refs 2021-08-05 08:59:37 -07:00
git-reflog.txt
git-remote-ext.txt
git-remote-fd.txt
git-remote-helpers.txto
git-remote.txt
git-repack.txt builtin/repack.c: make largest pack preferred 2021-09-28 21:20:56 -07:00
git-replace.txt
git-request-pull.txt
git-rerere.txt
git-reset.txt Documentation: call out commands that nuke untracked files/directories 2021-09-27 13:38:37 -07:00
git-restore.txt
git-rev-list.txt
git-rev-parse.txt
git-revert.txt
git-rm.txt rm: add --sparse option 2021-09-28 10:31:02 -07:00
git-send-email.txt git-send-email: add option to specify sendmail command 2021-05-17 07:06:13 +09: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
git-show-branch.txt
git-show-index.txt
git-show-ref.txt
git-show.txt
git-sparse-checkout.txt sparse-checkout: clear tracked sparse dirs 2021-09-07 22:41:10 -07:00
git-stage.txt
git-stash.txt stash show: use stash.showIncludeUntracked even when diff options given 2021-05-22 17:56:46 +09:00
git-status.txt Merge branch 'ja/doc-status-types-and-copies' 2021-10-13 15:15:58 -07:00
git-stripspace.txt
git-submodule.txt
git-svn.txt git-svn: drop support for --preserve-merges 2021-09-07 21:45:33 -07:00
git-switch.txt
git-symbolic-ref.txt
git-tag.txt
git-tools.txt
git-unpack-file.txt
git-unpack-objects.txt
git-update-index.txt
git-update-ref.txt
git-update-server-info.txt
git-upload-archive.txt
git-upload-pack.txt Merge branch 'jk/http-server-protocol-versions' 2021-09-23 13:44:47 -07:00
git-var.txt
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
git-whatchanged.txt
git-worktree.txt Merge branch 'sm/worktree-add-lock' 2021-07-28 13:17:58 -07:00
git-write-tree.txt
git.txt Merge branch 'ma/doc-git-version' 2021-10-29 15:43:14 -07:00
gitattributes.txt docs: document symlink restrictions for dot-files 2021-05-04 11:52:03 +09:00
gitcli.txt
gitcore-tutorial.txt
gitcredentials.txt
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
gitignore.txt gitignore.txt: change "folder" to "directory" 2021-10-25 11:06:56 -07:00
gitk.txt
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
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
glossary-content.txt docs: improve fast-forward in glossary content 2021-05-19 21:11:49 +09:00
howto-index.sh
i18n.txt
install-doc-quick.sh
install-webdoc.sh
line-range-format.txt
line-range-options.txt
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 Merge branch 'ab/fix-make-lint-docs' 2021-10-29 15:43:13 -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 MyFirstContribution: Document --range-diff option when writing v2 2021-09-22 14:25:05 -07:00
MyFirstObjectWalk.txt Merge branch 'es/walken-tutorial-fix' into maint 2021-10-12 13:51:29 -07:00
object-format-disclaimer.txt
pretty-formats.txt Merge branch 'ls/typofix' 2021-05-16 21:05:24 +09:00
pretty-options.txt log: document --encoding behavior on iconv() failure 2021-10-29 14:35:59 -07:00
pull-fetch-param.txt
ref-reachability-filters.txt
rev-list-description.txt
rev-list-options.txt Revert "connected: do not sort input revisions" 2021-11-11 12:34:41 -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
SubmittingPatches SubmittingPatches: replace discussion of Travis with GitHub Actions 2021-07-22 12:53:14 -07:00
texi.xsl
trace2-target-values.txt
transfer-data-leaks.txt
urls-remotes.txt
urls.txt
user-manual.conf
user-manual.txt Update docs for change of default merge backend 2021-08-05 15:35:02 -07:00