submodule/skia/experimental/documentation/gerrit.md

   1 Using Gerrit without git-cl
   2 ===========================
   3
   4 Setup
   5 -----
   6
   7 The following must be executed within the Skia source repository.
   8
   9 This command sets up a Git commit-message hook to add a unique Change-Id to
  10 each commit.  Gerrit only accepts changes with a Change-Id and uses it to
  11 identify which review a change applies to.
  12
  13     experimental/tools/set-change-id-hook
  14
  15 If you acquired Skia from a mirror (such as GitHub), you need to change the
  16 `origin` remote to point to point to googlesource.  Advanced uses will note
  17 that there is nothing special about the string `origin` and that you could call
  18 this remote anything you want, as long as you use that name for `get push`.
  19
  20     git remote set-url origin 'https://skia.googlesource.com/skia.git'
  21
  22
  23 Authentication
  24 --------------
  25
  26 Go to [skia.googlesource.com/new-password](https://skia.googlesource.com/new-password)
  27 and follow the instructions.
  28
  29
  30 Creating a Change
  31 -----------------
  32
  33 1.  Create a topic branch
  34
  35         git checkout -b TOPIC
  36
  37     You may want to set a tracking branch at this time with:
  38
  39         git checkout -b TOPIC -t origin/main
  40
  41 2.  Make a commit.
  42
  43         echo FOO >> whitespace.txt
  44         git commit --all --message 'Change Foo'
  45         git log -1
  46
  47     `git log` should show that a Change-Id line has been added you your commit
  48     message.
  49
  50
  51 3.  If You have multiple commits in your branch, Gerrit will think you want
  52     multiple changes that depend on each other.  If this is not what you want,
  53     you need to squash the commits.
  54
  55 4.  Push to Gerrit
  56
  57         git push origin @:refs/for/main
  58
  59     `@` is shorthand for `HEAD`, introduced in git v1.8.5.
  60
  61     If you want to target a branch other than `main`, that can be specified
  62     here, too.  For example:
  63
  64         git push origin @:refs/for/chrome/m57
  65
  66     [Gerrit Upload Documentation](https://gerrit-review.googlesource.com/Documentation/user-upload.html)
  67
  68 5.  Open in web browser:
  69
  70         bin/sysopen https://skia-review.googlesource.com/c/skia/+/$(bin/gerrit-number @)
  71
  72 Updating a Change
  73 -----------------
  74
  75
  76 1.  Edit your commits more.
  77
  78         echo BAR >> whitespace.txt
  79         git commit --all --amend
  80
  81     Changes to the commit message will be sent with the push as well.
  82
  83
  84 2.  Re-squash if needed.  (Not needed if you only amended your original commit.)
  85
  86
  87 3.  Push to Gerrit.
  88
  89         git push origin @:refs/for/main
  90
  91     If you want to set a comment message for this patch set, do this instead:
  92
  93         M=$(experimental/tools/gerrit_percent_encode 'This is the patch set comment message!')
  94         git push origin @:refs/for/main%m=$M
  95
  96     The title of this patch set will be "This is the patch set comment message!".
  97
  98
  99 Triggering Commit-Queue Dry Run when you upload a patch
 100 -------------------------------------------------------
 101
 102     M=$(experimental/tools/gerrit_percent_encode 'This is the patch set comment message!')
 103     git push origin @:refs/for/main%l=Commit-Queue+1,m=$M
 104
 105
 106 Using `git cl try`
 107 ------------------
 108
 109 On your current branch, after uploading to gerrit:
 110
 111     git cl issue $(bin/gerrit-number @)
 112
 113 Now `git cl try` and `bin/try` will work correctly.
 114
 115
 116 Scripting
 117 ---------
 118
 119 You may want to make git aliases for common tasks:
 120
 121     git config alias.gerrit-push 'push origin @:refs/for/main'
 122
 123 The following alias amends the head without editing the commit message:
 124
 125     git config alias.amend-head 'commit --all --amend --reuse-message=@'
 126
 127 Set the CL issue numnber:
 128
 129     git config alias.setcl '!git-cl issue $(bin/gerrit-number @)'
 130
 131 The following shell script will squash all commits on the current branch,
 132 assuming that the branch has an upstream topic branch.
 133
 134     squash_git_branch() {
 135         local MESSAGE="$(git log --format=%B ^@{upstream} @)"
 136         git reset --soft $(git merge-base @ @{upstream})
 137         git commit -m "$MESSAGE" -e
 138     }
 139
 140 This shell script pushes to gerrit and adds a message to a patchset:
 141
 142     gerrit_push_with_message() {
 143         local REMOTE='origin'
 144         local REMOTE_BRANCH='main'
 145         local MESSAGE="$(echo $*|sed 's/[^A-Za-z0-9]/_/g')"
 146         git push "$REMOTE" "@:refs/for/${REMOTE_BRANCH}%m=${MESSAGE}"
 147     }
 148
 149 These shell scripts can be turned into Git aliases with a little hack:
 150
 151     git config alias.squash-branch '!M="$(git log --format=%B ^@{u} @)";git reset --soft $(git merge-base @ @{u});git commit -m "$M" -e'
 152
 153     git config alias.gerrit-push-message '!f(){ git push origin @:refs/for/main%m=$(echo $*|sed "s/[^A-Za-z0-9]/_/g");};f'
 154
 155 If your branch's upstream branch (set with `git branch --set-upstream-to=...`)
 156 is set, you can use that to automatically push to that branch:
 157
 158     gerrit_push_upstream() {
 159         local UPSTREAM_FULL="$(git rev-parse --symbolic-full-name @{upstream})"
 160         case "$UPSTREAM_FULL" in
 161             (refs/remotes/*);;
 162             (*) echo "Set your remote upstream branch."; return 2;;
 163         esac
 164         local UPSTREAM="${UPSTREAM_FULL#refs/remotes/}"
 165         local REMOTE="${UPSTREAM%%/*}"
 166         local REMOTE_BRANCH="${UPSTREAM#*/}"
 167         local MESSAGE="$(echo $*|sed 's/[^A-Za-z0-9]/_/g')"
 168         echo git push $REMOTE @:refs/for/${REMOTE_BRANCH}%m=${MESSAGE}
 169         git push "$REMOTE" "@:refs/for/${REMOTE_BRANCH}%m=${MESSAGE}"
 170     }
 171
 172 As a Git alias:
 173
 174     git config alias.gerrit-push '!f()(F="$(git rev-parse --symbolic-full-name @{u})";case "$F" in (refs/remotes/*);;(*)echo "Set your remote upstream branch.";return 2;;esac;U="${F#refs/remotes/}";R="${U%%/*}";B="${U#*/}";M="$(echo $*|sed 's/[^A-Za-z0-9]/_/g')";echo git push $R @:refs/for/${B}%m=$M;git push "$R" "@:refs/for/${B}%m=$M");f'
 175