168 lines
5.9 KiB
Plaintext
168 lines
5.9 KiB
Plaintext
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"
|
|
git config --global transfer.fsckObjects true
|
|
|
|
(See the thread "Recommend these .gitconfig settings for git integrity."
|
|
[https://lists.gnu.org/r/emacs-devel/2016-01/threads.html#01802]
|
|
for more details about why that last line is there.)
|
|
|
|
Initial setup
|
|
=============
|
|
|
|
Then we want to clone the repository. We normally want to have both
|
|
the current master and (if there is one) the active release branch
|
|
(eg emacs-30).
|
|
|
|
mkdir ~/emacs
|
|
cd ~/emacs
|
|
git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git master
|
|
cd master
|
|
git config push.default current
|
|
git worktree add ../emacs-30 emacs-30
|
|
|
|
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 release branch
|
|
=============================
|
|
|
|
If you have applied a fix to the master, but then decide that it should
|
|
be applied to the release branch, too, then
|
|
|
|
cd ~/emacs/master
|
|
git log
|
|
|
|
and find the commit you're looking for. Then find the commit ID,
|
|
which will look like
|
|
|
|
commit 958b768a6534ae6e77a8547a56fc31b46b63710b
|
|
|
|
cd ~/emacs/emacs-30
|
|
git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
|
|
|
|
and add "Backport:" to the commit string. Then
|
|
|
|
git push
|
|
|
|
|
|
Reverting on release branch
|
|
===========================
|
|
|
|
If a commit is made to the release branch, and then it is later
|
|
decided that this change should only be on the master branch, the
|
|
simplest way to handle this is to revert the commit on the release
|
|
branch, and include in the associated log entry "do not merge to master".
|
|
(Otherwise, the reversion may get merged to master, and inadvertently
|
|
clobber the change on master if it has been manually made there.)
|
|
|
|
|
|
Merging release branch to the master
|
|
====================================
|
|
|
|
It is recommended to use the file gitmerge.el in the admin directory
|
|
for merging the release branch 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 the release branch 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 a pull. Then start Emacs with
|
|
|
|
emacs -l admin/gitmerge.el -f gitmerge
|
|
|
|
You'll be asked for the branch to merge, which will default to
|
|
(eg) 'origin/emacs-30', 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 the release branch that 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. If you're happy, push.
|
|
|
|
|
|
Long-lived feature branches
|
|
===========================
|
|
|
|
The conventions for formatting commit log messages set out in CONTRIBUTE
|
|
don't apply to commits made to feature branches.
|
|
Thus, feel free to commit little and often, with short and simple commit
|
|
messages. This practice can ease development by making 'git bisect' and
|
|
'git revert' more effective.
|
|
|
|
The commit merging the feature branch to master, on the other hand,
|
|
should follow the usual commit log message conventions.
|
|
|
|
|
|
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
|