doc/git.rst

   1 =============
   2 Bazaar to git
   3 =============
   4
   5 Initializing a working copy
   6 ---------------------------
   7
   8 Use the easy-setup shell script::
   9
  10      curl -O https://raw.githubusercontent.com/odoo/odoo/master/odoo.py | python2
  11
  12 it will will ask a few questions and create a local copy.
  13
  14 Git concepts
  15 ------------
  16
  17 Remotes
  18 ~~~~~~~
  19
  20 Remotes are "remote repositories" which can be fetched from and pushed
  21 to. Remotes can be listed with ``git remote``\ [#remote-default]_ and a local
  22 repository can have any number of remotes. The setup script creates 2 remotes:
  23
  24 ``odoo``
  25     the official repository and main branches, roughly corresponds to the old
  26     "mainline" branches in bazaar. You should never need to push to it, and by
  27     default your local copy is configured to forbid it.
  28 ``odoo-dev``
  29     a grab-bag of development branches, you can push your work to it so other
  30     coworkers can work with you.
  31
  32 Branches
  33 ~~~~~~~~
  34
  35 The working copy and each remote contain multiple branches. Local branches can
  36 be listed by ``git branch``, remote branches can be listed with ``git branch
  37 -r``. Both types can be listed with ``git branch -a``.
  38
  39 Work is only possible on local branches, even though it's possible to check
  40 out a remote branch work on it will be lost.
  41
  42 Staging
  43 ~~~~~~~
  44
  45 ``bzr commit`` takes all alterations to the working copy and creates a commit
  46 from them. Git has an intermediate step called "staging". ``git commit`` will
  47 create a commit from what has been staged, not from the working copy\
  48 [#commit-no-staging]_. Staging is done with ``git add``. A commit with nothing
  49 staged is a null operation.
  50
  51 .. warning::
  52
  53     It's possible for a single file to have changes in both the index and
  54     working copy: if a file is altered, staged and altered again, the second
  55     set of change has to be staged separately
  56
  57 SHA1
  58 ~~~~
  59
  60 Git has no sequential identifier, each commit is uniquely identified by a SHA
  61 (40 hexadecimal characters) roughly corresponding to a bazaar
  62 revision-id. Providing the full sha is rarely necessary, any unique leading
  63 substring is sufficient, e.g. ``dae86e`` will probably stand in for
  64 ``dae86e1950b1277e545cee180551750029cfe735``.
  65
  66 Basic development workflow
  67 --------------------------
  68
  69 * update your remotes with ``git fetch --all``
  70 * create your development branch with ``git checkout -b <branch_name>
  71   <source_branch>``. For instance if you wanted to add support for full-text
  72   search in master you could use ``git checkout -b master-fts-xxx odoo/master``
  73 * do your changes, stage them with ``git add`` and commit them with ``git
  74   commit``
  75 * if your branch is long-lived, you may want to update it to its parent
  76
  77   - update the remotes with ``git fetch --all``
  78   - merge the remote branch into the local one with ``git merge --no-ff
  79     odoo/master``
  80
  81 * to push the branch to the development repository, use ``git push -u dev
  82   <branchname>``, this will automatically create a branch called
  83   ``<branchname>`` on dev. Next time around you do not have to use ``-u``
  84 * once the feature is done, create a pull request
  85
  86 .. should we promote rebase? That would lead to cleaner histories, but if the
  87    branch is already pushed it requires force-pushing since the branch can't
  88    be fast-forwarded
  89
  90 .. git automatically creates a merge commit, should we configure merge with
  91    --no-commit?
  92
  93 .. make --no-ff the default in the config script?
  94
  95 .. warn about ``git pull``? It is ~ ``git fetch; git merge`` and should
  96    probably be avoided
  97
  98 .. CLI tools?
  99
 100 .. format for specifying issues? e.g. closes #42?
 101
 102 Tasks
 103 -----
 104
 105 Converting your feature branches from bazaar
 106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 107
 108 `The readme`_ has some instructions.
 109
 110 Viewing history: ``git log``
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113 ``git log`` fulfills the same role as ``bzr log`` and is fairly similar, with
 114 a few differences:
 115
 116 * ``git log`` has no ``-r`` argument, its first argument (optional) is a
 117   revision spec
 118 * ``git log`` always operates on ranges, if a single commit is provided (via
 119   hash, tag, branch or other) it will list the specified commit *and all of
 120   its ancestors*. To see a single commit, use ``git show``.
 121 * ``git log``'s second positional argument is a path (file or
 122   directory). Because both are optional, if both a revision and a file match
 123   the revision will be selected. It is recommended to use ``--`` before a file
 124   path::
 125
 126     git log -- filepath
 127
 128 * ``git log`` will actually work if given a directory, instead of pegging the
 129   CPU forever
 130 * ``git log`` works with removed files or directories without having to
 131   provide a revision during which the file or directory still existed
 132 * ``git log`` has *lots* of options to customize the output, e.g. ``-p`` will
 133   display the changes to each file\ [#log-patch-empty]_, ``--name-status``
 134   will list the changed files and how they changed SVN-style (with a ``M`` or
 135   ``D`` prefix), ``--name-only`` will just list the changed files, ``--stat``
 136   generates a diffstat view, ``--grep`` filters by grepping on the commit
 137   message, …
 138
 139 Reverting uncommitted changes
 140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 141
 142 .. danger:: Do *not* use ``git revert``, it does something completely
 143             different than ``bzr revert``
 144
 145 * If you have altered files which you want to revert, use ``git checkout --
 146   <path>``. To revert every file in the directory, use ``git checkout -- .``
 147 * If you have staged a file and you want to unstage it, use ``git reset HEAD
 148   <file>``. This will not revert the file's changes, the file will be marked
 149   as modified again
 150
 151 Diffing: ``git diff``
 152 ~~~~~~~~~~~~~~~~~~~~~
 153
 154 ``git diff`` is fairly similar to ``bzr diff``: it compares the working copy
 155 with stored content and can be restricted to a given file path. However:
 156
 157 * ``git diff`` compares the working copy and the staging area, not the latest
 158   commit
 159 * ``git diff --staged`` compares the staging area and the latest commit
 160 * ``git diff HEAD`` ignores the staging area and compares the working copy
 161   with the latest commit. More generally ``git diff <commit>`` will diff the
 162   working copy and the specified commit
 163 * to diff between commits, simply pass the commit identifiers (no ``-r``
 164   argument)
 165 * ``git diff --stat`` provides a diffstat-view of the diff, and can be
 166   combined with other flags. It can be used as an intermediate between ``git
 167   status`` and ``git status -s``
 168
 169 Update to a previous revision
 170 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 171
 172 ``git checkout`` takes an arbitrary commit, the equivalent to ``bzr update
 173 -r<rev>`` is thus ``git checkout <rev>``.
 174
 175 File from the past
 176 ~~~~~~~~~~~~~~~~~~
 177
 178 ``bzr cat -r<revision> <filename>`` shows the file ``<filename>`` as it was at
 179 ``<revision>``. The Git equivalent is ``git show <revision>:<filename>``
 180
 181 Incorrect last commit: fix it
 182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 183
 184 If the last commit has to be fixed a bit (error, missing data,
 185 incomplete/incorrect commit message) it can be fixed with ``git commit
 186 --amend``. Instead of creating a new commit, it adds whatever is being
 187 committed to the previous commit.
 188
 189 Incorrect last commit: remove it
 190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 191
 192 If the last commit has to be removed entirely (similar to ``bzr uncommit``),
 193 use ``git reset HEAD~1``.
 194
 195 .. danger:: do not use this command or the previous one on commits you have
 196             already pushed
 197
 198 Useful tips
 199 -----------
 200
 201 Partial operations
 202 ~~~~~~~~~~~~~~~~~~
 203
 204 ``checkout``, ``add``, ``commit``, ``reset`` and ``stash`` can take a ``-p``
 205 flag, which allows operating (staging, reverting, ...) on a subset of the
 206 file. It opens a UI allowing the selection (or not) of each patch hunk, and
 207 even the splitting of hunk if they're too big.
 208
 209 Allows reverting only part of the changes to a file, or cleanly splitting
 210 refactorings and fixes mixed in a file.
 211
 212 short status
 213 ~~~~~~~~~~~~
 214
 215 The default ``status`` command is very verbose (though useful, it provides
 216 instructions for reverting things). The ``-s`` flag provides an SVN-like
 217 display instead with just a listing of files and :abbr:`A (Added)`, :abbr:`M
 218 (Modified)` or :abbr:`D (Deleted)` flags next to them. Each file can have 2
 219 flags, the first is for the index (difference between the last commit and the
 220 index) and the and the second is for the working copy (difference between the
 221 index and the working copy).
 222
 223 ``checkout`` shortcut
 224 ~~~~~~~~~~~~~~~~~~~~~
 225
 226 ``checkout -`` will behave like ``cd -``, it will switch to the previously
 227 checked-out branch/commit
 228
 229 .. [#remote-default] by default, ``git remote`` will only give the names of
 230                      the various remotes. ``git remote -v`` will give the name
 231                      and URL of each remote.
 232
 233 .. [#commit-no-staging] the ``-a`` option will automatically stage modified
 234                         and deleted files
 235
 236 .. [#log-patch-empty] but only the changes performed by this actual commit,
 237                       for a merge the merged changes are not considered part
 238                       of the merge commit
 239
 240 .. _the readme: https://github.com/odoo/odoo/blob/master/README.md#migration-from-bazaar