mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-14 09:39:42 +00:00
f8bf1b35bf
* CONTRIBUTE: Mention URLs and info nodes more consistently, avoiding possibly-confusing punctuation adjacent to a URL, and giving full shell commands for 'info'. Start with a brief but complete how-to, for people who want to get started right away. Then briefly discuss how to join the development process in the typical order. Omit needless words. Update some of the now-obsolete file names, info node names, and quoting styles. Better document emacs-NN branches and how they are merged. * admin/notes/git-workflow: Change emacs-24 to emacs-25, and trunk to master. This file still needs work.
147 lines
5.1 KiB
Plaintext
147 lines
5.1 KiB
Plaintext
(This is a draft. The method here won't actually work yet, because
|
|
neither git-new-workdir nor merge-changelog are 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"
|
|
git config --global transfer.fsckObjects true
|
|
|
|
(See the thread "Recommend these .gitconfig settings for git integrity."
|
|
[https://lists.gnu.org/archive/html/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 the emacs-25 branch.
|
|
|
|
mkdir ~/emacs
|
|
cd ~/emacs
|
|
git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git master
|
|
(cd master; git config push.default current)
|
|
./master/admin/git-new-workdir master emacs-25
|
|
cd emacs-25
|
|
git checkout emacs-25
|
|
|
|
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 master, but then decide that it should
|
|
be applied to the emacs-25 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-25
|
|
git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
|
|
|
|
and add "Backport:" to the commit string. Then
|
|
|
|
git push
|
|
|
|
|
|
Merging emacs-25 to the 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 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
|
|
'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. 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
|