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