From 692322388c9f5bdebf2e8c4f7434c1d4769a04cc Mon Sep 17 00:00:00 2001 From: David Engster Date: Thu, 27 Nov 2014 23:17:40 +0100 Subject: [PATCH] admin: Add documentation for gitmerge.el * gitmerge.el: New file. * notes/git-workflow: Add documentation for using it. --- admin/ChangeLog | 1 + admin/notes/git-workflow | 56 ++++++++++++++++++++++++++++++++++++---- 2 files changed, 52 insertions(+), 5 deletions(-) diff --git a/admin/ChangeLog b/admin/ChangeLog index c30e4bea5b6..84aea47ae9e 100644 --- a/admin/ChangeLog +++ b/admin/ChangeLog @@ -1,6 +1,7 @@ 2014-11-27 David Engster * gitmerge.el: New file. + * notes/git-workflow: Add documentation for using it. 2014-11-17 Oscar Fuentes diff --git a/admin/notes/git-workflow b/admin/notes/git-workflow index 71ebd2abc96..d1d105a8a7a 100644 --- a/admin/notes/git-workflow +++ b/admin/notes/git-workflow @@ -68,11 +68,57 @@ and add "Backport:" to the commit string. Then git push -Merging emacs-24 to trunk -========================= - -This has yet to be written. - +Merging emacs-24 to trunk/master +================================ + +It is recommended to use the file gitmerge.el in the admin directory +for merging 'emacs-24' 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-24' 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-24', 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-24' 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 ============================= -- 2.39.5