doc/git.rst

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