From: Jean-Noël Avila Date: Sun, 25 May 2025 20:27:02 +0000 (+0000) Subject: doc: convert git-merge manpage to new style X-Git-Tag: v2.50.0-rc1~8^2~7 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=13d5331cccf8c23f1d4eb9b6a24e2308c8631d00;p=thirdparty%2Fgit.git doc: convert git-merge manpage to new style - Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use __ instead of in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. In order to avoid breaking the format on '<<<<<<' and '>>>>>' lines by applying the synopsis rules to these spans, they are formatted using '+' signs instead of '`' signs. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc index 64281d6d44..12aa859d16 100644 --- a/Documentation/git-merge.adoc +++ b/Documentation/git-merge.adoc @@ -8,13 +8,13 @@ git-merge - Join two or more development histories together SYNOPSIS -------- -[verse] -'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] +[synopsis] +git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] [--no-verify] [-s ] [-X ] [-S[]] [--[no-]allow-unrelated-histories] [--[no-]rerere-autoupdate] [-m ] [-F ] [--into-name ] [...] -'git merge' (--continue | --abort | --quit) +git merge (--continue | --abort | --quit) DESCRIPTION ----------- @@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified after the merge was started), `git merge --abort` will in some cases be unable to reconstruct the original (pre-merge) changes. Therefore: -*Warning*: Running `git merge` with non-trivial uncommitted changes is +WARNING: Running `git merge` with non-trivial uncommitted changes is discouraged: while possible, it may leave you in a state that is hard to back out of in the case of a conflict. @@ -67,7 +67,7 @@ OPTIONS include::merge-options.adoc[] --m :: +`-m `:: Set the commit message to be used for the merge commit (in case one is created). + @@ -78,13 +78,13 @@ The `git fmt-merge-msg` command can be used to give a good default for automated `git merge` invocations. The automated message can include the branch description. ---into-name :: +`--into-name `:: Prepare the default merge message as if merging to the branch - ``, instead of the name of the real branch to which + __, instead of the name of the real branch to which the merge is made. --F :: ---file=:: +`-F `:: +`--file=`:: Read the commit message to be used for the merge commit (in case one is created). + @@ -93,12 +93,12 @@ will be appended to the specified message. include::rerere-options.adoc[] ---overwrite-ignore:: ---no-overwrite-ignore:: +`--overwrite-ignore`:: +`--no-overwrite-ignore`:: Silently overwrite ignored files from the merge result. This is the default behavior. Use `--no-overwrite-ignore` to abort. ---abort:: +`--abort`:: Abort the current conflict resolution process, and try to reconstruct the pre-merge state. If an autostash entry is present, apply it to the worktree. @@ -114,17 +114,17 @@ which case `git merge --abort` applies the stash entry to the worktree whereas `git reset --merge` will save the stashed changes in the stash list. ---quit:: +`--quit`:: Forget about the current merge in progress. Leave the index and the working tree as-is. If `MERGE_AUTOSTASH` is present, the stash entry will be saved to the stash list. ---continue:: +`--continue`:: After a `git merge` stops due to conflicts you can conclude the merge by running `git merge --continue` (see "HOW TO RESOLVE CONFLICTS" section below). -...:: +`...`:: Commits, usually other branch heads, to merge into our branch. Specifying more than one commit will create a merge with more than two parents (affectionately called an Octopus merge). @@ -152,7 +152,7 @@ To avoid recording unrelated changes in the merge commit, `git pull` and `git merge` will also abort if there are any changes registered in the index relative to the `HEAD` commit. (Special narrow exceptions to this rule may exist depending on which merge -strategy is in use, but generally, the index must match HEAD.) +strategy is in use, but generally, the index must match `HEAD`.) If all named commits are already ancestors of `HEAD`, `git merge` will exit early with the message "Already up to date." @@ -195,11 +195,11 @@ happens: stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you can inspect the stages with `git ls-files -u`). The working tree files contain the result of the merge operation; i.e. 3-way - merge results with familiar conflict markers `<<<` `===` `>>>`. + merge results with familiar conflict markers +<<<+ `===` +>>>+. 5. A ref named `AUTO_MERGE` is written, pointing to a tree corresponding to the current content of the working tree (including conflict markers for textual conflicts). Note that this ref is only - written when the 'ort' merge strategy is used (the default). + written when the `ort` merge strategy is used (the default). 6. No other changes are made. In particular, the local modifications you had before you started merge will stay the same and the index entries for them stay as they were, @@ -231,7 +231,6 @@ git merge v1.2.3^0 git merge --ff-only v1.2.3 ---- - HOW CONFLICTS ARE PRESENTED --------------------------- @@ -260,7 +259,7 @@ And here is another line that is cleanly resolved or unmodified. ------------ The area where a pair of conflicting changes happened is marked with markers -`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` ++<<<<<<<+, `=======`, and +>>>>>>>+. The part before the `=======` is typically your side, and the part afterwards is typically their side. The default format does not show what the original said in the conflicting @@ -270,7 +269,7 @@ side wants to say it is hard and you'd prefer to go shopping, while the other side wants to claim it is easy. An alternative style can be used by setting the `merge.conflictStyle` -configuration variable to either "diff3" or "zdiff3". In "diff3" +configuration variable to either `diff3` or `zdiff3`. In `diff3` style, the above conflict may look like this: ------------ @@ -290,7 +289,7 @@ Git makes conflict resolution easy. And here is another line that is cleanly resolved or unmodified. ------------ -while in "zdiff3" style, it may look like this: +while in `zdiff3` style, it may look like this: ------------ Here are lines that are either unchanged from the common @@ -308,8 +307,8 @@ Git makes conflict resolution easy. And here is another line that is cleanly resolved or unmodified. ------------ -In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses -another `|||||||` marker that is followed by the original text. You can +In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses +another +|||||||+ marker that is followed by the original text. You can tell that the original just stated a fact, and your side simply gave in to that statement and gave up, while the other side tried to have a more positive attitude. You can sometimes come up with a better resolution by @@ -390,8 +389,8 @@ include::merge-strategies.adoc[] CONFIGURATION ------------- -branch..mergeOptions:: - Sets default options for merging into branch . The syntax and +`branch..mergeOptions`:: + Sets default options for merging into branch __. The syntax and supported options are the same as those of `git merge`, but option values containing whitespace characters are currently not supported.