Repository: VirtusLab/git-machete
Pull request #1111 (2023-11-27 18:37:37)

Deprecate `clean` and `github sync`


Patch:
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 6f12a4c..f8ef090 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -3,9 +3,9 @@
 ## New in git-machete 3.21.0
 
 - added: `--removed-from-remote` flag to `git machete slide-out` (contributed by @raylu)
-- added: `--with-urls` flag to `git machete github anno-prs` and `machete.github.annotateWithUrls` config key that allow for adding the URL of the PR to the annotations (contributed by @guyboltonking)
+- added: `--with-urls` flag to `git machete github anno-prs` and `machete.github.annotateWithUrls` git config key that allow for adding the URL of the PR to the annotations (contributed by @guyboltonking)
+- deprecated: `git machete clean` and `git machete github sync`; use `github checkout-prs --mine`, `delete-unmanaged` and `slide-out --removed-from-remote` instead
 - fixed: PR author is now always added to annotation if different from current user (contributed by @guyboltonking)
-- fixed: `git machete clean` and `git machete github sync` not only delete untracked branches, but also actually slide them out of branch layout
 
 ## New in git-machete 3.20.0
 
diff --git a/completion/git-machete.completion.bash b/completion/git-machete.completion.bash
index 7b43947..8befcad 100644
--- a/completion/git-machete.completion.bash
+++ b/completion/git-machete.completion.bash
@@ -1,12 +1,12 @@
 #!/usr/bin/env bash
 
 _git_machete() {
-  local cmds="add advance anno clean completion delete-unmanaged diff discover edit file fork-point github go help is-managed list log reapply show slide-out squash status traverse update version"
+  local cmds="add advance anno completion delete-unmanaged diff discover edit file fork-point github go help is-managed list log reapply show slide-out squash status traverse update version"
   local help_topics="$cmds config format hooks"
 
   local categories="addable childless managed slidable slidable-after unmanaged with-overridden-fork-point"
   local directions="down first last next prev root up"
-  local github_subcommands="anno-prs checkout-prs create-pr restack-pr retarget-pr sync"
+  local github_subcommands="anno-prs checkout-prs create-pr restack-pr retarget-pr"
   local locations="current $directions"
   local opt_color_args="always auto never"
   local opt_return_to_args="here nearest-remaining stay"
@@ -17,7 +17,6 @@ _git_machete() {
   local add_opts="-o --onto= -R --as-root -y --yes"
   local advance_opts="-y --yes"
   local anno_opts="-b --branch= -H --sync-github-prs"
-  local clean_opts="-H --checkout-my-github-prs -y --yes"
   local delete_unmanaged_opts="-y --yes"
   local diff_opts="-s --stat"
   local discover_opts="-C --checked-out-since= -l --list-commits -r --roots= -y --yes"
@@ -47,7 +46,6 @@ _git_machete() {
         add) __gitcomp "$common_opts $add_opts" ;;
         advance) __gitcomp "$common_opts $advance_opts" ;;
         anno) __gitcomp "$common_opts $anno_opts" ;;
-        clean) __gitcomp "$common_opts $clean_opts" ;;
         d|diff) __gitcomp "$common_opts $diff_opts" ;;
         delete-unmanaged) __gitcomp "$common_opts $delete_unmanaged_opts" ;;
         discover) __gitcomp "$common_opts $discover_opts" ;;
diff --git a/completion/git-machete.completion.zsh b/completion/git-machete.completion.zsh
index 5058e6f..07c2a2a 100644
--- a/completion/git-machete.completion.zsh
+++ b/completion/git-machete.completion.zsh
@@ -35,12 +35,6 @@ _git-machete() {
             '(-H --sync-github-prs)'{-H,--sync-github-prs}'[Annotate with GitHub PR numbers and authors where applicable]' \
             "${common_flags[@]}"
           ;;
-        (clean)
-          _arguments \
-            '(-H --checkout-my-github-prs)'{-H,--checkout-my-github-prs}'[Checkout your open PRs into local branches]' \
-            '(-y --yes)'{-y,--yes}'[Do not ask for confirmation when deleting unmanaged or untracked branches]' \
-            "${common_flags[@]}"
-          ;;
         (completion)
           _arguments \
             '1:: :__git_machete_completion_shells' \
@@ -175,7 +169,6 @@ __git_machete_cmds=(
   'add:Add a branch to the tree of branch dependencies'
   'advance:Fast-forward the current branch to match one of its downstreams and subsequently slide out this downstream'
   'anno:Manage custom annotations'
-  'clean:Delete untracked and unmanaged branches and optionally check out open GitHub PRs'
   'completion:Print completion script for the given shell'
   'delete-unmanaged:Delete local branches that are not present in the branch layout file'
   'diff:Diff current working directory or a given branch against its fork point'
@@ -255,7 +248,6 @@ __git_machete_github_subcommands() {
         'create-pr:create a PR for the current branch, using the upstream (parent) branch as the PR base'
         'restack-pr:(force-)push and retarget the PR, without adding code owners as reviewers in the process'
         'retarget-pr:set the base of the current branch PR to upstream (parent) branch'
-        'sync:synchronize with the remote repository: checkout open PRs for the current user associated with the GitHub token, delete unmanaged branches and also delete untracked managed branches with no downstream branch'
       )
       _describe 'subcommand' github_subcommands
       ;;
diff --git a/completion/git-machete.fish b/completion/git-machete.fish
index e285384..69dff42 100644
--- a/completion/git-machete.fish
+++ b/completion/git-machete.fish
@@ -1,7 +1,7 @@
 # git.fish completions will provide all __fish_git_* functions referenced from this script
 
 set -l __machete_help_topics config format hooks
-set -l __machete_commands_long add advance anno clean completion delete-unmanaged diff discover edit file fork-point \
+set -l __machete_commands_long add advance anno completion delete-unmanaged diff discover edit file fork-point \
   github go help is-managed list log reapply show slide-out squash status traverse update version
 set -l __machete_commands_short d e g l s t
 set -l __machete_commands $__machete_commands_long $__machete_commands_short
@@ -49,11 +49,6 @@ complete -c git-machete -n "not __fish_seen_subcommand_from $__machete_commands"
 complete -c git-machete -n "__fish_seen_subcommand_from anno"                                                           -x -l branch          -s b -a '(__machete_managed_branches)' -d 'Branch to set the annotation for'
 complete -c git-machete -n "__fish_seen_subcommand_from anno; and not __fish_seen_subcommand_from --sync-github-prs -H" -f -l sync-github-prs -s H                                   -d 'Annotate with GitHub PR numbers and authors where applicable'
 
-# git machete clean
-complete -c git-machete -n "not __fish_seen_subcommand_from $__machete_commands"                                                  -f -a clean                       -d 'Delete untracked and unmanaged branches, and optionally check out open GitHub PRs'
-complete -c git-machete -n "__fish_seen_subcommand_from clean; and not __fish_seen_subcommand_from --checkout-my-github-prs -H"   -f -l checkout-my-github-prs -s H -d 'Checkout open PRs for the current user associated with the GitHub token'
-complete -c git-machete -n "__fish_seen_subcommand_from clean; and not __fish_seen_subcommand_from --yes -y"                      -f -l yes                    -s y -d 'Do not ask for confirmation'
-
 # git machete completion
 complete -c git-machete -n "not __fish_seen_subcommand_from $__machete_commands"                                       -f -a completion -d 'Print completion script for the given shell'
 complete -c git-machete -n "__fish_seen_subcommand_from completion; and not __fish_seen_subcommand_from bash fish zsh" -f -a bash
@@ -102,7 +97,6 @@ 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 not __fish_seen_subcommand_from anno-prs checkout-prs create-pr restack-pr retarget-pr sync"          -f -a create-pr                                            -d 'Creates a PR for the current branch, using the upstream (parent) branch as the PR base'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and not __fish_seen_subcommand_from anno-prs checkout-prs create-pr restack-pr retarget-pr sync"          -f -a restack-pr                                           -d '(Force-)pushes and retargets the PR, without adding code owners as reviewers in the process'
 complete -c git-machete -n "__fish_seen_subcommand_from github; and not __fish_seen_subcommand_from anno-prs checkout-prs create-pr restack-pr retarget-pr sync"          -f -a retarget-pr                                          -d 'Sets the base of PR for the current branch to upstream (parent) branch, as seen by git machete (see git machete show up)'
-complete -c git-machete -n "__fish_seen_subcommand_from github; and not __fish_seen_subcommand_from anno-prs checkout-prs create-pr restack-pr retarget-pr sync"          -f -a sync                                                 -d 'Synchronize with the remote repository: checkout open PRs for the current user associated with the GitHub token, delete unmanaged branches and also delete untracked managed branches with no downstream branch'
 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"
diff --git a/docs/man/git-machete.1 b/docs/man/git-machete.1
index 6f23bcc..900a4f3 100644
--- a/docs/man/git-machete.1
+++ b/docs/man/git-machete.1
@@ -493,7 +493,7 @@ such as: \fBreapply\fP, \fBslide\-out\fP, \fBtraverse\fP, \fBupdate\fP).
 Example: \fBGIT_MACHETE_REBASE_OPTS=\(dq\-\-keep\-empty \-\-rebase\-merges\(dq git machete update\fP\&.
 .TP
 .B \fBGITHUB_TOKEN\fP
-Used to store GitHub API token. Used by commands such as: \fBanno \-\-sync\-github\-prs\fP, \fBclean\fP, \fBgithub\fP\&.
+Used to store GitHub API token. Used by commands such as \fBanno \-\-sync\-github\-prs\fP and \fBgithub\fP\&.
 .UNINDENT
 .SH CLEAN
 .sp
@@ -509,6 +509,8 @@ git machete clean [\-c|\-\-checkout\-my\-github\-prs] [\-y|\-\-yes]
 .UNINDENT
 .UNINDENT
 .sp
+\fBDeprecated.\fP Use \fBgithub checkout\-prs \-\-mine\fP, \fBdelete\-unmanaged\fP and \fBslide\-out \-\-removed\-from\-remote\fP\&.
+.sp
 Synchronizes with the remote repository:
 .INDENT 0.0
 .INDENT 3.5
@@ -1138,6 +1140,8 @@ Ignore errors and quietly terminate execution if there is no PR opened for curre
 .UNINDENT
 .TP
 .B \fBsync\fP:
+\fBDeprecated.\fP Use \fBgithub checkout\-prs \-\-mine\fP, \fBdelete\-unmanaged\fP and \fBslide\-out \-\-removed\-from\-remote\fP\&.
+.sp
 Synchronizes with the remote repository:
 .INDENT 7.0
 .INDENT 3.5
@@ -1152,8 +1156,6 @@ deletes untracked managed branches that have no downstream branch.
 .UNINDENT
 .UNINDENT
 .UNINDENT
-.sp
-Equivalent of \fBgit machete clean \-\-checkout\-my\-github\-prs\fP\&.
 .UNINDENT
 .sp
 \fBGit config keys (all subcommands):\fP
diff --git a/docs/source/cli/clean.rst b/docs/source/cli/clean.rst
index f55a448..80518c6 100644
--- a/docs/source/cli/clean.rst
+++ b/docs/source/cli/clean.rst
@@ -8,6 +8,8 @@ clean
 
     git machete clean [-c|--checkout-my-github-prs] [-y|--yes]
 
+**Deprecated.** Use ``github checkout-prs --mine``, ``delete-unmanaged`` and ``slide-out --removed-from-remote``.
+
 Synchronizes with the remote repository:
 
     1. if invoked with ``-H`` or ``--checkout-my-github-prs``, checks out open PRs for the current user associated with the GitHub token
diff --git a/docs/source/cli/config.rst b/docs/source/cli/config.rst
index e406085..073c4ce 100644
--- a/docs/source/cli/config.rst
+++ b/docs/source/cli/config.rst
@@ -48,4 +48,4 @@ Note: ``config`` is not a command as such, just a help topic (there is no ``git
     Example: ``GIT_MACHETE_REBASE_OPTS="--keep-empty --rebase-merges" git machete update``.
 
 ``GITHUB_TOKEN``
-    Used to store GitHub API token. Used by commands such as: ``anno --sync-github-prs``, ``clean``, ``github``.
+    Used to store GitHub API token. Used by commands such as ``anno --sync-github-prs`` and ``github``.
diff --git a/docs/source/cli/github.rst b/docs/source/cli/github.rst
index 21e6feb..9b8c51a 100644
--- a/docs/source/cli/github.rst
+++ b/docs/source/cli/github.rst
@@ -95,6 +95,8 @@ Creates, checks out and manages GitHub PRs while keeping them reflected in branc
     --ignore-if-missing       Ignore errors and quietly terminate execution if there is no PR opened for current (or specified) branch.
 
 ``sync``:
+    **Deprecated.** Use ``github checkout-prs --mine``, ``delete-unmanaged`` and ``slide-out --removed-from-remote``.
+
     Synchronizes with the remote repository:
 
       1. checks out open PRs for the current user associated with the GitHub token and also traverses the chain of pull requests upwards,
@@ -102,8 +104,6 @@ Creates, checks out and manages GitHub PRs while keeping them reflected in branc
       2. deletes unmanaged branches,
       3. deletes untracked managed branches that have no downstream branch.
 
-    Equivalent of ``git machete clean --checkout-my-github-prs``.
-
 **Git config keys (all subcommands):**
 
 ``machete.github.annotateWithUrls``:
diff --git a/git_machete/generated_docs.py b/git_machete/generated_docs.py
index f956ffc..770f740 100644
--- a/git_machete/generated_docs.py
+++ b/git_machete/generated_docs.py
@@ -186,6 +186,8 @@ long_docs: Dict[str, str] = {
         <b>Usage:</b><b>
            git machete clean [-c|--checkout-my-github-prs] [-y|--yes]</b>
 
+        <b>Deprecated.</b> Use `github checkout-prs --mine`, `delete-unmanaged` and `slide-out --removed-from-remote`.
+
         Synchronizes with the remote repository:
            * if invoked with `-H` or `--checkout-my-github-prs`, checks out open PRs for the current user associated with the GitHub token
              and also traverses the chain of pull requests upwards, adding branches one by one to git-machete and checks them out locally as well,
@@ -355,7 +357,7 @@ long_docs: Dict[str, str] = {
               Example: `GIT_MACHETE_REBASE_OPTS="--keep-empty --rebase-merges" git machete update`.
 
            `GITHUB_TOKEN`
-              Used to store GitHub API token. Used by commands such as: `anno --sync-github-prs`, `clean`, `github`.
+              Used to store GitHub API token. Used by commands such as `anno --sync-github-prs` and `github`.
 
    """,
     "delete-unmanaged": """
@@ -661,6 +663,8 @@ long_docs: Dict[str, str] = {
 
            `sync`:
  
+              <b>Deprecated.</b> Use `github checkout-prs --mine`, `delete-unmanaged` and `slide-out --removed-from-remote`.
+
               Synchronizes with the remote repository:
 
                  * checks out open PRs for the current user associated with the GitHub token and also traverses the chain of pull requests upwards,
@@ -670,8 +674,6 @@ long_docs: Dict[str, str] = {
 
                  * deletes untracked managed branches that have no downstream branch.
 
-              Equivalent of `git machete clean --checkout-my-github-prs`.
-
         <b>Git config keys (all subcommands):</b>
            `machete.github.annotateWithUrls`:
  


Test patch:
diff --git a/tests/completion_e2e/test_completion_e2e.py b/tests/completion_e2e/test_completion_e2e.py
index 49670a9..57a3d25 100644
--- a/tests/completion_e2e/test_completion_e2e.py
+++ b/tests/completion_e2e/test_completion_e2e.py
@@ -8,7 +8,7 @@ from tests.mockers import rewrite_branch_layout_file
 
 test_cases: Dict[str, str] = {
     "git machete ":
-        "add advance anno clean completion delete-unmanaged diff discover edit file fork-point github go "
+        "add advance anno completion delete-unmanaged diff discover edit file fork-point github go "
         "help is-managed list log reapply show slide-out squash status traverse update version",
     "git machete -":
         "--debug -h --help -v --verbose --version",
@@ -30,8 +30,6 @@ test_cases: Dict[str, str] = {
         "develop master",
     "git machete anno --branch=":
         "develop master",
-    "git machete clean -":
-        "-H --checkout-my-github-prs --debug -h --help -v --verbose -y --yes",
     "git machete completion ":
         "bash fish zsh",
     "git machete delete-unmanaged -":
@@ -57,7 +55,7 @@ test_cases: Dict[str, str] = {
     "git machete fork-point --unset-override ":
         "develop",
     "git machete github ":
-        "anno-prs checkout-prs create-pr restack-pr retarget-pr sync",
+        "anno-prs checkout-prs create-pr restack-pr retarget-pr",
     "git machete github anno-prs -":
         "--debug -h --help -v --verbose --with-urls",
     "git machete github checkout-prs -":
@@ -73,7 +71,7 @@ test_cases: Dict[str, str] = {
     "git machete go ":
         "down first last next prev root up",
     "git machete help ":
-        "add advance anno clean completion config delete-unmanaged diff discover edit file fork-point format github go "
+        "add advance anno completion config delete-unmanaged diff discover edit file fork-point format github go "
         "help hooks is-managed list log reapply show slide-out squash status traverse update version",
     "git machete is-managed ":
         "develop feature master",