Display downstream PRs in PR description

README.md

@@ -127,8 +127,6 @@ nix-env -i git-machete
 The latest released version, however, is generally available in the unstable channel.
 Stable channels may lag behind; see [repology](https://repology.org/project/git-machete/versions) for the current channel-package mapping.
 
-<br/>
-
 ### Using Pex
 
 The [Pex tool](https://github.com/pex-tool/pex) (short for Python EXecutable) allows you to build "pex" files which are executable Python environments in a single file.
@@ -141,6 +139,8 @@ pex git-machete -m git_machete.bin:main -o git-machete
 
 Then put the produced `git-machete` file somewhere on your `PATH`.
 
+<br/>
+
 ## Quick start
 
 ### Discover the branch layout

RELEASE_NOTES.md

@@ -1,6 +1,11 @@
 # Release notes
 
-## New in git-machete 3.28.1
+## New in git-machete 3.29.0
+
+- added: git config keys `machete.github.prDescriptionIntroStyle` and `machete.gitlab.mrDescriptionIntroStyle`
+- added: ability to turn off PR/MR description intro completely by setting the git config keys to `none` (suggested by @tir38)
+- added: ability to also include downstream PRs/MRs in PR/MR description intro (suggested by @aouaki)
+- changed: layout and ordering of PRs/MRs in PR/MR description intro to better match `git machete status`
 
 ## New in git-machete 3.28.0
 

ci/checks/prohibit-trailing-whitespace.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-if git grep -EIn ' +$' -- :!'*.py'; then
+if git grep -EIn ' +$' -- :!git_machete/generated_docs.py; then
   echo 'The above lines contain trailing whitespace, please tidy up'
   exit 1
 fi

docs/man/git-machete.1

@@ -27,9 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "GIT-MACHETE" "1" "Aug 22, 2024" "" "git-machete"
+.TH "GIT-MACHETE" "1" "Aug 23, 2024" "" "git-machete"
 .SH NAME
-git-machete \- git-machete 3.28.1
+git-machete \- git-machete 3.29.0
 .sp
 git machete is a robust tool that \fBsimplifies your git workflows\fP\&.
 .sp
@@ -360,6 +360,12 @@ but also \fBgithub checkout\-prs\fP, \fBgithub create\-pr\fP, \fBgithub retarget
 Setting this config key to \fBtrue\fP will force \fBgit machete github create\-pr\fP to take PR description
 from the message body of the first unique commit of the branch, even if \fB\&.git/info/description\fP and/or \fB\&.github/pull_request_template.md\fP is present.
 .TP
+.B \fBmachete.github.prDescriptionIntroStyle\fP:
+Select the style of the intro prepended to PR description:
+* \fBfull\fP    \-\-\- include both a chain of upstream PRs (typically leading to \fBmain\fP, \fBmaster\fP, \fBdevelop\fP etc.) and a tree of downstream PRs
+* \fBup\-only\fP \-\-\- default, include only a chain of upstream PRs
+* \fBnone\fP    \-\-\- prepend no intro to the PR description at all
+.TP
 .B \fBmachete.gitlab.{domain,remote,namespace,project}\fP:
 .INDENT 7.0
 .INDENT 3.5
@@ -392,6 +398,12 @@ but also \fBgitlab checkout\-mrs\fP, \fBgitlab create\-mr\fP, \fBgitlab retarget
 Setting this config key to \fBtrue\fP will force \fBgit machete gitlab create\-mr\fP to take MR description
 from the message body of the first unique commit of the branch, even if \fB\&.git/info/description\fP and/or \fB\&.gitlab/merge_request_templates/Default.md\fP is present.
 .TP
+.B \fBmachete.gitlab.mrDescriptionIntroStyle\fP:
+Select the style of the intro prepended to MR description:
+* \fBfull\fP    \-\-\- include both a chain of upstream MRs (typically leading to \fBmain\fP, \fBmaster\fP, \fBdevelop\fP etc.) and a tree of downstream MRs
+* \fBup\-only\fP \-\-\- default, include only a chain of upstream MRs
+* \fBnone\fP    \-\-\- prepend no intro to the MR description at all
+.TP
 .B \fBmachete.overrideForkPoint.<branch>.to\fP:
 Executing \fBgit machete fork\-point \-\-override\-to[\-parent|\-inferred|=<revision>] [<branch>]\fP sets up a fork point override for \fB<branch>\fP\&.
 .sp
@@ -1009,10 +1021,10 @@ Draft PRs don\(aqt get code owners automatically added as reviewers.
 .B \fBretarget\-pr [\-b|\-\-branch=<branch>] [\-\-ignore\-if\-missing]\fP:
 Sets the base of the current (or specified) branch\(aqs PR to upstream (parent) branch, as seen by git machete (see \fBgit machete show up\fP).
 .sp
-If after changing the base the PR ends up stacked atop another PR, the PR description posted to GitHub will be prepended with a section
-listing the entire related chain of PRs.
+If after changing the base the PR ends up stacked atop another PR, the PR description posted to GitHub will be prepended
+with an intro section listing the entire related chain of PRs.
 .sp
-This header will be updated or removed accordingly with the subsequent runs of \fBretarget\-pr\fP\&.
+This header will be updated or removed accordingly with the subsequent runs of \fBretarget\-pr\fP, even if the base branch is already up to date.
 .sp
 \fBOptions:\fP
 .INDENT 7.0
@@ -1075,6 +1087,12 @@ but also \fBgithub checkout\-prs\fP, \fBgithub create\-pr\fP, \fBgithub retarget
 .B \fBmachete.github.forceDescriptionFromCommitMessage\fP (\fBcreate\-pr\fP only):
 Setting this config key to \fBtrue\fP will force \fBgit machete github create\-pr\fP to take PR description
 from the message body of the first unique commit of the branch, even if \fB\&.git/info/description\fP and/or \fB\&.github/pull_request_template.md\fP is present.
+.TP
+.B \fBmachete.github.prDescriptionIntroStyle\fP (\fBcreate\-pr\fP, \fBrestack\-pr\fP and \fBretarget\-pr\fP):
+Select the style of the intro prepended to PR description:
+* \fBfull\fP    \-\-\- include both a chain of upstream PRs (typically leading to \fBmain\fP, \fBmaster\fP, \fBdevelop\fP etc.) and a tree of downstream PRs
+* \fBup\-only\fP \-\-\- default, include only a chain of upstream PRs
+* \fBnone\fP    \-\-\- prepend no intro to the PR description at all
 .UNINDENT
 .sp
 \fBEnvironment variables (all subcommands):\fP
@@ -1233,10 +1251,10 @@ Draft MRs don\(aqt get code owners automatically added as reviewers.
 .B \fBretarget\-mr [\-b|\-\-branch=<branch>] [\-\-ignore\-if\-missing]\fP:
 Sets the target of the current (or specified) branch\(aqs MR to upstream (parent) branch, as seen by git machete (see \fBgit machete show up\fP).
 .sp
-If after changing the target the MR ends up stacked atop another MR, the MR description posted to GitLab will be prepended with a section
-listing the entire related chain of MRs.
+If after changing the target the MR ends up stacked atop another MR, the MR description posted to GitLab will be prepended
+with an intro section listing the entire related chain of MRs.
 .sp
-This header will be updated or removed accordingly with the subsequent runs of \fBretarget\-mr\fP\&.
+This header will be updated or removed accordingly with the subsequent runs of \fBretarget\-mr\fP, even if the target branch is already up to date.
 .sp
 \fBOptions:\fP
 .INDENT 7.0
@@ -1285,6 +1303,12 @@ but also \fBgitlab checkout\-mrs\fP, \fBgitlab create\-mr\fP, \fBgitlab retarget
 .B \fBmachete.gitlab.forceDescriptionFromCommitMessage\fP (\fBcreate\-mr\fP only):
 Setting this config key to \fBtrue\fP will force \fBgit machete gitlab create\-mr\fP to take MR description
 from the message body of the first unique commit of the branch, even if \fB\&.git/info/description\fP and/or \fB\&.gitlab/merge_request_templates/Default.md\fP is present.
+.TP
+.B \fBmachete.gitlab.mrDescriptionIntroStyle\fP (\fBcreate\-mr\fP, \fBrestack\-mr\fP and \fBretarget\-mr\fP):
+Select the style of the intro prepended to PR description:
+* \fBfull\fP    \-\-\- include both a chain of upstream PRs (typically leading to \fBmain\fP, \fBmaster\fP, \fBdevelop\fP etc.) and a tree of downstream PRs
+* \fBup\-only\fP \-\-\- default, include only a chain of upstream PRs
+* \fBnone\fP    \-\-\- prepend no intro to the PR description at all
 .UNINDENT
 .sp
 \fBEnvironment variables (all subcommands):\fP

docs/source/cli/config.rst

@@ -18,6 +18,9 @@ Note: ``config`` is not a command as such, just a help topic (there is no ``git
 ``machete.github.forceDescriptionFromCommitMessage``:
   .. include:: git-config-keys/github_forceDescriptionFromCommitMessage.rst
 
+``machete.github.prDescriptionIntroStyle``:
+  .. include:: git-config-keys/github_prDescriptionIntroStyle.rst
+
 ``machete.gitlab.{domain,remote,namespace,project}``:
   .. include:: git-config-keys/gitlab_access.rst
       :start-line: 3
@@ -28,6 +31,9 @@ Note: ``config`` is not a command as such, just a help topic (there is no ``git
 ``machete.gitlab.forceDescriptionFromCommitMessage``:
   .. include:: git-config-keys/gitlab_forceDescriptionFromCommitMessage.rst
 
+``machete.gitlab.mrDescriptionIntroStyle``:
+  .. include:: git-config-keys/gitlab_mrDescriptionIntroStyle.rst
+
 ``machete.overrideForkPoint.<branch>.to``:
     Executing ``git machete fork-point --override-to[-parent|-inferred|=<revision>] [<branch>]`` sets up a fork point override for ``<branch>``.
 

docs/source/cli/github.rst

@@ -112,10 +112,10 @@ Creates, checks out and manages GitHub PRs while keeping them reflected in branc
 ``retarget-pr [-b|--branch=<branch>] [--ignore-if-missing]``:
     Sets the base of the current (or specified) branch's PR to upstream (parent) branch, as seen by git machete (see ``git machete show up``).
 
-    If after changing the base the PR ends up stacked atop another PR, the PR description posted to GitHub will be prepended with a section
-    listing the entire related chain of PRs.
+    If after changing the base the PR ends up stacked atop another PR, the PR description posted to GitHub will be prepended
+    with an intro section listing the entire related chain of PRs.
 
-    This header will be updated or removed accordingly with the subsequent runs of ``retarget-pr``.
+    This header will be updated or removed accordingly with the subsequent runs of ``retarget-pr``, even if the base branch is already up to date.
 
     **Options:**
 
@@ -144,6 +144,9 @@ Creates, checks out and manages GitHub PRs while keeping them reflected in branc
 ``machete.github.forceDescriptionFromCommitMessage`` (``create-pr`` only):
   .. include:: git-config-keys/github_forceDescriptionFromCommitMessage.rst
 
+``machete.github.prDescriptionIntroStyle`` (``create-pr``, ``restack-pr`` and ``retarget-pr``):
+  .. include:: git-config-keys/github_prDescriptionIntroStyle.rst
+
 **Environment variables (all subcommands):**
 
 ``GITHUB_TOKEN``

docs/source/cli/gitlab.rst

@@ -113,10 +113,10 @@ Creates, checks out and manages GitLab MRs while keeping them reflected in branc
 ``retarget-mr [-b|--branch=<branch>] [--ignore-if-missing]``:
     Sets the target of the current (or specified) branch's MR to upstream (parent) branch, as seen by git machete (see ``git machete show up``).
 
-    If after changing the target the MR ends up stacked atop another MR, the MR description posted to GitLab will be prepended with a section
-    listing the entire related chain of MRs.
+    If after changing the target the MR ends up stacked atop another MR, the MR description posted to GitLab will be prepended
+    with an intro section listing the entire related chain of MRs.
 
-    This header will be updated or removed accordingly with the subsequent runs of ``retarget-mr``.
+    This header will be updated or removed accordingly with the subsequent runs of ``retarget-mr``, even if the target branch is already up to date.
 
     **Options:**
 
@@ -135,6 +135,9 @@ Creates, checks out and manages GitLab MRs while keeping them reflected in branc
 ``machete.gitlab.forceDescriptionFromCommitMessage`` (``create-mr`` only):
   .. include:: git-config-keys/gitlab_forceDescriptionFromCommitMessage.rst
 
+``machete.gitlab.mrDescriptionIntroStyle`` (``create-mr``, ``restack-mr`` and ``retarget-mr``):
+  .. include:: git-config-keys/github_prDescriptionIntroStyle.rst
+
 **Environment variables (all subcommands):**
 
 ``GITLAB_TOKEN``

docs/source/git-config-keys/github_prDescriptionIntroStyle.rst

@@ -0,0 +1,4 @@
+Select the style of the intro prepended to PR description:
+* ``full``    --- include both a chain of upstream PRs (typically leading to ``main``, ``master``, ``develop`` etc.) and a tree of downstream PRs
+* ``up-only`` --- default, include only a chain of upstream PRs
+* ``none``    --- prepend no intro to the PR description at all

docs/source/git-config-keys/gitlab_mrDescriptionIntroStyle.rst

@@ -0,0 +1,4 @@
+Select the style of the intro prepended to MR description:
+* ``full``    --- include both a chain of upstream MRs (typically leading to ``main``, ``master``, ``develop`` etc.) and a tree of downstream MRs
+* ``up-only`` --- default, include only a chain of upstream MRs
+* ``none``    --- prepend no intro to the MR description at all

git_machete/__init__.py

@@ -1 +1 @@
-__version__ = '3.28.1'
+__version__ = '3.29.0'