Add --by=... flag to git machete git{hub,lab} --update-{pr,mr}-descriptions

Author: PawelLipski

README.md

@@ -255,6 +255,16 @@ However, we still recommend using merge for the narrow case of [backporting hotf
 
 <br/>
 
+#### In what order should I merge stacked PRs?
+
+We recommend merging PRs from the top-most (closest to the root branch, typically `main` or `master`).
+In other words, PR should only be merged when its base is a root branch.
+
+This way, you don't end up with a big-ball-of-code PR at the end.
+Avoid such balls is one of the main reasons for opening small PRs in the first place.
+
+<br/>
+
 #### Sometimes when I run `update` or `traverse`, too many commits are taken into the rebase... how to fix that?
 
 Contrary to the popular misconception, git doesn't have a notion of

RELEASE_NOTES.md

@@ -1,6 +1,8 @@
 # Release notes
 
-## New in git-machete 3.32.2
+## New in git-machete 3.33.0
+
+- added: `--by=...` flag to `git machete git{hub,lab} update-{pr,mr}-descriptions`
 
 ## New in git-machete 3.32.1
 

completion/git-machete.completion.bash

@@ -27,7 +27,7 @@ _git_machete() {
   local githublab_checkout_opts="--all --by= --mine"
   local githublab_restack_opts="-U --update-related-descriptions"
   local githublab_retarget_opts="-b --branch= --ignore-if-missing -U --update-related-descriptions"
-  local githublab_update_descriptions_opts="--all --mine --related"
+  local githublab_update_descriptions_opts="--all --by= --mine --related"
   local reapply_opts="-f --fork-point="
   local slide_out_opts="-d --down-fork-point= --delete -M --merge -n --no-edit-merge --no-interactive-rebase --removed-from-remote"
   local squash_opts="-f --fork-point="

completion/git-machete.completion.zsh

@@ -304,6 +304,7 @@ __git_machete_github_subcommands() {
         (update-pr-descriptions)
           _arguments \
             '(--all)'--all'[Update PR descriptions for all PRs in the repository]' \
+            '(--by)'--by='[Update PR descriptions for all PRs authored by the given GitHub user]' \
             '(--mine)'--mine'[Update PR descriptions for all PRs opened by the current user associated with the GitHub token]' \
             '(--related)'--related'[Update PR descriptions for all PRs that are upstream and/or downstream of the PR for the current branch]' \
             "${common_flags[@]}"
@@ -379,6 +380,7 @@ __git_machete_gitlab_subcommands() {
         (update-mr-descriptions)
           _arguments \
             '(--all)'--all'[Update MR descriptions for all MRs in the project]' \
+            '(--by)'--by='[Update MR descriptions for all MRs authored by the given GitLab user]' \
             '(--mine)'--mine'[Update MR descriptions for all MRs opened by the current user associated with the GitLab token]' \
             '(--related)'--related'[Update MR descriptions for all MRs that are upstream and/or downstream of the MR for the current branch]' \
             "${common_flags[@]}"

completion/git-machete.fish

@@ -103,7 +103,7 @@ complete -c git-machete -n "__fish_seen_subcommand_from github; and not __fish_s
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from anno-prs;               and not __fish_seen_subcommand_from --with-urls"                   -f -l with-urls                                            -d 'Include PR URLs in the annotations'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from checkout-prs;           and not __fish_seen_subcommand_from --all"                         -f -l all                                                  -d 'Checkout all open PRs'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from checkout-prs;           and not __fish_seen_subcommand_from --by"                          -x -l by                                                   -d "Checkout someone's open PRs"
-complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from checkout-prs;           and not __fish_seen_subcommand_from --mine"                        -x -l mine                                                 -d 'Checkout open PRs for the current user associated with the GitHub token'
+complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from checkout-prs;           and not __fish_seen_subcommand_from --mine"                        -f -l mine                                                 -d 'Checkout open PRs for the current user associated with the GitHub token'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from create-pr;              and not __fish_seen_subcommand_from --draft"                       -f -l draft                                                -d 'Create the new PR as a draft'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from create-pr;              and not __fish_seen_subcommand_from --title"                       -x -l title                                                -d 'Set the title for new PR explicitly'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from create-pr;              and not __fish_seen_subcommand_from --update-related-descriptions" -f -l update-related-descriptions -s U                     -d 'Update the generated sections of PR descriptions that list the upstream and/or downstream PRs'
@@ -113,8 +113,9 @@ complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from retarget-pr;            and not __fish_seen_subcommand_from --ignore-if-missing"           -f -l ignore-if-missing                                    -d 'Ignore errors and quietly terminate execution if there is no PR opened for current (or specified) branch'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from retarget-pr;            and not __fish_seen_subcommand_from --update-related-descriptions" -f -l update-related-descriptions -s U                     -d 'Update the generated sections of PR descriptions that list the upstream and/or downstream PRs'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from update-pr-descriptions; and not __fish_seen_subcommand_from --all"                         -f -l all                                                  -d 'Update PR descriptions for all PRs in the repository'
-complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from update-pr-descriptions; and not __fish_seen_subcommand_from --mine"                        -x -l mine                                                 -d 'Update PR descriptions for all PRs opened by the current user associated with the GitHub token'
-complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from update-pr-descriptions; and not __fish_seen_subcommand_from --related"                     -x -l related                                              -d 'Update PR descriptions for all PRs that are upstream and/or downstream of the PR for the current branch'
+complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from update-pr-descriptions; and not __fish_seen_subcommand_from --by"                          -x -l by                                                   -d 'Update PR descriptions for all PRs opened by the given user'
+complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from update-pr-descriptions; and not __fish_seen_subcommand_from --mine"                        -f -l mine                                                 -d 'Update PR descriptions for all PRs opened by the current user associated with the GitHub token'
+complete -c git-machete -n "__fish_seen_subcommand_from github; and __fish_seen_subcommand_from update-pr-descriptions; and not __fish_seen_subcommand_from --related"                     -f -l related                                              -d 'Update PR descriptions for all PRs that are upstream and/or downstream of the PR for the current branch'
 
 # git machete gitlab
 complete -c git-machete -n "not __fish_seen_subcommand_from $__machete_commands"                                                                                                           -f -a gitlab                                               -d 'Create, check out and manage GitLab MRs while keeping them reflected in git machete'
@@ -127,7 +128,7 @@ complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and not __fish_s
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from anno-mrs;               and not __fish_seen_subcommand_from --with-urls"                   -f -l with-urls                                            -d 'Include MR URLs in the annotations'
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from checkout-mrs;           and not __fish_seen_subcommand_from --all"                         -f -l all                                                  -d 'Checkout all open MRs'
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from checkout-mrs;           and not __fish_seen_subcommand_from --by"                          -x -l by                                                   -d "Checkout someone's open MRs"
-complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from checkout-mrs;           and not __fish_seen_subcommand_from --mine"                        -x -l mine                                                 -d 'Checkout open MRs for the current user associated with the GitLab token'
+complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from checkout-mrs;           and not __fish_seen_subcommand_from --mine"                        -f -l mine                                                 -d 'Checkout open MRs for the current user associated with the GitLab token'
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from create-mr;              and not __fish_seen_subcommand_from --draft"                       -f -l draft                                                -d 'Create the new MR as a draft'
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from create-mr;              and not __fish_seen_subcommand_from --title"                       -x -l title                                                -d 'Set the title for new MR explicitly'
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from create-mr;              and not __fish_seen_subcommand_from --update-related-descriptions" -f -l update-related-descriptions -s U                     -d 'Update the generated sections of MR descriptions that list the upstream and/or downstream MRs'
@@ -137,8 +138,9 @@ complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from retarget-mr;            and not __fish_seen_subcommand_from --ignore-if-missing"           -f -l ignore-if-missing                                    -d 'Ignore errors and quietly terminate execution if there is no MR opened for current (or specified) branch'
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from retarget-mr;            and not __fish_seen_subcommand_from --update-related-descriptions" -f -l update-related-descriptions -s U                     -d 'Update the generated sections of MR descriptions that list the upstream and/or downstream MRs'
 complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from update-mr-descriptions; and not __fish_seen_subcommand_from --all"                         -f -l all                                                  -d 'Update MR descriptions for all MRs in the project'
-complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from update-mr-descriptions; and not __fish_seen_subcommand_from --mine"                        -x -l mine                                                 -d 'Update MR descriptions for all MRs opened by the current user associated with the GitHub token'
-complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from update-mr-descriptions; and not __fish_seen_subcommand_from --related"                     -x -l related                                              -d 'Update MR descriptions for all MRs that are upstream and/or downstream of the MR for the current branch'
+complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from update-mr-descriptions; and not __fish_seen_subcommand_from --by"                          -f -l by                                                   -d 'Update MR descriptions for all MRs opened by the given user'
+complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from update-mr-descriptions; and not __fish_seen_subcommand_from --mine"                        -f -l mine                                                 -d 'Update MR descriptions for all MRs opened by the current user associated with the GitHub token'
+complete -c git-machete -n "__fish_seen_subcommand_from gitlab; and __fish_seen_subcommand_from update-mr-descriptions; and not __fish_seen_subcommand_from --related"                     -f -l related                                              -d 'Update MR descriptions for all MRs that are upstream and/or downstream of the MR for the current branch'
 
 # git machete go
 complete -c git-machete -n "not __fish_seen_subcommand_from $__machete_commands"                                                                   -f -a go    -d 'Check out the branch relative to the position of the current branch, accepts down/first/last/next/root/prev/up argument'

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" "Feb 07, 2025" "" "git-machete"
+.TH "GIT-MACHETE" "1" "Feb 18, 2025" "" "git-machete"
 .SH NAME
-git-machete \- git-machete 3.32.2
+git-machete \- git-machete 3.33.0
 .sp
 git machete is a robust tool that \fBsimplifies your git workflows\fP\&.
 .sp
@@ -1090,7 +1090,7 @@ deletes unmanaged branches,
 deletes untracked managed branches that have no downstream branch.
 .UNINDENT
 .TP
-.B \fBupdate\-pr\-descriptions\fP:
+.B \fBupdate\-pr\-descriptions [\-\-all | \-\-by=<github\-login> | \-\-mine | \-\-related]\fP:
 Updates the generated sections (\(dqintros\(dq) of PR descriptions that list the upstream and/or downstream PRs
 (depending on \fBmachete.github.prDescriptionIntroStyle\fP git config key).
 .sp
@@ -1100,6 +1100,9 @@ Updates the generated sections (\(dqintros\(dq) of PR descriptions that list the
 .B  \-\-all
 Update PR descriptions for all PRs in the repository.
 .TP
+.BI \-\-by\fB= <github\-login>
+Update PR descriptions for all PRs authored by the given GitHub user, where \fB<github\-login>\fP is the GitHub account name.
+.TP
 .B  \-\-mine
 Update PR descriptions for all PRs opened by the current user associated with the GitHub token.
 .TP
@@ -1351,7 +1354,7 @@ Update the generated sections (\(dqintros\(dq) of MR descriptions that list the
 See help for \fBgit machete gitlab update\-mr\-descriptions \-\-related\fP for details.
 .UNINDENT
 .TP
-.B \fBupdate\-mr\-descriptions\fP:
+.B \fBupdate\-mr\-descriptions [\-\-all | \-\-by=<gitlab\-login> | \-\-mine | \-\-related]\fP:
 Updates the generated sections (\(dqintros\(dq) of MR descriptions that list the upstream and/or downstream MRs
 (depending on \fBmachete.gitlab.mrDescriptionIntroStyle\fP git config key).
 .sp
@@ -1361,6 +1364,9 @@ Updates the generated sections (\(dqintros\(dq) of MR descriptions that list the
 .B  \-\-all
 Update MR descriptions for all MRs in the project.
 .TP
+.BI \-\-by\fB= <gitlab\-login>
+Update MR descriptions for all MRs authored by the given GitLab user, where \fB<gitlab\-login>\fP is the GitLab account name.
+.TP
 .B  \-\-mine
 Update MR descriptions for all MRs opened by the current user associated with the GitLab token.
 .TP

docs/source/cli/github.rst

@@ -146,19 +146,21 @@ Creates, checks out and manages GitHub PRs while keeping them reflected in branc
     #. deletes unmanaged branches,
     #. deletes untracked managed branches that have no downstream branch.
 
-``update-pr-descriptions``:
+``update-pr-descriptions [--all | --by=<github-login> | --mine | --related]``:
     Updates the generated sections ("intros") of PR descriptions that list the upstream and/or downstream PRs
     (depending on ``machete.github.prDescriptionIntroStyle`` git config key).
 
     **Options:**
 
-    --all         Update PR descriptions for all PRs in the repository.
+    --all                Update PR descriptions for all PRs in the repository.
 
-    --mine        Update PR descriptions for all PRs opened by the current user associated with the GitHub token.
+    --by=<github-login>  Update PR descriptions for all PRs authored by the given GitHub user, where ``<github-login>`` is the GitHub account name.
 
-    --related     Update PR descriptions for all PRs that are upstream and/or downstream of the PR for the current branch.
-                  If ``machete.github.prDescriptionIntroStyle`` is ``up-only`` (default), then only downstream PR descriptions are updated.
-                  If ``machete.github.prDescriptionIntroStyle`` is ``full``, then both downstream and upstream PR descriptions are updated.
+    --mine               Update PR descriptions for all PRs opened by the current user associated with the GitHub token.
+
+    --related            Update PR descriptions for all PRs that are upstream and/or downstream of the PR for the current branch.
+                         If ``machete.github.prDescriptionIntroStyle`` is ``up-only`` (default), then only downstream PR descriptions are updated.
+                         If ``machete.github.prDescriptionIntroStyle`` is ``full``, then both downstream and upstream PR descriptions are updated.
 
 **Git config keys:**
 

docs/source/cli/gitlab.rst

@@ -137,19 +137,21 @@ Creates, checks out and manages GitLab MRs while keeping them reflected in branc
     -U, --update-related-descriptions  Update the generated sections ("intros") of MR descriptions that list the upstream and/or downstream MRs.
                                        See help for ``git machete gitlab update-mr-descriptions --related`` for details.
 
-``update-mr-descriptions``:
+``update-mr-descriptions [--all | --by=<gitlab-login> | --mine | --related]``:
     Updates the generated sections ("intros") of MR descriptions that list the upstream and/or downstream MRs
     (depending on ``machete.gitlab.mrDescriptionIntroStyle`` git config key).
 
     **Options:**
 
-    --all         Update MR descriptions for all MRs in the project.
+    --all                Update MR descriptions for all MRs in the project.
 
-    --mine        Update MR descriptions for all MRs opened by the current user associated with the GitLab token.
+    --by=<gitlab-login>  Update MR descriptions for all MRs authored by the given GitLab user, where ``<gitlab-login>`` is the GitLab account name.
 
-    --related     Update MR descriptions for all MRs that are upstream and/or downstream of the MR for the current branch.
-                  If ``machete.gitlab.mrDescriptionIntroStyle`` is ``up-only`` (default), then only downstream MR descriptions are updated.
-                  If ``machete.gitlab.mrDescriptionIntroStyle`` is ``full``, then both downstream and upstream MR descriptions are updated.
+    --mine               Update MR descriptions for all MRs opened by the current user associated with the GitLab token.
+
+    --related            Update MR descriptions for all MRs that are upstream and/or downstream of the MR for the current branch.
+                         If ``machete.gitlab.mrDescriptionIntroStyle`` is ``up-only`` (default), then only downstream MR descriptions are updated.
+                         If ``machete.gitlab.mrDescriptionIntroStyle`` is ``full``, then both downstream and upstream MR descriptions are updated.
 
 **Git config keys:**