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