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
| | (This is a draft. The method here won't actually work yet, because
git-new-workdir is not in the Emacs distribution yet.)
Setting up and using git for normal, simple bugfixing
=====================================================
If you haven't configured git before you should first do:
git config --global user.name "Frank Chu"
git config --global user.email "fchu@example.com"
Initial setup
=============
Then we want to clone the repository. We normally want to have both
the current trunk and the emacs-25 branch.
mkdir ~/emacs
cd ~/emacs
git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git
mv emacs trunk
(cd trunk; git config push.default current)
./trunk/admin/git-new-workdir trunk emacs-25
cd emacs-25
git checkout emacs-25
git config push.default current
You now have both branches conveniently accessible, and you can do
"git pull" in them once in a while to keep updated.
Fixing bugs
===========
You edit the files in either branch, 'M-x vc-dir', and check in your
changes. Then you need to push the data to the main repository. This
will usually fail, since somebody else has pushed other changes in the
meantime. To fix this, say
git pull --rebase
which will update your repository, and then re-apply your changes on
top of that. Then say
git push
Sending patches
===============
If you lack push access or would like feedback before pushing a patch,
you commit your change locally and then send a patch file as a bug report
as described in ../../CONTRIBUTE.
Backporting to emacs-25
=======================
If you have applied a fix to the trunk, but then decide that it should
be applied to the emacs-25 branch, too, then
cd ~/emacs/trunk
git log
and find the commit you're looking for. Then find the commit ID,
which will look like
commit 958b768a6534ae6e77a8547a56fc31b46b63710b
cd ~/emacs/emacs-25
git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
and add "Backport:" to the commit string. Then
git push
Merging emacs-25 to trunk/master
================================
It is recommended to use the file gitmerge.el in the admin directory
for merging 'emacs-25' into 'master'. It will take care of many
things which would otherwise have to be done manually, like ignoring
commits that should not land in master, fixing up ChangeLogs and
automatically dealing with certain types of conflicts. If you really
want to, you can do the merge manually, but then you're on your own.
If you still choose to do that, make absolutely sure that you *always*
use the 'merge' command to transport commits from 'emacs-25' to
'master'. *Never* use 'cherry-pick'! If you don't know why, then you
shouldn't manually do the merge in the first place; just use
gitmerge.el instead.
How to use gitmerge.el:
Enter the Emacs repository, checkout 'master' and make sure it's
up-to-date by doing:
git pull
Then bring the file ChangeLog-25.1 up-to-date by doing:
make change-history
Then start Emacs with
emacs -l admin/gitmerge.el -f gitmerge
You'll be asked for the branch to merge, which will default to
'origin/emacs-25', which you should accept. Merging a local tracking
branch is discouraged, since it might not be up-to-date, or worse,
contain commits from you which are not yet pushed upstream.
You will now see the list of commits from 'emacs-25' which are not yet
merged to 'master'. You might also see commits that are already
marked for "skipping", which means that they will be merged with a
different merge strategy ('ours'), which will effectively ignore the
commit's diff while still being seen as merged, so it won't turn up
again in future merges. Recognizing these kinds of commits is done
with a simple regexp searching the log for strings like 'backport' or
'merge', so you'll probably see false positives as well as false
negatives. Carefully go through the commits, investigate them by
hitting 'l', 'd' and 'f', and mark or unmark them for skipping with
's'. When you're done, hit 'm' to start the merge.
You'll likely get conflicts during the process which cannot be dealt
with automatically. In that case, the merge will stop and show you
the list of conflicted files. Resolve those conflicts as usual using
smerge and restart gitmerge (remember to enter the repository when
doing that). You don't have to 'add' the resolved files and 'commit'
the resulting merge, but if you really want to, feel free to do that.
Note you can also resume gitmerge in a new Emacs session, since the
current state will be saved to disk.
When everything's done, look hard at the resulting merge. Skipping
commits requires separate merges, so don't be surprised to see more
than one merge commit.
The above steps should have updated ChangeLog-25.0 without altering
ChangeLog-25.1. If you were to run 'make change-history' now, this
would mess up ChangeLog-25.1 by adding a redundant copy of the newly
merged ChangeLog entries. Prevent this by editing ChangeLog-25.1 to
say that it records revisions to the current master commit
(inclusive), by doing the following shell commands:
commitid=$(git log -1 --format=%H)
sed "s/^commit .* (inclusive)\\.\$/commit $commitid (inclusive)./" ChangeLog-25.1 >ChangeLog-25.1.tmp
cp ChangeLog-25.1.tmp ChangeLog-25.1
git commit -m"Omit ChangeLog entries from emacs-25 merge" ChangeLog-25.1
If you're happy, push.
Warnings about X11 forwarding
=============================
If you get warnings like
Warning: No xauth data; using fake authentication data for X11 forwarding.
X11 forwarding request failed on channel 0
when pulling or pushing data, add the following to the start of
~/.ssh/config:
Host git.sv.gnu.org
ForwardX11 no
|