docs/vanilla_msysgit_workflow.md

   1 # Vanilla msysgit workflow
   2
   3 This describes how you can use msysgit on Windows to work on the Chromium git
   4 repository, without setting up Cygwin or hacking the `git cl`, `git try` and
   5 other scripts to work under a regular Windows shell.
   6
   7 The basic setup is to set up a regular git checkout on a Linux (or Mac) box, and
   8 use this exclusively to create your branches and run tools such as `git cl`, and
   9 have your Windows box treat this git repository as its upstream.
  10
  11 The advantage is, you get a pretty clean setup on your Windows box that is
  12 unlikely to break when the various custom git tools like `git cl` change. The
  13 setup is also advantageous if you regularly build code on Windows and then want
  14 to test it on Linux, since all you need to test on your Linux box is a `git
  15 push` from Windows followed by building and testing under Linux.
  16
  17 The disadvantage is that it adds an extra layer between the Chromium git repo
  18 and your Windows checkout.  In my experience (joi@chromium.org) this does not
  19 actually slow you down much, if at all.
  20
  21 The most frequently used alternative to this workflow on Windows seems to be
  22 using Cygwin and creating a checkout directly according to the instructions at
  23 UsingGit. The advantage of that approach is you lose the extra overhead, the
  24 disadvantage seems to be mostly speed and having to run a Cygwin shell rather
  25 than just a normal Windows cmd.
  26
  27 Please note that the instructions below are mostly from memory so they may be
  28 slightly incorrect and steps may be missing.  Please feel free to update the
  29 page with corrections and additions based on your experience.
  30
  31 ## Details
  32
  33 Create your checkouts:
  34
  35 1.  Create a git checkout on your Linux box, with read/write abilities, as per
  36     UsingGit. The rest of these instructions assume it is located at
  37     /home/username/chrome
  38 1.  Install msysgit on your Windows box.
  39
  40 Starting a new topic branch:
  41
  42 1.   Linux: `git branch mytopic`
  43      (or you may want to use e.g. the LKGR script from UsingGit).
  44 1.   Windows: `git fetch` then `git checkout mytopic`
  45
  46 Normal workflow on Windows:
  47
  48 1.  ...edit/add some files...
  49 1.  `git commit -a -m "my awesome change"`
  50 1.  ...edit more...
  51 1.  `git commit -a -m "follow-up awesomeness"`
  52 1.  `git push`
  53
  54 Normal workflow on Linux:
  55
  56 *   (after `git push` from windows): `git cl upload && git try`
  57 *   (after LGTM and successful try): `git cl commit`
  58     (but note the `tot-mytopic` trick in the pipelining section below)
  59
  60 Avoiding excessive file changes (to limit amount of Visual Studio rebuilds when
  61 switching between branches):
  62
  63 *   Base all your different topic branches off of the same base branch; I
  64     generally create a new LKGR branch once every 2-3 working days and then `git
  65     merge` it to all of my topic branches.
  66 *   To track which base branch topic branches are based off, you can use a
  67     naming convention; I use e.g. lk0426 for an LKGR branch created April 26th,
  68     then use e.g. lk0426-topic1, lk0426-topic2 for the topic branches that have
  69     all changes merged from lk0426. I (joi@chromium.org) also have a script to
  70     update the base branch for topic branches and rename them - let me know if
  71     interested.
  72 *   Now that all your branch names are prefixed with the base revision (whether
  73     you use my naming convention or not), you can know before hand when you
  74     switch between branches on Windows whether you should expect a major
  75     rebuild, or a minor rebuild.  If you are able to remember which of your
  76     topic branches have .gyp changes and which don't (or I guess you could use
  77     `git diff` to figure this out), then you will also have a good idea whether
  78     you need to run `gclient runhooks` or not when you switch branches.  Another
  79     nice thing is that yu should never have to run `gclient sync` when you
  80     switch between branches with the same base revision, unless some of your
  81     branches have changes to DEPS files.
  82
  83 Pipelining:
  84
  85 1.  Linux:
  86     1.  `git checkout lk0426-mytopic`
  87     1.  `git checkout -b lk0426-mytopic-nextstep`
  88 1.  Windows:
  89     1.  `git fetch && git checkout lk0426-mytopic-nextstep`
  90     1.  ...work as usual...
  91     1.  `git push`
  92 1.  Later, on Linux:
  93     1.  `make_new_lkgr_branch lk0428`
  94     1.  `git merge lk0428 lk0426-mytopic`
  95     1.  `git branch -m lk0426-mytopic lk0428-mytopic` (to rename)
  96     1.  `git merge lk0428-mytopic lk0426-mytopic-nextstep`
  97     1.  `git branch -m lk0428-mytopic-nextstep lk0428-mytopic-nextstep`
  98         (to rename)
  99 1.  Later, when you want to commit one of the earlier changes in the pipeline;
 100     all on Linux.  The reason you may want to create the separate tip-of-tree
 101     branch is in case the trybots show your change failing on tip-of-tree and
 102     you need to do significant additional work, this avoids having to roll back
 103     the tip-of-tree merge:
 104
 105 Janitorial work on Windows:
 106
 107 *   When you rename branches on the Linux side, the Windows repo will not know
 108     automatically; so if you already had a branch `lk0426-mytopic` open on
 109     Windows and then `git fetch`, you will still have `lk0426-mytopic` even if
 110     that was renamed on the Linux side to `lk0428-mytopic`.
 111 *   Dealing with this is straight-forward; you just
 112     `git checkout lk0428-mytopic` to switch to the renamed (and likely updated)
 113     branch. Then `git branch -d lk0426-mytopic` to get rid of the tracking
 114     branch for the older name.  Then, occasionally, `git remotes prune origin`
 115     to prune remote tracking branches (you don't normally see these listed
 116     unless you do `git branch -a`).
 117
 118 Gotchas:
 119
 120 *   You should normally create your branches on Linux only, so that the Windows
 121     repo gets tracking branches for them.  Any branches you create in the
 122     Windows repo would be local to that repository, and so will be non-trivial
 123     to push to Linux.
 124 *   `git push` from Windows will fail if your Linux repo is checked out to the
 125     same branch. It is easy to switch back manually, but I also have a script I
 126     call `safepush` that switches the Linux-side branch for you before pushing;
 127     let me (joi@chromium.org) know if interested.