From d9687f163d4b379cd5d85f3fade9f0e0e91b4022 Mon Sep 17 00:00:00 2001 From: Jacob Walls Date: Thu, 5 Mar 2026 12:14:59 -0500 Subject: [6.0.x] Extended checks and docs for proper commit message format and edition. Thanks to Tim Schilling for the review. Co-authored-by: Natalia <124304+nessita@users.noreply.github.com> Backport of c27d368b92f321e6f91704f554dccbc18df5b075 from main. --- .../contributing/writing-code/working-with-git.txt | 49 ++++++++++++++++++---- 1 file changed, 42 insertions(+), 7 deletions(-) (limited to 'docs/internals/contributing/writing-code/working-with-git.txt') diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt index 15ab7054aa..3691b9cf2f 100644 --- a/docs/internals/contributing/writing-code/working-with-git.txt +++ b/docs/internals/contributing/writing-code/working-with-git.txt @@ -111,7 +111,7 @@ necessary: .. code-block:: shell - git commit -m 'Added two more tests for edge cases' + git commit -m 'Added two more tests for edge cases.' Publishing work --------------- @@ -163,11 +163,46 @@ will deal with your pull request has only two options: merge it or close it. For this reason, it isn't useful to make a pull request until the code is ready for merging -- or sufficiently close that a merger will finish it themselves. +.. _editing-commit-messages: + +Editing commit messages +----------------------- + +To change the message of the most recent commit, run: + +.. code-block:: shell + + git commit --amend + +This opens an editor with the current commit message. Edit it, save, and close +to update the commit. + +To change the message of an earlier commit, use the "reword" option in +interactive rebase. For example, to reword one of the last three commits: + +.. code-block:: shell + + git rebase -i HEAD~3 + +This opens an editor listing the three commits, each prefixed with the word +"pick". Change "pick" to "reword" (or "r") on the line of the commit you want +to change, then save and close. A new editor will open for each commit marked +as "reword", allowing you to update the message. + +See :ref:`committing-guidelines` for the required commit message format. + +After rewriting a commit that has already been pushed to GitHub, you will need +to force-push your branch: + +.. code-block:: shell + + git push --force-with-lease origin ticket_xxxxx + Rebasing branches ----------------- -In the example above, you created two commits, the "Fixed ticket_xxxxx" commit -and "Added two more tests" commit. +In the example above, you created two commits, the "Fixed #xxxxx -- ..." +commit and the "Added two more tests ..." commit. We do not want to have the entire history of your working process in your repository. Your commit "Added two more tests" would be unhelpful noise. @@ -208,7 +243,7 @@ the changes: .. code-block:: shell - git push -f origin ticket_xxxxx + git push --force-with-lease origin ticket_xxxxx Note that this will rewrite history of ticket_xxxxx - if you check the commit hashes before and after the operation at GitHub you will notice that the commit @@ -264,10 +299,10 @@ of: .. code-block:: text - Made changes asked in review by + Made changes asked in review by . - - Fixed whitespace errors in foobar - - Reworded the docstring of bar() + - Fixed whitespace errors in foobar. + - Reworded the docstring of bar(). Finally, push your work back to your GitHub repository. Since you didn't touch the public commits during the rebase, you should not need to force-push: -- cgit v1.3