stg squash: Improve documentation
[stgit] / stgit / commands / squash.py
1 # -*- coding: utf-8 -*-
2
3 __copyright__ = """
4 Copyright (C) 2007, Karl Hasselström <kha@treskal.com>
5
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License version 2 as
8 published by the Free Software Foundation.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 """
19
20 from stgit.argparse import opt
21 from stgit.out import *
22 from stgit import argparse, utils
23 from stgit.commands import common
24 from stgit.lib import git, transaction
25
26 help = 'Squash two or more patches into one'
27 kind = 'stack'
28 usage = ['[options] <patches>']
29 description = """
30 Squash two or more patches, creating one big patch that contains all
31 their changes. In more detail:
32
33 1. Pop all the given patches, plus any other patches on top of them.
34
35 2. Push the given patches in the order they were given on the
36 command line.
37
38 3. Squash the given patches into one big patch.
39
40 4. Allow the user to edit the commit message of the new patch
41 interactively.
42
43 5. Push the other patches that were popped in step (1).
44
45 Conflicts can occur whenever we push a patch; that is, in step (2) and
46 (5). If there are conflicts, the command will stop so that you can
47 resolve them."""
48
49 args = [argparse.patch_range(argparse.applied_patches,
50 argparse.unapplied_patches)]
51 options = [opt('-n', '--name', short = 'Name of squashed patch')
52 ] + argparse.message_options(save_template = True)
53
54 directory = common.DirectoryHasRepositoryLib()
55
56 class SaveTemplateDone(Exception):
57 pass
58
59 def _squash_patches(trans, patches, msg, save_template):
60 cd = trans.patches[patches[0]].data
61 cd = git.CommitData(tree = cd.tree, parents = cd.parents)
62 for pn in patches[1:]:
63 c = trans.patches[pn]
64 tree = trans.stack.repository.simple_merge(
65 base = c.data.parent.data.tree,
66 ours = cd.tree, theirs = c.data.tree)
67 if not tree:
68 return None
69 cd = cd.set_tree(tree)
70 if msg == None:
71 msg = '\n\n'.join('%s\n\n%s' % (pn.ljust(70, '-'),
72 trans.patches[pn].data.message)
73 for pn in patches)
74 if save_template:
75 save_template(msg)
76 raise SaveTemplateDone()
77 else:
78 msg = utils.edit_string(msg, '.stgit-squash.txt').strip()
79 cd = cd.set_message(msg)
80
81 return cd
82
83 def _squash(stack, iw, name, msg, save_template, patches):
84
85 # If a name was supplied on the command line, make sure it's OK.
86 def bad_name(pn):
87 return pn not in patches and stack.patches.exists(pn)
88 def get_name(cd):
89 return name or utils.make_patch_name(cd.message, bad_name)
90 if name and bad_name(name):
91 raise common.CmdException('Patch name "%s" already taken')
92
93 def make_squashed_patch(trans, new_commit_data):
94 name = get_name(new_commit_data)
95 trans.patches[name] = stack.repository.commit(new_commit_data)
96 trans.unapplied.insert(0, name)
97
98 trans = transaction.StackTransaction(stack, 'squash',
99 allow_conflicts = True)
100 push_new_patch = bool(set(patches) & set(trans.applied))
101 try:
102 new_commit_data = _squash_patches(trans, patches, msg, save_template)
103 if new_commit_data:
104 # We were able to construct the squashed commit
105 # automatically. So just delete its constituent patches.
106 to_push = trans.delete_patches(lambda pn: pn in patches)
107 else:
108 # Automatic construction failed. So push the patches
109 # consecutively, so that a second construction attempt is
110 # guaranteed to work.
111 to_push = trans.pop_patches(lambda pn: pn in patches)
112 for pn in patches:
113 trans.push_patch(pn, iw)
114 new_commit_data = _squash_patches(trans, patches, msg,
115 save_template)
116 assert not trans.delete_patches(lambda pn: pn in patches)
117 make_squashed_patch(trans, new_commit_data)
118
119 # Push the new patch if necessary, and any unrelated patches we've
120 # had to pop out of the way.
121 if push_new_patch:
122 trans.push_patch(get_name(new_commit_data), iw)
123 for pn in to_push:
124 trans.push_patch(pn, iw)
125 except SaveTemplateDone:
126 trans.abort(iw)
127 return
128 except transaction.TransactionHalted:
129 pass
130 return trans.run(iw)
131
132 def func(parser, options, args):
133 stack = directory.repository.current_stack
134 patches = common.parse_patches(args, list(stack.patchorder.all))
135 if len(patches) < 2:
136 raise common.CmdException('Need at least two patches')
137 return _squash(stack, stack.repository.default_iw, options.name,
138 options.message, options.save_template, patches)