From 8d2b87ac26d01c7110d911aefea8988ca5a9b183 Mon Sep 17 00:00:00 2001 Message-Id: <8d2b87ac26d01c7110d911aefea8988ca5a9b183.1715179605.git.mdw@distorted.org.uk> From: Mark Wooding Date: Fri, 30 Nov 2007 02:20:03 +0100 Subject: [PATCH] Make "stg repair" help text more helpful MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Organization: Straylight/Edgeware From: Karl Hasselström Specifically, point out that if messing up the branch with git commands was a mistake, the user should run "git reset", not "stg repair". Signed-off-by: Karl Hasselström --- stgit/commands/common.py | 4 +-- stgit/commands/repair.py | 63 +++++++++++++++++++++++++--------------- 2 files changed, 41 insertions(+), 26 deletions(-) diff --git a/stgit/commands/common.py b/stgit/commands/common.py index 6318cdd..bf804e6 100644 --- a/stgit/commands/common.py +++ b/stgit/commands/common.py @@ -114,8 +114,8 @@ def check_head_top_equal(crt_series): if not crt_series.head_top_equal(): raise CmdException( """HEAD and top are not the same. This can happen if you - modify a branch with git. The "repair" command can - fix this situation.""") + modify a branch with git. "stg repair --help" explains + more about what to do next.""") def check_conflicts(): if os.path.exists(os.path.join(basedir.get(), 'conflicts')): diff --git a/stgit/commands/repair.py b/stgit/commands/repair.py index c36db07..aa34792 100644 --- a/stgit/commands/repair.py +++ b/stgit/commands/repair.py @@ -26,32 +26,47 @@ from stgit.out import * from stgit.run import * from stgit import stack, git -help = 'StGit-ify any git commits made on top of your StGit stack' +help = 'Fix StGit metadata if branch was modified with git commands' usage = """%prog [options] -"repair" will repair three kinds of inconsistencies in your StGit -stack, all of them caused by using plain git commands on the branch: - - 1. If you have made regular git commits on top of your stack of - StGit patches, "repair" converts them to StGit patches, - preserving their contents. - - 2. Merge commits cannot become patches; if you have committed a - merge on top of your stack, "repair" will simply mark all - patches below the merge unapplied, since they are no longer - reachable. If this is not what you want, use "git reset" to get - rid of the merge and run "repair" again. - - 3. The applied patches are supposed to be precisely those that are - reachable from the branch head. If you have used e.g. "git reset" - to move the head, some applied patches may no longer be - reachable, and some unapplied patches may have become reachable. - "repair" will correct the appliedness of such patches. - -Note that these are "inconsistencies", not "errors"; furthermore, -"repair" will repair them reliably. As long as you are satisfied -with the way "repair" handles them, you have no reason to avoid -causing them in the first place if that is convenient for you.""" +If you modify an StGit stack (branch) with some git commands -- such +as commit, pull, merge, and rebase -- you will leave the StGit +metadata in an inconsistent state. In that situation, you have two +options: + + 1. Use "git reset" or similar to undo the effect of the git + command(s). + + 2. Use "stg repair". This will fix up the StGit metadata to + accomodate the modifications to the branch. Specifically, it will + do the following: + + * If you have made regular git commits on top of your stack of + StGit patches, "stg repair" makes new StGit patches out of + them, preserving their contents. + + * However, merge commits cannot become patches; if you have + committed a merge on top of your stack, "repair" will simply + mark all patches below the merge unapplied, since they are no + longer reachable. If this is not what you want, use "git + reset" to get rid of the merge and run "stg repair" again. + + * The applied patches are supposed to be precisely those that + are reachable from the branch head. If you have used e.g. + "git reset" to move the head, some applied patches may no + longer be reachable, and some unapplied patches may have + become reachable. "stg repair" will correct the appliedness + of such patches. + + "stg repair" will fix these inconsistencies reliably, so as long + as you like what it does, you have no reason to avoid causing + them in the first place. For example, you might find it + convenient to make commits with a graphical tool and then have + "stg repair" make proper patches of the commits. + +NOTE: If using git commands on the stack was a mistake, running "stg +repair" is _not_ what you want. In that case, what you want is option +(1) above.""" directory = DirectoryGotoToplevel() options = [] -- [mdw]