[PATCH v3 2/2] doc: revert: add discussion

From: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
Date: Aug 9, 2023, 17:15 UTC
Message-ID: <20230809171531.2564807-2-oswald.buddenhagen@gmx.de>
In-Reply-To: <20230809171531.2564807-1-oswald.buddenhagen@gmx.de>

The section is inspired by git-commit.txt.

Signed-off-by: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>

---

Cc: Junio C Hamano <gitster@pobox.com>

---

while thinking about what to write, i came up with an idea for another improvement: with (implicit) --edit, the template message would end up being:

 This reverts commit <sha1>,
 because <PUT REASON HERE>.
---
 Documentation/git-revert.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index d2e10d3dce..2b52dc89a8 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -142,6 +142,16 @@ EXAMPLES
 	changes. The revert only modifies the working tree and the
 	index.
 
+DISCUSSION
+----------
+
+While git creates a basic commit message automatically, you really
+should not leave it at that. In particular, it is _strongly_
+recommended to explain why the original commit is being reverted.
+Repeatedly reverting reversions yields increasingly unwieldy
+commit subjects; latest when you arrive at 'Reapply "Reapply
+"<original subject>""' you should get creative.
+
 CONFIGURATION
 -------------

-- 
2.40.0.152.g15d061e6df