admin/notes/git-workflow

   1 (This is a draft.  The method here won't actually work yet, because
   2 neither git-new-workdir nor merge-changelog are in the Emacs
   3 distribution yet.)
   4
   5 Setting up and using git for normal, simple bugfixing
   6 =====================================================
   7
   8 If you haven't configured git before you should first do:
   9
  10 git config --global user.name "Frank Chu"
  11 git config --global user.email "fchu@example.com"
  12
  13 Initial setup
  14 =============
  15
  16 Then we want to clone the repository.  We normally want to have both
  17 the current trunk and the emacs-24 branch.
  18
  19 mkdir ~/emacs
  20 cd ~/emacs
  21 git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git
  22 mv emacs trunk
  23 (cd trunk; git config push.default current)
  24 ./trunk/admin/git-new-workdir trunk emacs-24
  25 cd emacs-24
  26 git checkout emacs-24
  27 git config push.default current
  28
  29 You now have both branches conveniently accessible, and you can do
  30 "git pull" in them once in a while to keep updated.
  31
  32
  33 Fixing bugs
  34 ===========
  35
  36 You edit the files in either branch, 'M-x vc-dir', and check in your
  37 changes.  Then you need to push the data to the main repository.  This
  38 will usually fail, since somebody else has pushed other changes in the
  39 meantime.  To fix this, say
  40
  41 git pull --rebase
  42
  43 which will update your repository, and then re-apply your changes on
  44 top of that.  Then say
  45
  46 git push
  47
  48
  49 Sending patches
  50 ===============
  51
  52 If you lack push access or would like feedback before pushing a patch,
  53 you commit your change locally and then send a patch file as a bug report
  54 as described in ../../CONTRIBUTE.
  55
  56
  57 Backporting to emacs-24
  58 =======================
  59
  60 If you have applied a fix to the trunk, but then decide that it should
  61 be applied to the emacs-24 branch, too, then
  62
  63 cd ~/emacs/trunk
  64 git log
  65
  66 and find the commit you're looking for.  Then find the commit ID,
  67 which will look like
  68
  69 commit 958b768a6534ae6e77a8547a56fc31b46b63710b
  70
  71 cd ~/emacs/emacs-24
  72 git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
  73
  74 and add "Backport:" to the commit string.  Then
  75
  76 git push
  77
  78
  79 Merging emacs-24 to trunk/master
  80 ================================
  81
  82 It is recommended to use the file gitmerge.el in the admin directory
  83 for merging 'emacs-24' into 'master'.  It will take care of many
  84 things which would otherwise have to be done manually, like ignoring
  85 commits that should not land in master, fixing up ChangeLogs and
  86 automatically dealing with certain types of conflicts.  If you really
  87 want to, you can do the merge manually, but then you're on your own.
  88 If you still choose to do that, make absolutely sure that you *always*
  89 use the 'merge' command to transport commits from 'emacs-24' to
  90 'master'.  *Never* use 'cherry-pick'!  If you don't know why, then you
  91 shouldn't manually do the merge in the first place; just use
  92 gitmerge.el instead.
  93
  94 How to use gitmerge.el:
  95
  96 Enter the Emacs repository, checkout 'master' and make sure it's
  97 up-to-date by doing a pull.  Then start Emacs with
  98
  99   emacs -l admin/gitmerge.el -f gitmerge
 100
 101 You'll be asked for the branch to merge, which will default to
 102 'origin/emacs-24', which you should accept.  Merging a local tracking
 103 branch is discouraged, since it might not be up-to-date, or worse,
 104 contain commits from you which are not yet pushed upstream.
 105
 106 You will now see the list of commits from 'emacs-24' which are not yet
 107 merged to 'master'.  You might also see commits that are already
 108 marked for "skipping", which means that they will be merged with a
 109 different merge strategy ('ours'), which will effectively ignore the
 110 commit's diff while still being seen as merged, so it won't turn up
 111 again in future merges.  Recognizing these kinds of commits is done
 112 with a simple regexp searching the log for strings like 'backport' or
 113 'merge', so you'll probably see false positives as well as false
 114 negatives.  Carefully go through the commits, investigate them by
 115 hitting 'l', 'd' and 'f', and mark or unmark them for skipping with
 116 's'.  When you're done, hit 'm' to start the merge.
 117
 118 You'll likely get conflicts during the process which cannot be dealt
 119 with automatically.  In that case, the merge will stop and show you
 120 the list of conflicted files.  Resolve those conflicts as usual using
 121 smerge and restart gitmerge (remember to enter the repository when
 122 doing that).  You don't have to 'add' the resolved files and 'commit'
 123 the resulting merge, but if you really want to, feel free to do that.
 124 Note you can also resume gitmerge in a new Emacs session, since the
 125 current state will be saved to disk.
 126
 127 When everything's done, look hard at the resulting merge.  Skipping
 128 commits requires separate merges, so don't be surprised to see more
 129 than one merge commit.  If you're happy, push.
 130
 131 Warnings about X11 forwarding
 132 =============================
 133
 134 If you get warnings like
 135
 136 Warning: No xauth data; using fake authentication data for X11 forwarding.
 137 X11 forwarding request failed on channel 0
 138
 139 when pulling or pushing data, add the following to the start of
 140 ~/.ssh/config:
 141
 142 Host git.sv.gnu.org
 143    ForwardX11 no