1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<html>
<head>
<title>Writing Log Entries for Merges</title>
</head>
<body>
<a name="Writing_Log_Entries_for_Merges"></a>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
<h2 align=center>Writing Log Entries for Merges</h2>
<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
<b>next: </b><a href="arbitrary-patching.html#Arbitrary_Patching_with_delta-patch">Arbitrary Patching with delta-patch</a></br>
<b>prev: </b><a href="star-topology.html#Star_Topology_Branching_and_Merging">Star Topology Branching and Merging</a></br>
</small>
<br>
<p><a name="index-pt:0"></a>
<a name="index-pt:1"></a>
</p><p>Suppose you have used <code>star-merge</code>
or some other commands to merge
two or more branches. You are ready to commit those changes, but
first you have to write a log message.
</p><p>All of the changes you've just merged are already explained in
existing log messages. Your new log message can simply summarize the
changes, and point to the more detailed log entries. <code>arch</code>
has
commands which help with this.
</p><p>The command:
</p><pre>
% larch new-on-branch [--reverse] [--dir .] VERSION
</pre>
<p>reports a list of patches found in a project tree, but not previously
merged with <code>VERSION</code>
. Those patches are the ones that were added
by your merging activity.
</p><p>You can print a summary of the changes made by those patches by using
<code>xargs</code>
and the <code>log-ls</code>
command. For example, the main development
path for arch <code>1</code>
.0 is called <code>arch--devo--1.0</code>
. I develop new features
on various branches. When it comes time to write a log message before
committing a merge to <code>arch--devo</code>
, I use:
</p><pre>
% larch new-on-branch --reverse arch--devo--1.0 \
| xargs larch log-ls --full --summary
</pre>
<pre>
lord@regexps.com--2002/arch--lord--1.0--patch-14
`merge-points' fixes and `new-on-branch' speed-up
lord@regexps.com--2002/arch--lord--1.0--patch-13
Use --dir consistently.
lord@regexps.com--2002/arch--lord--1.0--patch-12
output format touch-ups
</pre>
<p>That idiom is captured, along with a little bit of formatting, by the
command <code>log-for-merge</code>
:
</p><pre>
% larch log-for-merge arch--devo--1.0
</pre>
<pre>
Patches applied:
</pre>
<pre>
* lord@regexps.com--2002/arch--lord--1.0--patch-14
`merge-points' fixes and `new-on-branch' speed-up
</pre>
<pre>
* lord@regexps.com--2002/arch--lord--1.0--patch-13
Use --dir consistently.
</pre>
<pre>
* lord@regexps.com--2002/arch--lord--1.0--patch-12
output format touch-ups
</pre>
<p>(An advantage of using the formate generated by <code>log-for-merge</code>
is
that it is understood by other <code>arch</code>
commands which automatically
format web pages from <code>ChangeLogs</code>
.)
</p><p>That works out nicely as part of a log message if you organize
<code>ChangeLogs</code>
as I do. In the top-level of the <code>arch</code>
source code, I
have an automatic <code>ChangeLog</code>
for the <code>arch--devo--branch</code>
:
</p><pre>
arch/
arch/ChangeLog
</pre>
<p>I created that once, using:
</p><pre>
% larch changelog arch--devo--1.0 > ChangeLog
</pre>
<p>and after that, it is automatically updated with every <code>commit</code>
,
<code>update</code>
, or similar operation.
</p><p>I also have per-branch <code>ChangeLogs</code>
:
</p><pre>
arch/
arch/ChangeLog.d/
arch/ChangeLog.d/lord@regexps.com--2002/
arch/ChangeLog.d/lord@regexps.com--2002/ChangeLog.lord--1.0
arch/ChangeLog.d/lord@regexps.com--2002/ChangeLog.lord-doc--1.0
</pre>
<p>Note that <code>lord@regexps.com...</code>
is the name of my archive. Two
branches that I develop on are:
</p><pre>
arch--lord--1.0
arch--lord-doc--1.0
</pre>
<p>and each of those has their own ChangeLog. I created those logs with
similar commands. For example:
</p><pre>
% larch changelog arch--lord--1.0 > ChangeLog.lord
</pre>
<p>To write the log entry for a merge, I start with the output of
<code>log-for-merge</code>
application shown above, and add a tiny bit of extra
text for people browsing the ChangeLogs as plain text:
</p><pre>
Summary: merge with `lord'
Keywords:
</pre>
<pre>
Merge with branch `lord'.
</pre>
<pre>
For details, see
</pre>
<pre>
Changelog.d/lord@regexps.com--2002/ChangeLog.lord--1.0
</pre>
<pre>
Patches applied:
</pre>
<pre>
* lord@regexps.com--2002/arch--lord--1.0--patch-14
`merge-points' fixes and `new-on-branch' speed-up
</pre>
<pre>
* lord@regexps.com--2002/arch--lord--1.0--patch-13
Use --dir consistently.
</pre>
<pre>
* lord@regexps.com--2002/arch--lord--1.0--patch-12
output format touch-ups
</pre>
<p>Note that for each of the <code>Patches applied</code>
, there is a corresponding
<code>ChangeLog</code>
entry in <code>ChangeLog.d</code>
.
</p>
<small><i>arch: The arch Revision Control System
</i></small><br>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
</body>
|
