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 Backporting to emacs-24
  50 =======================
  51
  52 If you have applied a fix to the trunk, but then decide that it should
  53 be applied to the emacs-24 branch, too, then
  54
  55 cd ~/emacs/trunk
  56 git log
  57
  58 and find the commit you're looking for.  Then find the commit ID,
  59 which will look like
  60
  61 commit 958b768a6534ae6e77a8547a56fc31b46b63710b
  62
  63 cd ~/emacs/emacs-24
  64 git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
  65
  66 and add "Backport:" to the commit string.  Then
  67
  68 git push
  69
  70
  71 Merging emacs-24 to trunk/master
  72 ================================
  73
  74 It is recommended to use the file gitmerge.el in the admin directory
  75 for merging 'emacs-24' into 'master'.  It will take care of many
  76 things which would otherwise have to be done manually, like ignoring
  77 commits that should not land in master, fixing up ChangeLogs and
  78 automatically dealing with certain types of conflicts.  If you really
  79 want to, you can do the merge manually, but then you're on your own.
  80 If you still choose to do that, make absolutely sure that you *always*
  81 use the 'merge' command to transport commits from 'emacs-24' to
  82 'master'.  *Never* use 'cherry-pick'!  If you don't know why, then you
  83 shouldn't manually do the merge in the first place; just use
  84 gitmerge.el instead.
  85
  86 How to use gitmerge.el:
  87
  88 Enter the Emacs repository, checkout 'master' and make sure it's
  89 up-to-date by doing a pull.  Then start Emacs with
  90
  91   emacs -l admin/gitmerge.el -f gitmerge
  92
  93 You'll be asked for the branch to merge, which will default to
  94 'origin/emacs-24', which you should accept.  Merging a local tracking
  95 branch is discouraged, since it might not be up-to-date, or worse,
  96 contain commits from you which are not yet pushed upstream.
  97
  98 You will now see the list of commits from 'emacs-24' which are not yet
  99 merged to 'master'.  You might also see commits that are already
 100 marked for "skipping", which means that they will be merged with a
 101 different merge strategy ('ours'), which will effectively ignore the
 102 commit's diff while still being seen as merged, so it won't turn up
 103 again in future merges.  Recognizing these kinds of commits is done
 104 with a simple regexp searching the log for strings like 'backport' or
 105 'merge', so you'll probably see false positives as well as false
 106 negatives.  Carefully go through the commits, investigate them by
 107 hitting 'l', 'd' and 'f', and mark or unmark them for skipping with
 108 's'.  When you're done, hit 'm' to start the merge.
 109
 110 You'll likely get conflicts during the process which cannot be dealt
 111 with automatically.  In that case, the merge will stop and show you
 112 the list of conflicted files.  Resolve those conflicts as usual using
 113 smerge and restart gitmerge (remember to enter the repository when
 114 doing that).  You don't have to 'add' the resolved files and 'commit'
 115 the resulting merge, but if you really want to, feel free to do that.
 116 Note you can also resume gitmerge in a new Emacs session, since the
 117 current state will be saved to disk.
 118
 119 When everything's done, look hard at the resulting merge.  Skipping
 120 commits requires separate merges, so don't be surprised to see more
 121 than one merge commit.  If you're happy, push.
 122
 123 Warnings about X11 forwarding
 124 =============================
 125
 126 If you get warnings like
 127
 128 Warning: No xauth data; using fake authentication data for X11 forwarding.
 129 X11 forwarding request failed on channel 0
 130
 131 when pulling or pushing data, add the following to the start of
 132 ~/.ssh/config:
 133
 134 Host git.sv.gnu.org
 135    ForwardX11 no