docs/git_tips.md

   1 # Git Tips
   2
   3 When using Git, there are a few tips that are particularly useful when working
   4 on the Chromium codebase, especially due to its size.
   5
   6 [TOC]
   7
   8 ## Remember the basic git convention:
   9
  10     git COMMAND [FLAGS] [ARGUMENTS]
  11
  12 Various git commands have underlying executable with a hyphenated name, such as
  13 `git-grep`, but these can also be called via the `git` wrapper script as
  14 `git grep` (and `man` should work either way too).
  15
  16 ## Git references
  17
  18 The following resources can provide background on how Git works:
  19
  20 *   [Git-SVN Crash Course](http://git-scm.com/course/svn.html) -- this crash
  21     course is useful for Subversion users  witching to Git.
  22 *   [Think Like (a) Git](http://think-like-a-git.net/) -- does a great job of
  23     explaining the main purpose of Git operations.
  24 *   [Git User's Manual](http://schacon.github.com/git/user-manual.html) -- a
  25     great resource to learn more about ho to use Git properly.
  26 *   [A Visual Git Reference](http://marklodato.github.com/visual-git-guide/index-en.html)
  27     -- a resource that explains various Git operations for visual reasons.
  28 *   [Git Cheat Sheet](http://cheat.errtheblog.com/s/git) -- now that you
  29     understand Git, here's a cheat sheet to quickly remind you of all the
  30     commands you need.
  31
  32 ## Committing changes
  33
  34 For a simple workflow (always commit all changed files, don't keep local
  35 revisions), the following script handles check; you may wish to call it `gci`
  36 (git commit) or similar.
  37
  38 Amending a single revision is generally easier for various reasons, notably for
  39 rebasing and for checking that CLs have been committed. However, if you don't
  40 use local revisions (a local branch with multiple revisions), you should make
  41 sure to upload revisions periodically to code review if you ever need to go to
  42 an old version of a CL.
  43
  44 ```bash
  45 #!/bin/bash
  46 # Commit all, amending if not initial commit.
  47 if git status | grep -q "# Your branch is ahead of 'master' by 1 commit."
  48 then
  49   git commit --all --amend
  50 else
  51   git commit --all  # initial, not amendment
  52 fi
  53 ```
  54
  55 ## Listing and changing branches
  56
  57 ```shell
  58 git branch  # list branches
  59 git checkout -  # change to last branch
  60 ```
  61
  62 To quickly list the 5 most recent branches, add the following to `.gitconfig`
  63 in the `[alias]` section:
  64
  65 ```shell
  66 last5 = "!git for-each-ref --sort=committerdate refs/heads/ \
  67     --format='%(committerdate:short) %(refname:short)' | tail -5 | cut -c 12-"
  68 ```
  69
  70 A nicely color-coded list, sorted in descending order by date, can be made by
  71 the following bash function:
  72
  73 ```bash
  74 git-list-branches-by-date() {
  75   local current_branch=$(git rev-parse --symbolic-full-name --abbrev-ref HEAD)
  76   local normal_text=$(echo -ne '\E[0m')
  77   local yellow_text=$(echo -ne '\E[0;33m')
  78   local yellow_bg=$(echo -ne '\E[7;33m')
  79   git for-each-ref --sort=-committerdate \
  80       --format=$'  %(refname:short)  \
  81           \t%(committerdate:short)\t%(authorname)\t%(objectname:short)' \
  82           refs/heads \
  83       | column -t -s $'\t' -n \
  84       | sed -E "s:^  (${current_branch}) :* ${yellow_bg}\1${normal_text} :" \
  85       | sed -E "s:^  ([^ ]+):  ${yellow_text}\1${normal_text}:"
  86 }
  87 ```
  88
  89 ## Searching
  90
  91 Use `git-grep` instead of `grep` and `git-ls-files` instead of `find`, as these
  92 search only files in the index or _tracked_ files in the work tree, rather than
  93 all files in the work tree.
  94
  95 Note that `git-ls-files` is rather simpler than `find`, so you'll often need to
  96 use `xargs` instead of `-exec` if you want to process matching files.
  97
  98 ## Global changes
  99
 100 To make global changes across the source tree, it's often easiest to use `sed`
 101 with `git-ls-files`, using `-i` for in-place changing (this is generally safe,
 102 as we don't use symlinks much, but there are few places that do). Remember that
 103 you don't need to use `xargs`, since sed can take multiple input files. E.g., to
 104 strip trailing whitespace from C++ and header files:
 105
 106     sed -i -E 's/\s+$//' $(git ls-files '*.cpp' '*.h')
 107
 108
 109 You may also find `git-grep` useful for limiting the scope of your changes,
 110 using `-l` for listing files.
 111
 112     sed -i -E '...' $(git grep -lw Foo '*.cpp' '*.h')
 113
 114 Remember that you can restrict sed actions to matching (or non-matching) lines.
 115 For example, to skip lines with a line comment, use the following:
 116
 117     '\,//, ! s/foo/bar/g'
 118
 119 ## Diffs
 120
 121     git diff --shortstat
 122
 123 Displays summary statistics, such as:
 124
 125     2104 files changed, 9309 insertions(+), 9309 deletions(-)