docs: Split 'git-guide.md`.

This should make our Git documentation more readable and less
intimidating.

CONTRIBUTING.md

@@ -68,7 +68,7 @@ to help.
   [#development help](https://chat.zulip.org/#narrow/stream/development.20help)
   if you run into any troubles.
 * Read the
-  [Zulip guide to Git](https://zulip.readthedocs.io/en/latest/contributing/git-guide.html)
+  [Zulip guide to Git](https://zulip.readthedocs.io/en/latest/git/index.html)
   and do the Git tutorial (coming soon) if you are unfamiliar with Git,
   getting help in
   [#git help](https://chat.zulip.org/#narrow/stream/git.20help) if you run

docs/contributing/code-reviewing.md

@@ -198,5 +198,5 @@ We also strongly recommend reviewers to go through the following resources.
 [commit-messages]: ../contributing/version-control.html#commit-messages
 [test-writing]: ../testing/testing.html
 [mypy]: ../contributing/mypy.html
-[git tool]: ../contributing/git-guide.html#fetch-a-pull-request-and-rebase
+[git tool]: ../git/zulip-tools.html#fetch-a-pull-request-and-rebase
 [translation]: ../translating/translating.html

docs/contributing/index.rst

@@ -5,7 +5,6 @@ Code Contribution Guide
 .. toctree::
    :maxdepth: 3
 
-   git-guide
    version-control
    code-style
    mypy

docs/development/overview.md

@@ -92,4 +92,4 @@ machine, take a look at our tips for
 [configure-proxy]: ../development/setup-vagrant.html#specifying-a-proxy
 [using-dev-env]: using.html
 [testing]: ../testing/testing.html
-[travis-ci]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration
+[travis-ci]: ../git/cloning.html#step-3-configure-travis-ci-continuous-integration

docs/development/remote.md

@@ -87,7 +87,7 @@ don't have a favorite, here are some suggestions:
 * [spacemacs](https://github.com/syl20bnr/spacemacs)
 * [sublime](https://www.sublimetext.com/)
 
-Next, follow our [Git and GitHub Guide](../contributing/git-guide.html) to clone and configure
+Next, follow our [Git and GitHub Guide](../git/index.html) to clone and configure
 your fork of zulip on your local computer.
 
 Once you have cloned your code locally, you can get to work.
@@ -175,7 +175,7 @@ Next, read the following to learn more about developing for Zulip:
 [install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu
 [install-generic]: ../development/setup-advanced.html#installing-manually-on-linux
 [install-vagrant]: ../development/setup-vagrant.html
-[rtd-git-guide]: ../contributing/git-guide.html
+[rtd-git-guide]: ../git/index.html
 [rtd-using-dev-env]: using.html
 [rtd-testing]: ../testing/testing.html
 [git-bash]: https://git-for-windows.github.io/

docs/development/request-remote.md

@@ -65,7 +65,7 @@ Once you've confirmed you can connect to your remote server, take a look at:
 
 * [developing remotely](../development/remote.html) for tips on using the remote dev
   instance, and
-* our [Git & GitHub Guide](../contributing/git-guide.html) to learn how to use Git with Zulip.
+* our [Git & GitHub Guide](../git/index.html) to learn how to use Git with Zulip.
 
 Next, read the following to learn more about developing for Zulip:
 

docs/development/setup-advanced.md

@@ -8,7 +8,7 @@ Contents:
 
 ## Installing directly on Ubuntu
 
-Start by [cloning your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+Start by [cloning your fork of the zulip repository][zulip-rtd-git-cloning]:
 
 `git clone --config pull.rebase https://github.com/YOURUSERNAME/zulip.git`
 
@@ -62,7 +62,7 @@ Install the following non-Python dependencies:
 
 #### Using the official Ubuntu repositories, PGroonga PPA and `tsearch-extras` deb package:
 
-Start by [cloning your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+Start by [cloning your fork of the zulip repository][zulip-rtd-git-cloning]:
 
 `git clone --config pull.rebase https://github.com/YOURUSERNAME/zulip.git`
 
@@ -121,7 +121,7 @@ Now continue with the [All Systems](#all-systems) instructions below.
 
 [zulip-ppa]: https://launchpad.net/~tabbott/+archive/ubuntu/zulip/+packages
 
-Start by [cloning your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+Start by [cloning your fork of the zulip repository][zulip-rtd-git-cloning]:
 
 `git clone --config pull.rebase https://github.com/YOURUSERNAME/zulip.git`
 
@@ -142,7 +142,7 @@ Now continue with the [All Systems](#all-systems) instructions below.
 These instructions are experimental and may have bugs; patches
 welcome!
 
-Start by [cloning your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+Start by [cloning your fork of the zulip repository][zulip-rtd-git-cloning]:
 
 `git clone --config pull.rebase https://github.com/YOURUSERNAME/zulip.git`
 
@@ -160,7 +160,7 @@ Now continue with the [Common to Fedora/CentOS](#common-to-fedora-centos-instruc
 These instructions are experimental and may have bugs; patches
 welcome!
 
-Start by [cloning your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+Start by [cloning your fork of the zulip repository][zulip-rtd-git-cloning]:
 
 `git clone --config pull.rebase https://github.com/YOURUSERNAME/zulip.git`
 
@@ -219,7 +219,7 @@ Now continue with the [Common to Fedora/CentOS](#common-to-fedora-centos-instruc
 These instructions are experimental and may have bugs; patches
 welcome!
 
-Start by [cloning your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+Start by [cloning your fork of the zulip repository][zulip-rtd-git-cloning]:
 
 `git clone --config pull.rebase https://github.com/YOURUSERNAME/zulip.git`
 
@@ -254,7 +254,7 @@ Finally continue with the [All Systems](#all-systems) instructions below.
 
 ### Common to Fedora/CentOS instructions
 
-Start by [cloning your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+Start by [cloning your fork of the zulip repository][zulip-rtd-git-cloning]:
 
 `git clone --config pull.rebase https://github.com/YOURUSERNAME/zulip.git`
 
@@ -375,7 +375,7 @@ proxy in the environment as follows:
 
 ## Using Docker (experimental)
 
-Start by [cloning your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+Start by [cloning your fork of the zulip repository][zulip-rtd-git-cloning]:
 
 `git clone --config pull.rebase https://github.com/YOURUSERNAME/zulip.git`
 
@@ -472,3 +472,5 @@ the results in your browser.
 Currently, the Docker workflow is substantially less convenient than
 the Vagrant workflow and less documented; please contribute to this
 guide and the Docker tooling if you are using Docker to develop Zulip!
+
+[zulip-rtd-git-cloning]: ../git/cloning.html#step-1b-clone-to-your-machine

docs/development/setup-vagrant.md

@@ -279,7 +279,7 @@ Now you are ready for [Step 2: Get Zulip Code.](#step-2-get-zulip-code)
 2. Open Terminal (macOS/Ubuntu) or Git BASH (Windows; must
    **run as an Administrator**).
 3. In Terminal/Git BASH,
-   [clone your fork of the zulip repository](../contributing/git-guide.html#step-1b-clone-to-your-machine):
+   [clone your fork of the zulip repository](../git/cloning.html#step-1b-clone-to-your-machine):
 
 ```
 git clone --config pull.rebase git@github.com:YOURUSERNAME/zulip.git
@@ -1060,11 +1060,11 @@ for the IP address that means any IP address can connect to your development ser
 [avoiding-sudo]: https://github.com/fgrehm/vagrant-lxc#avoiding-sudo-passwords
 [install-advanced]: ../development/setup-advanced.html
 [lxc-sf]: https://github.com/fgrehm/vagrant-lxc/wiki/FAQ#help-my-shared-folders-have-the-wrong-owner
-[rtd-git-guide]: ../contributing/git-guide.html
+[rtd-git-guide]: ../git/index.html
 [rtd-testing]: ../testing/testing.html
 [rtd-using-dev-env]: using.html
 [rtd-dev-remote]: remote.html
 [git-bash]: https://git-for-windows.github.io/
 [bash-admin-setup]: https://superuser.com/questions/1002262/run-applications-as-administrator-by-default-in-windows-10
-[set-up-git]: ../contributing/git-guide.html#set-up-git
+[set-up-git]: ../git/setup.html
-[travis-ci]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration
+[travis-ci]: ../git/cloning.html#step-3-configure-travis-ci-continuous-integration

docs/git/cloning.md

@@ -0,0 +1,135 @@
+# Get Zulip code
+
+Zulip uses a **forked-repo** and **[rebase][gitbook-rebase]-oriented
+workflow.**. This means that all contributors create a fork of the [Zulip
+repository][github-zulip] they want to contribute to and then submit pull
+requests to the upstream repository to have their contributions reviewed and
+accepted. We also recommend you work on feature branches.
+
+## Step 1a: Create your fork
+
+The following steps you'll only need to do the first time you setup a machine
+for contributing to a given Zulip project. You'll need to repeat the steps for
+any additional Zulip projects ([list][github-zulip]) that you work on.
+
+The first thing you'll want to do to contribute to Zulip is fork ([see
+how][github-help-fork]) the appropriate [Zulip repository][github-zulip]. For
+the main server app, this is [zulip/zulip][github-zulip-zulip].
+
+## Step 1b: Clone to your machine
+
+Next, clone your fork to your local machine:
+
+```
+$ git clone --config pull.rebase git@github.com:christi3k/zulip.git
+Cloning into 'zulip'
+remote: Counting objects: 86768, done.
+remote: Compressing objects: 100% (15/15), done.
+remote: Total 86768 (delta 5), reused 1 (delta 1), pack-reused 86752
+Receiving objects: 100% (86768/86768), 112.96 MiB | 523.00 KiB/s, done.
+Resolving deltas: 100% (61106/61106), done.
+Checking connectivity... done.
+```
+
+(The `--config pull.rebase` option configures Git so that `git pull`
+will behave like `git pull --rebase` by default.  Using `git pull
+--rebase` to update your changes to resolve merge conflicts is
+expected by essentially all of open source projects, including Zulip.
+You can also set that option after cloning using `git config --add
+pull.rebase true`, or just be careful to always run `git pull
+--rebase`, never `git pull`).
+
+Note: If you receive an error while cloning, you may not have [added your ssh
+key to GitHub][github-help-add-ssh-key].
+
+## Step 1c: Connect your fork to Zulip upstream
+
+Next you'll want to [configure an upstream remote
+repository][github-help-conf-remote] for your fork of Zulip. This will allow
+you to [sync changes][github-help-sync-fork] from the main project back into
+your fork.
+
+First, show the currently configured remote repository:
+
+```
+$ git remote -v
+origin  git@github.com:YOUR_USERNAME/zulip.git (fetch)
+origin  git@github.com:YOUR_USERNAME/zulip.git (push)
+```
+
+Note: If you've cloned the repository using a graphical client, you may already
+have the upstream remote repository configured. For example, when you clone
+[zulip/zulip][github-zulip-zulip] with the GitHub desktop client it configures
+the remote repository `zulip` and you see the following output from `git remote
+-v`:
+
+```
+origin  git@github.com:YOUR_USERNAME/zulip.git (fetch)
+origin  git@github.com:YOUR_USERNAME/zulip.git (push)
+zulip    https://github.com/zulip/zulip.git (fetch)
+zulip    https://github.com/zulip/zulip.git (push)
+```
+
+If your client hasn't automatically configured a remote for zulip/zulip, you'll
+need to with:
+
+```
+$ git remote add upstream https://github.com/zulip/zulip.git
+```
+
+Finally, confirm that the new remote repository, upstream, has been configured:
+
+```
+$ git remote -v
+origin  git@github.com:YOUR_USERNAME/zulip.git (fetch)
+origin  git@github.com:YOUR_USERNAME/zulip.git (push)
+upstream https://github.com/zulip/zulip.git (fetch)
+upstream https://github.com/zulip/zulip.git (push)
+```
+
+## Step 2: Set up the Zulip development environment
+
+If you haven't already, now is a good time to install the Zulip development environment
+([overview][zulip-rtd-dev-overview]). If you're new to working on Zulip or open
+source projects in general, we recommend following our [detailed guide for
+first-time contributors][zulip-rtd-dev-first-time].
+
+## Step 3: Configure Travis CI (continuous integration)
+
+This step is optional, but recommended.
+
+The Zulip Server project is configured to use [Travis CI][travis-ci]
+to test and create builds upon each new commit and pull
+request. Travis CI is free for open source projects and it's easy to
+configure for your own fork of Zulip. After doing so, Travis CI will
+run tests for new refs you push to GitHub and email you the outcome
+(you can also view the results in the web interface).
+
+Running Travis CI against your fork can help save both you and the
+Zulip maintainers time by making it easy to test a change fully before
+submitting a pull request.  We generally recommend a worfklow where as
+you make changes, you use a fast edit-refresh cycle running individual
+tests locally until your changes work.  But then once you've gotten
+the tests you'd expect to be relevant to your changes working, push a
+branch to Travis CI to run the full test suite before you create a
+pull request.  While you wait for Travis CI to run, you can start
+working on your next task.  When the tests finish, you can create a
+pull request that you already know passes the tests.
+
+First, sign in to [Travis CI][travis-ci] with your GitHub account and authorize
+Travis CI to access your GitHub account and repositories. Once you've done
+this, Travis CI will fetch your repository information and display it on your
+[profile page][travis-ci-profile]. From there you can enable integration with
+Zulip. ([See screen cast](../_static/zulip-travisci.gif).)
+
+[gitbook-rebase]: https://git-scm.com/book/en/v2/Git-Branching-Rebasing
+[github-help-add-ssh-key]: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
+[github-help-conf-remote]: https://help.github.com/articles/configuring-a-remote-for-a-fork/
+[github-help-fork]: https://help.github.com/articles/fork-a-repo/
+[github-help-sync-fork]: https://help.github.com/articles/syncing-a-fork/
+[github-zulip]: https://github.com/zulip/
+[github-zulip-zulip]: https://github.com/zulip/zulip/
+[travis-ci]: https://travis-ci.org/
+[travis-ci-profile]: https://travis-ci.org/profile
+[zulip-rtd-dev-first-time]: ../development/setup-vagrant.html
+[zulip-rtd-dev-overview]: ../development/overview.html

docs/git/collaborate.md

@@ -0,0 +1,57 @@
+# Collaborate
+
+## Fetch another contributor's branch
+
+What happens when you would like to collaborate with another contributor and
+they have work-in-progress on their own fork of Zulip? No problem! Just add
+their fork as a remote and pull their changes.
+
+```
+$ git remote add <username> https://github.com/<username>/zulip.git
+$ git fetch <username>
+```
+
+Now you can checkout their branch just like you would any other. You can name
+the branch anything you want, but using both the username and branch name will
+help you keep things organized.
+
+```
+$ git checkout -b <username>/<branchname>
+```
+
+You can choose to rename the branch if you prefer:
+```
+git checkout -b <custombranchname> <username>/<branchname>
+```
+
+## Checkout a pull request locally
+
+Just as you can checkout any user's branch locally, you can also checkout any
+pull request locally. GitHub provides a special syntax
+([details][github-help-co-pr-locally]) for this since pull requests are
+specific to GitHub rather than Git.
+
+First, fetch and create a branch for the pull request, replacing *ID* and
+*BRANCHNAME* with the ID of the pull request and your desired branch name:
+
+```
+$ git fetch upstream pull/ID/head:BRANCHNAME
+```
+
+Now switch to the branch:
+
+```
+$ git checkout BRANCHNAME
+```
+
+Now you work on this branch as you would any other.
+
+Note: you can use the scripts provided in the tools/ directory to fetch pull
+requests. You can read more about what they do [here][tools-PR].
+```
+tools/fetch-rebase-pull-request <PR-number>
+tools/fetch-pull-request <PR-number>
+```
+
+[github-help-co-pr-locally]: https://help.github.com/articles/checking-out-pull-requests-locally/
+[tools-PR]: ../git/zulip-tools.html#fetch-a-pull-request-and-rebase

docs/git/index.rst

@@ -0,0 +1,18 @@
+#########
+Git Guide
+#########
+
+.. toctree::
+   :maxdepth: 3
+
+   Quick Start <overview>
+   Set up Git <setup>
+   How Git is different <the-git-difference>
+   Important Git terms <terminology>
+   Get Zulip code <cloning>
+   Using Git as you work <using>
+   Pull Requests <pull-requests>
+   Collaborate <collaborate>
+   Reviewing changes <reviewing>
+   Get and stay out of trouble <troubleshooting>
+   Zulip-specific-tools <zulip-tools>

docs/git/overview.md

@@ -0,0 +1,67 @@
+# Quick start: How Zulip uses Git and GitHub
+
+This quick start provides a brief overview of how Zulip uses Git and GitHub.
+
+Those who are familiar with Git and GitHub should be able to start contributing
+with these details in mind:
+
+- We use **GitHub for source control and code review.** To contribute, fork
+  [zulip/zulip][github-zulip-zulip] (or the appropriate
+  [repository][github-zulip], if you are working on something else besides
+  Zulip server) to your own account and then create feature/issue branches.
+  When you're ready to get feedback, submit a work-in-progress (WIP) pull
+  request. *We encourage you to submit WIP pull requests early and often.*
+
+- We use a **[rebase][gitbook-rebase]-oriented workflow.** We do not use merge
+  commits. This means you should use `git fetch` followed by `git rebase`
+  rather than `git pull` (or you can use `git pull --rebase`). Also, to prevent
+  pull requests from becoming out of date with the main line of development,
+  you should rebase your feature branch prior to submitting a pull request, and
+  as needed thereafter. If you're unfamiliar with how to rebase a pull request,
+  [read this excellent guide][github-rebase-pr].
+
+  We use this strategy in order to avoid the extra commits that appear
+  when another branch is merged, that clutter the commit history (it's
+  popular with other large projects such as Django).  This makes
+  Zulip's commit history more readable, but a side effect is that many
+  pull requests we merge will be reported by GitHub's UI as *closed*
+  instead of *merged*, since GitHub has poor support for
+  rebase-oriented workflows.
+
+- We have a **[code style guide][zulip-rtd-code-style]**, a **[commit message
+  guide][zulip-rtd-commit-messages]**, and strive for each commit to be *a
+  minimal coherent idea* (see **[commit
+  discipline][zulip-rtd-commit-discipline]** for details).
+
+- We provide **many tools to help you submit quality code.** These include
+  [linters][zulip-rtd-lint-tools], [tests][zulip-rtd-testing], continuous
+  integration with [Travis CI][travis-ci], and [mypy][zulip-rtd-mypy].
+
+- We use [zulipbot][zulip-rtd-zulipbot-usage] to manage our issues and
+pull requests to create a better GitHub workflow for contributors.
+
+Finally, take a quick look at [Zulip-specific Git scripts][zulip-rtd-zulip-tools],
+install the [Zulip developer environment][zulip-rtd-dev-overview], and then
+[configure your fork for use with Travis CI][zulip-git-guide-travisci].
+
+***
+
+The following sections will help you be awesome with Zulip and Git/GitHub in a
+rebased-based workflow. Read through it if you're new to git, to a rebase-based
+git workflow, or if you'd like a git refresher.
+
+[gitbook-rebase]: https://git-scm.com/book/en/v2/Git-Branching-Rebasing
+[github-rebase-pr]: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
+[github-zulip]: https://github.com/zulip/
+[github-zulip-zulip]: https://github.com/zulip/zulip/
+[travis-ci]: https://travis-ci.org/
+[zulip-git-guide-travisci]: ../git/cloning.html#step-3-configure-travis-ci-continuous-integration
+[zulip-rtd-code-style]: ../contributing/code-style.html
+[zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline
+[zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages
+[zulip-rtd-dev-overview]: ../development/overview.html
+[zulip-rtd-lint-tools]: ../contributing/code-style.html#lint-tools
+[zulip-rtd-mypy]: ../contributing/mypy.html
+[zulip-rtd-testing]: ../testing/testing.html
+[zulip-rtd-zulip-tools]: ../git/zulip-tools.html
+[zulip-rtd-zulipbot-usage]: ../contributing/zulipbot-usage.html

docs/git/pull-requests.md

@@ -0,0 +1,150 @@
+# Create a pull request
+
+When you're ready for feedback, submit a pull request. Pull requests
+are a feature specific to GitHub. They provide a simple, web-based way
+to submit your work (often called "patches") to a project. It's called
+a *pull request* because you're asking the project to *pull changes*
+from your fork.
+
+If you're unfamiliar with how to create a pull request, you can check
+out GitHub's documentation on
+[creating a pull request from a fork][github-help-create-pr-fork]. You
+might also find GitHub's article
+[about pull requests][github-help-about-pr] helpful. That all said,
+the tutorial below will walk you through the process.
+
+## Work in progress pull requests
+
+In the Zulip project, we encourage submitting work-in-progress pull
+requests early and often. This allows you to share your code to make
+it easier to get feedback and help with your changes. Prefix the
+titles of work-in-progress pull requests with **[WIP]**, which in our
+project means that you don't think your pull request is ready to be
+merged (e.g. it might not work or pass tests).  This sets expectations
+correctly for any feedback from other developers, and prevents your
+work from being merged before you're confident in it.
+
+## Step 1: Update your branch with git rebase
+
+The best way to update your branch is with `git fetch` and `git rebase`. Do not
+use `git pull` or `git merge` as this will create merge commits. See [keep your
+fork up to date][keep-up-to-date] for details.
+
+Here's an example (you would replace *issue-123* with the name of your feature branch):
+
+```
+$ git checkout issue-123
+Switched to branch 'issue-123'
+
+$ git fetch upstream
+remote: Counting objects: 69, done.
+remote: Compressing objects: 100% (23/23), done.
+remote: Total 69 (delta 49), reused 39 (delta 39), pack-reused 7
+Unpacking objects: 100% (69/69), done.
+From https://github.com/zulip/zulip
+   69fa600..43e21f6  master     -> upstream/master
+
+$ git rebase upstream/master
+
+First, rewinding head to replay your work on top of it...
+Applying: troubleshooting tip about provisioning
+```
+
+## Step 2: Push your updated branch to your remote fork
+
+Once you've updated your local feature branch, push the changes to GitHub:
+
+```
+$ git push origin issue-123
+Counting objects: 6, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (4/4), done.
+Writing objects: 100% (6/6), 658 bytes | 0 bytes/s, done.
+Total 6 (delta 3), reused 0 (delta 0)
+remote: Resolving deltas: 100% (3/3), completed with 1 local objects.
+To git@github.com:christi3k/zulip.git
+ + 2d49e2d...bfb2433 issue-123 -> issue-123
+```
+
+If your push is rejected with error **failed to push some refs** then you need
+to prefix the name of your branch with a `+`:
+
+```
+$ git push origin +issue-123
+Counting objects: 6, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (4/4), done.
+Writing objects: 100% (6/6), 658 bytes | 0 bytes/s, done.
+Total 6 (delta 3), reused 0 (delta 0)
+remote: Resolving deltas: 100% (3/3), completed with 1 local objects.
+To git@github.com:christi3k/zulip.git
+ + 2d49e2d...bfb2433 issue-123 -> issue-123 (forced update)
+```
+
+This is perfectly okay to do on your own feature branches, especially if you're
+the only one making changes to the branch. If others are working along with
+you, they might run into complications when they retrieve your changes because
+anyone who has based their changes off a branch you rebase will have to do a
+complicated rebase.
+
+## Step 3: Open the pull request
+
+If you've never created a pull request or need a refresher, take a look at
+GitHub's article [creating a pull request from a
+fork][github-help-create-pr-fork]. We'll briefly review the process here.
+
+The first step in creating a pull request is to use your web browser to
+navigate to your fork of Zulip. Sign in to GitHub if you haven't already.
+
+Next, navigate to the branch you've been working on. Do this by clicking on the
+**Branch** button and selecting the relevant branch. Finally, click the **New
+pull request** button.
+
+Alternatively, if you've recently pushed to your fork, you will see a green
+**Compare & pull request** button.
+
+You'll see the *Open a pull request* page:
+
+![images-create-pr]
+
+Provide a **title** and first comment for your pull request. Remember to prefix
+your pull request title with [WIP] if it is a [work-in-progress][wip-prs].
+
+If your pull request has an effect on the visuals of a component, you might want
+to include a screenshot of this change or a GIF of the interaction in your first
+comment. This will allow reviewers to comment on your changes without having to
+checkout your branch; you can find a list of tools you can use for this over
+[here][screenshots-gifs].
+
+When ready, click the green **Create pull request** to submit the pull request.
+
+Note: **Pull request titles are different from commit messages.** Commit
+messages can be edited with `git commit --amend`, `git rebase -i`, etc., while
+the title of a pull request can only be edited via GitHub.
+
+# Update a pull request
+
+As you get make progress on your feature or bugfix, your pull request, once
+submitted, will be updated each time you [push commits][self-push-commits] to
+your remote branch. This means you can keep your pull request open as long as
+you need, rather than closing and opening new ones for the same feature or
+bugfix.
+
+It's a good idea to keep your pull request mergeable with Zulip upstream by
+frequently fetching, rebasing, and pushing changes. See [keep your fork up to
+date][keep-up-to-date] for details. You might also find this excellent
+article [How to Rebase a Pull Request][edx-howto-rebase-pr] helpful.
+
+And, as you address review comments others have made, we recommend posting a
+follow-up comment in which you: a) ask for any clarifications you need, b)
+explain to the reviewer how you solved any problems they mentioned, and c) ask
+for another review.
+
+[edx-howto-rebase-pr]: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
+[github-help-about-pr]: https://help.github.com/articles/about-pull-requests/
+[github-help-create-pr-fork]: https://help.github.com/articles/creating-a-pull-request-from-a-fork/
+[images-create-pr]: ../images/zulip-open-pr.png
+[keep-up-to-date]: ../git/using.html#keep-your-fork-up-to-date
+[push-commits]: ../git/using.html#push-your-commits-to-github
+[screenshots-gifs]: ../tutorials/screenshot-and-gif-software.html
+[wip-prs]: #work-in-progress-pull-requests

docs/git/reviewing.md

@@ -0,0 +1,58 @@
+# Review changes
+
+## Changes on (local) working tree
+
+Display changes between index and working tree (what is not yet staged for commit):
+
+```
+$ git diff
+```
+
+Display changes between index and last commit (what you have staged for commit):
+
+```
+$ git diff --cached
+```
+
+Display changes in working tree since last commit (changes that are staged as
+well as ones that are not):
+
+```
+$ git diff HEAD
+```
+
+## Changes within branches
+
+Use any git-ref to compare changes between two commits on the current branch.
+
+Display changes between commit before last and last commit:
+
+```
+$ git diff HEAD^ HEAD
+```
+
+Display changes between two commits using their hashes:
+
+```
+$ git diff e2f404c 7977169
+```
+
+## Changes between branches
+
+Display changes between tip of topic branch and tip of master branch:
+
+```
+$ git diff topic master
+```
+
+Display changes that have occurred on master branch since topic branch was created:
+
+```
+$ git diff topic...master
+```
+
+Display changes you've committed so far since creating a branch from upstream/master:
+
+```
+$ git diff upstream/master...HEAD
+```

docs/git/setup.md

@@ -0,0 +1,67 @@
+# Set up Git
+
+If you're already using Git, have a client you like, and a GitHub account, you
+can skip this section. Otherwise, read on!
+
+## Install and configure Git, join GitHub
+
+If you're not already using Git, you might need to [install][gitbook-install]
+and [configure][gitbook-setup] it.
+
+**If you are using Windows 10, make sure you [are running Git BASH as an
+administrator][git-bash-admin] at all times.**
+
+You'll also need a GitHub account, which you can sign up for
+[here][github-join].
+
+We highly recommend you create an ssh key if you don't already have
+one and [add it to your GitHub account][github-help-add-ssh-key].  If
+you don't, you'll have to type your GitHub username and password every
+time you interact with GitHub, which is usually several times a day.
+
+We also highly recommend the following:
+
+- [Configure Git][gitbook-config] with your name and email and
+  [aliases][gitbook-aliases] for commands you'll use often.  We
+  recommend using your full name (not just your first name), since
+  that's what we'll use to give credit to your work in places like the
+  Zulip release notes.
+- Install the command auto-completion and/or git-prompt plugins available for
+  [Bash][gitbook-other-envs-bash] and [Zsh][gitbook-other-envs-zsh].
+
+## Get a graphical client
+
+Even if you're comfortable using git on the command line, having a graphic
+client can be useful for viewing your repository. This is especially when doing
+a complicated rebases and similar operations because you can check the state of
+your repository after each command to see what changed. If something goes
+wrong, this helps you figure out when and why.
+
+If you don't already have one installed, here are some suggestions:
+
+- macOS: [GitX-dev][gitgui-gitxdev]
+- Ubuntu/Linux: [git-cola][gitgui-gitcola], [gitg][gitgui-gitg], [gitk][gitgui-gitk]
+- Windows: [SourceTree][gitgui-sourcetree]
+
+If you like working on the command line, but want better visualization and
+navigation of your git repo, try [Tig][tig], a cross-platform ncurses-based
+text-mode interface to Git.
+
+And, if none of the above are to your liking, try [one of these][gitbook-guis].
+
+[git-bash-admin]: ../development/setup-vagrant.html#running-git-bash-as-an-administrator
+[gitbook-aliases]: https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases
+[gitbook-config]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration
+[gitbook-guis]: https://git-scm.com/downloads/guis
+[gitbook-install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[github-join]: https://github.com/join
+[gitbook-setup]: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup
+[gitbook-other-envs-bash]: https://git-scm.com/book/en/v2/Git-in-Other-Environments-Git-in-Bash
+[gitbook-other-envs-zsh]: https://git-scm.com/book/en/v2/Git-in-Other-Environments-Git-in-Zsh
+[gitgui-gitcola]: http://git-cola.github.io/
+[gitgui-gitg]: https://wiki.gnome.org/Apps/Gitg
+[gitgui-gitk]: https://git-scm.com/docs/gitk
+[gitgui-gitxdev]: https://rowanj.github.io/gitx/
+[gitgui-sourcetree]: https://www.sourcetreeapp.com/
+[github-help-add-ssh-key]: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
+[tig]: http://jonas.nitro.dk/tig/

docs/git/terminology.md

@@ -0,0 +1,84 @@
+# Important Git terms
+
+When you install Git, it adds a manual entry for `gitglossary`. You can view
+this glossary by running `man gitglossary`. Below we've included the git terms
+you'll encounter most often along with their definitions from *gitglossary*.
+
+## branch
+A "branch" is an active line of development. The most recent commit
+on a branch is referred to as the tip of that branch. The tip of
+the branch is referenced by a branch head, which moves forward as
+additional development is done on the branch. A single Git
+repository can track an arbitrary number of branches, but your
+working tree is associated with just one of them (the "current" or
+"checked out" branch), and HEAD points to that branch.
+
+## cache
+Obsolete for: index
+
+## checkout
+The action of updating all or part of the working tree with a tree
+object or blob from the object database, and updating the index and
+HEAD if the whole working tree has been pointed at a new branch.
+
+## commit
+As a noun: A single point in the Git history; the entire history of
+a project is represented as a set of interrelated commits. The word
+"commit" is often used by Git in the same places other revision
+control systems use the words "revision" or "version". Also used as
+a short hand for commit object.
+
+As a verb: The action of storing a new snapshot of the project's
+state in the Git history, by creating a new commit representing the
+current state of the index and advancing HEAD to point at the new
+
+## fast-forward
+A fast-forward is a special type of merge where you have a revision
+and you are "merging" another branch's changes that happen to be a
+descendant of what you have. In such these cases, you do not make a
+new mergecommit but instead just update to their revision. This will
+happen frequently on a remote-tracking branch of a remote
+repository.
+
+## fetch
+Fetching a branch means to get the branch's head ref from a remote
+repository, to find out which objects are missing from the local
+object database, and to get them, too. See also git-fetch(1).
+
+## hash
+In Git's context, synonym for object name.
+
+## head
+A named reference to the commit at the tip of a branch. Heads are
+stored in a file in $GIT_DIR/refs/heads/ directory, except when
+using packed refs. (See git-pack-refs(1).)
+
+## HEAD
+The current branch. In more detail: Your working tree is normally
+derived from the state of the tree referred to by HEAD. HEAD is a
+reference to one of the heads in your repository, except when using
+a detached HEAD, in which case it directly references an arbitrary
+commit.
+
+## index
+A collection of files with stat information, whose contents are
+stored as objects. The index is a stored version of your working
+tree. Truth be told, it can also contain a second, and even a third
+version of a working tree, which are used when merging.
+
+## pull
+Pulling a branch means to fetch it and merge it. See also git-
+pull(1).
+
+## push
+Pushing a branch means to get the branch's head ref from a remote
+repository, find out if it is a direct ancestor to the branch's
+local head ref, and in that case, putting all objects, which are
+reachable from the local head ref, and which are missing from the
+remote repository, into the remote object database, and updating
+the remote head ref. If the remote head is not an ancestor to the
+local head, the push fails.
+
+## rebase
+To reapply a series of changes from a branch to a different base,
+and reset the head of that branch to the result.

docs/git/the-git-difference.md

@@ -0,0 +1,64 @@
+# How Git is different
+
+Whether you're new to Git or have experience with another version control
+system (VCS), it's a good idea to learn a bit about how Git works. We recommend
+this excellent presentation *[Understanding Git][understanding-git]* from
+Nelson Elhage and Anders Kaseorg and the [Git Basics][gitbook-basics] chapter
+from *Pro Git* by Scott Chacon and Ben Straub.
+
+Here are the top things to know:
+
+- **Git works on snapshots:** Unlike other version control systems (e.g.,
+  Subversion, Perforce, Bazaar), which track files and changes to those files
+  made over time, Git tracks *snapshots* of your project. Each time you commit
+  or otherwise make a change to your repository, Git takes a snapshot of your
+  project and stores a reference to that snapshot. If a file hasn't changed,
+  Git creates a link to the identical file rather than storing it again.
+
+- **Most Git operations are local:** Git is a distributed version control
+  system, so once you've cloned a repository, you have a complete copy of that
+  repository's *entire history*. Staging, committing, branching, and browsing
+  history are all things you can do locally without network access and without
+  immediately affecting any remote repositories. To make or receive changes
+  from remote repositories, you need to `git fetch`, `git pull`, or `git push`.
+
+- **Nearly all Git actions add information to the Git database**, rather than
+  removing it. As such, it's hard to make Git perform actions that you can't
+  undo. However, Git can't undo what it doesn't know about, so it's a good
+  practice to frequently commit your changes and frequently push your commits to
+  your remote repository.
+
+- **Git is designed for lightweight branching and merging.** Branches are
+  simply references to snapshots. It's okay and expected to make a lot of
+  branches, even throwaway and experimental ones.
+
+- **Git stores all data as objects, of which there are four types:** blob
+  (file), tree (directory), commit (revision), and tag. Each of these objects
+  is named by a unique hash, the SHA-1 has of its contents. Most of the time
+  you'll refer to objects by their truncated hash or more human-readable
+  reference like `HEAD` (the current branch). Blobs and trees represent files
+  and directories. Tags are named references to other objects. A commit object
+  includes: tree id, zero or more parents as commit ids, an author (name,
+  email, date), a committer (name, email, date), and a log message. A Git
+  repository is a collection of mutable pointers to these objects called
+  **refs**.
+
+- **Cloning a repository creates a working copy.** Every working copy has a
+  `.git` subdirectory, which contains its own Git repository. The `.git`
+  subdirectory also tracks the *index*, a staging area for changes that will
+  become part of the next commit. All files outside of `.git` is the *working
+  tree*.
+
+- **Files tracked with Git have possible three states: committed, modified, and
+  staged.** Committed files are those safely stored in your local `.git`
+  repository/database. Staged files have changes and have been marked for
+  inclusion in the next commit; they are part of the index. Modified files have
+  changes but have not yet been marked for inclusion in the next commit; they
+  have not been added to the index.
+
+- **Git commit workflow is as follows:** Edit files in your *working tree*. Add
+  to the *index* (that is *stage*) with `git add`. *Commit* to the HEAD of the
+  current branch with `git commit`.
+
+[gitbook-basics]: https://git-scm.com/book/en/v2/Getting-Started-Git-Basics
+[understanding-git]: http://web.mit.edu/nelhage/Public/git-slides-2009.pdf

docs/git/troubleshooting.md

@@ -0,0 +1,280 @@
+# Get and stay out of trouble
+
+Git is a powerful yet complex version control system. Even for contributors
+experienced at using version control, it can be confusing. The good news is
+that nearly all Git actions add information to the Git database, rather than
+removing it. As such, it's hard to make Git perform actions that you can't
+undo. However, git can't undo what it doesn't know about, so it's a good
+practice to frequently commit your changes and frequently push your commits to
+your remote repository.
+
+## Undo a merge commit
+
+A merge commit is a special type of commit that has two parent commits. It's
+created by Git when you merge one branch into another and the last commit on
+your current branch is not a direct ancestor of the branch you are trying to
+merge in. This happens quite often in a busy project like Zulip where there are
+many contributors because upstream/zulip will have new commits while you're
+working on a feature or bugfix. In order for Git to merge your changes and the
+changes that have occurred on zulip/upstream since you first started your work,
+it must perform a three-way merge and create a merge commit.
+
+Merge commits aren't bad, however, Zulip doesn't use them. Instead Zulip uses a
+forked-repo, rebase-oriented workflow.
+
+A merge commit is usually created when you've run `git pull` or `git merge`.
+You'll know you're creating a merge commit if you're prompted for a commit
+message and the default is something like this:
+
+```
+Merge branch 'master' of https://github.com/zulip/zulip
+
+# Please enter a commit message to explain why this merge is necessary,
+# especially if it merges an updated upstream into a topic branch.
+#
+# Lines starting with '#' will be ignored, and an empty message aborts
+# the commit.
+```
+
+And the first entry for `git log` will show something like:
+
+```
+commit e5f8211a565a5a5448b93e98ed56415255546f94
+Merge: 13bea0e e0c10ed
+Author: Christie Koehler <ck@christi3k.net>
+Date:   Mon Oct 10 13:25:51 2016 -0700
+
+    Merge branch 'master' of https://github.com/zulip/zulip
+```
+
+Some graphical Git clients may also create merge commits.
+
+To undo a merge commit, first run `git reflog` to identify the commit you want
+to roll back to:
+
+```
+$ git reflog
+
+e5f8211 HEAD@{0}: pull upstream master: Merge made by the 'recursive' strategy.
+13bea0e HEAD@{1}: commit: test commit for docs.
+```
+
+Reflog output will be long. The most recent git refs will be listed at the top.
+In the example above `e5f8211 HEAD@{0}:` is the merge commit made automatically
+by `git pull` and `13bea0e HEAD@{1}:` is the last commit I made before running
+`git pull`, the commit that I want to rollback to.
+
+Once you'd identified the ref you want to revert to, you can do so with [git
+reset][gitbook-reset]:
+
+```
+$ git reset --hard 13bea0e
+HEAD is now at 13bea0e test commit for docs.
+```
+
+**Important:** `git reset --hard <commit>` will discard all changes in your
+working directory and index since the commit you're resetting to with
+*<commit>*. *This is the main way you can lose work in Git*. If you need to
+keep any changes that are in your working directory or that you have committed,
+use `git reset --merge <commit>` instead.
+
+You can also use the relative reflog `HEAD@{1}` instead of the commit hash,
+just keep in mind that this changes as you run git commands.
+
+Now when you look at the output of `git reflog`, you should see that the tip of your branch points to your
+last commit `13bea0e` before the merge:
+
+```
+$ git reflog
+
+13bea0e HEAD@{2}: reset: moving to HEAD@{1}
+e5f8211 HEAD@{3}: pull upstream master: Merge made by the 'recursive' strategy.
+13bea0e HEAD@{4}: commit: test commit for docs.
+```
+
+And the first entry `git log` shows is this:
+
+```
+commit 13bea0e40197b1670e927a9eb05aaf50df9e8277
+Author: Christie Koehler <ck@christi3k.net>
+Date:   Mon Oct 10 13:25:38 2016 -0700
+
+    test commit for docs.
+```
+
+## Restore a lost commit
+
+We've mentioned you can use `git reset --hard` to rollback to a previous
+commit. What if you run `git reset --hard` and then realize you actually need
+one or more of the commits you just discarded? No problem, you can restore them
+with `git cherry-pick` ([docs][gitbook-git-cherry-pick]).
+
+For example, let's say you just committed "some work" and your `git log` looks
+like this:
+
+```
+* 67aea58 (HEAD -> master) some work
+* 13bea0e test commit for docs.
+```
+
+You then mistakenly run `git reset --hard 13bea0e`:
+
+```
+$ git reset --hard 13bea0e
+HEAD is now at 13bea0e test commit for docs.
+
+$ git log
+* 13bea0e (HEAD -> master) test commit for docs.
+```
+
+And then realize you actually needed to keep commit 67aea58. First, use `git
+reflog` to confirm that commit you want to restore and then run `git
+cherry-pick <commit>`:
+
+```
+$ git reflog
+13bea0e HEAD@{0}: reset: moving to 13bea0e
+67aea58 HEAD@{1}: commit: some work
+
+$ git cherry-pick 67aea58
+ [master 67aea58] some work
+ Date: Thu Oct 13 11:51:19 2016 -0700
+ 1 file changed, 1 insertion(+)
+ create mode 100644 test4.txt
+```
+
+## Recover from a git rebase failure
+
+One situation in which `git rebase` will fail and require you to intervene is
+when your change, which git will try to re-apply on top of new commits from
+which ever branch you are rebasing on top of, is to code that has been changed
+by those new commits.
+
+For example, while I'm working on a file, another contributor makes a change to
+that file, submits a pull request and has their code merged into master.
+Usually this is not a problem, but in this case the other contributor made a
+change to a part of the file I also want to change. When I try to bring my
+branch up to date with `git fetch` and then `git rebase upstream/master`, I see
+the following:
+
+```
+First, rewinding head to replay your work on top of it...
+Applying: test change for docs
+Using index info to reconstruct a base tree...
+M    README.md
+Falling back to patching base and 3-way merge...
+Auto-merging README.md
+CONFLICT (content): Merge conflict in README.md
+error: Failed to merge in the changes.
+Patch failed at 0001 test change for docs
+The copy of the patch that failed is found in: .git/rebase-apply/patch
+
+When you have resolved this problem, run "git rebase --continue".
+If you prefer to skip this patch, run "git rebase --skip" instead.
+To check out the original branch and stop rebasing, run "git rebase --abort".
+```
+
+This message tells me that Git was not able to apply my changes to README.md
+after bringing in the new commits from upstream/master.
+
+Running `git status` also gives me some information:
+
+```
+rebase in progress; onto 5ae56e6
+You are currently rebasing branch 'docs-test' on '5ae56e6'.
+  (fix conflicts and then run "git rebase --continue")
+  (use "git rebase --skip" to skip this patch)
+  (use "git rebase --abort" to check out the original branch)
+
+Unmerged paths:
+  (use "git reset HEAD <file>..." to unstage)
+  (use "git add <file>..." to mark resolution)
+
+  both modified:   README.md
+
+no changes added to commit (use "git add" and/or "git commit -a")
+```
+
+To fix, open all the files with conflicts in your editor and decide which edits
+should be applied. Git uses standard conflict-resolution (`<<<<<<<`, `=======`,
+and `>>>>>>>`) markers to indicate where in files there are conflicts.
+
+Tip: You can see recent changes made to a file by running the following
+commands:
+```
+git fetch upstream
+git log -p upstream/master -- /path/to/file
+```
+You can use this to compare the changes that you have made to a file with the
+ones in upstream, helping you avoid undoing changes from a previous commit when
+you are rebasing.
+
+Once you've done that, save the file(s), stage them with `git add` and then
+continue the rebase with `git rebase --continue`:
+
+```
+$ git add README.md
+
+$ git rebase --continue
+Applying: test change for docs
+```
+
+For help resolving merge conflicts, see [basic merge
+conflicts][gitbook-basic-merge-conflicts], [advanced
+merging][gitbook-advanced-merging], and/or GitHub's help on [how to resolve a
+merge conflict][github-help-resolve-merge-conflict].
+
+## Working from multiple computers
+
+Working from multiple computers with Zulip and Git is fine, but you'll need to
+pay attention and do a bit of work to ensure all of your work is readily
+available.
+
+Recall that most Git operations are local. When you commit your changes with
+`git commit` they are safely stored in your *local* Git database only. That is,
+until you *push* the commits to GitHub, they are only available on the computer
+where you committed them.
+
+So, before you stop working for the day, or before you switch computers, push
+all of your commits to GitHub with `git push`:
+
+```
+$ git push origin <branchname>
+```
+
+When you first start working on a new computer, you'll [clone the Zulip
+repository][clone-to-your-machine] and [connect it to Zulip
+upstream][connect-upstream]. A clone retrieves all current commits,
+including the ones you pushed to GitHub from your other computer.
+
+But if you're switching to another computer on which you have already cloned
+Zulip, you need to update your local Git database with new refs from your
+GitHub fork. You do this with `git fetch`:
+
+```
+$ git fetch <usermame>
+```
+
+Ideally you should do this before you have made any commits on the same branch
+on the second computer. Then you can `git merge` on whichever branch you need
+to update:
+
+```
+$ git checkout <my-branch>
+Switched to branch '<my-branch>'
+
+$ git merge origin/master
+```
+
+**If you have already made commits on the second computer that you need to
+keep,** you'll need to use `git log FETCH_HEAD` to identify that hashes of the
+commits you want to keep and then `git cherry-pick <commit>` those commits into
+whichever branch you need to update.
+
+[clone-to-your-machine]: ../git/cloning.html#step-1b-clone-to-your-machine
+[connect-upstream]: ../git/cloning.html#step-1c-connect-your-fork-to-zulip-upstream
+[gitbook-advanced-merging]: https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_advanced_merging
+[gitbook-basic-merge-conflicts]: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts
+[gitbook-git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick
+[gitbook-reset]: https://git-scm.com/docs/git-reset
+[github-help-resolve-merge-conflict]: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/

docs/git/using.md

@@ -0,0 +1,452 @@
+# Using Git as you work
+
+## Know what branch you're working on
+
+When using Git, it's important to know which branch you currently have checked
+out because most git commands implicitly operate on the current branch. You can
+determine the currently checked out branch several ways.
+
+One way is with [git status][gitbook-git-status]:
+
+```
+$ git status
+On branch issue-demo
+nothing to commit, working directory clean
+```
+
+Another is with [git branch][gitbook-git-branch] which will display all local
+branches, with a star next to the current branch:
+
+```
+$ git branch
+* issue-demo
+  master
+```
+
+To see even more information about your branches, including remote branches,
+use `git branch -vva`:
+
+```
+$ git branch -vva
+* issue-123                 517468b troubleshooting tip about provisioning
+  master                    f0eaee6 [origin/master] bug: Fix traceback in get_missed_message_token_from_address().
+  remotes/origin/HEAD       -> origin/master
+  remotes/origin/issue-1234 4aeccb7 Another test commit, with longer message.
+  remotes/origin/master     f0eaee6 bug: Fix traceback in get_missed_message_token_from_address().
+  remotes/upstream/master   dbeab6a Optimize checks of test database state by moving into Python.
+```
+
+You can also configure [Bash][gitbook-other-envs-bash] and
+[Zsh][gitbook-other-envs-zsh] to display the current branch in your prompt.
+
+## Keep your fork up to date
+
+You'll want to [keep your fork][github-help-sync-fork] up-to-date with changes
+from Zulip's main repositories.
+
+**Note about git pull**: You might be used to using `git pull` on other
+projects. With Zulip, because we don't use merge commits, you'll want to avoid
+it. Rather that using `git pull`, which by default is a shortcut for `git fetch
+&& git merge FETCH_HEAD` ([docs][gitbook-git-pull]), you should use `git fetch`
+and then `git rebase`.
+
+First, [fetch][gitbook-fetch] changes from Zulip's upstream repository you
+configured in the step above:
+
+```
+$ git fetch upstream
+```
+
+Next, checkout your `master` branch and [rebase][gitbook-git-rebase] it on top
+of `upstream/master`:
+
+```
+$ git checkout master
+Switched to branch 'master'
+
+$ git rebase upstream/master
+```
+
+This will rollback any changes you've made to master, update it from
+`upstream/master`, and then re-apply your changes. Rebasing keeps the commit
+history clean and readable.
+
+When you're ready, [push your changes][github-help-push] to your remote fork.
+Make sure you're in branch `master` and the run `git push`:
+
+```
+$ git checkout master
+$ git push origin master
+```
+
+You can keep any branch up to date using this method. If you're working on a
+feature branch (see next section), which we recommend, you would change the
+command slightly, using the name of your `feature-branch` rather than `master`:
+
+```
+$ git checkout feature-branch
+Switched to branch 'feature-branch'
+
+$ git rebase upstream/master
+
+$ git push origin feature-branch
+```
+
+## Work on a feature branch
+
+One way to keep your work organized is to create a branch for each issue or
+feature. Recall from [how Git is different][how-git-is-different] that
+**Git is designed for lightweight branching and merging.** You can and should
+create as many branches as you'd like.
+
+First, make sure your master branch is up-to-date with Zulip upstream ([see
+how][zulip-git-guide-up-to-date]).
+
+Next, from your master branch, create a new tracking branch, providing a
+descriptive name for your feature branch:
+
+```
+$ git checkout master
+Switched to branch 'master'
+
+$ git checkout -b issue-1755-fail2ban
+Switched to a new branch 'issue-1755-fail2ban'
+```
+
+Alternatively, you can create a new branch explicitly based off
+`upstream/master`:
+
+```
+$ git checkout -b issue-1755-fail2ban upstream/master
+Switched to a new branch 'issue-1755-fail2ban'
+```
+
+Now you're ready to work on the issue or feature.
+
+## Run linters and tests locally
+
+In addition to having Travis run tests and linters each time you push a new
+commit, you can also run them locally. See [testing](../testing/testing.html) for details.
+
+## Stage changes
+
+Recall that files tracked with Git have possible three states:
+committed, modified, and staged.
+
+To prepare a commit, first add the files with changes that you want
+to include in your commit to your staging area. You *add* both new files and
+existing ones. You can also remove files from staging when necessary.
+
+### Get status of working directory
+
+To see what files in the working directory have changes that have not been
+staged, use `git status`.
+
+If you have no changes in the working directory, you'll see something like
+this:
+
+```
+$ git status
+On branch issue-123
+nothing to commit, working directory clean
+```
+
+If you have unstaged changes, you'll see something like this:
+
+```
+On branch issue-123
+Untracked files:
+  (use "git add <file>..." to include in what will be committed)
+
+        newfile.py
+
+nothing added to commit but untracked files present (use "git add" to track)
+```
+
+### Stage additions with git add
+
+To add changes to your staging area, use `git add <filename>`. Because `git
+add` is all about staging the changes you want to commit, you use it to add
+*new files* as well as *files with changes* to your staging area.
+
+Continuing our example from above, after we run `git add newfile.py`, we'll see
+the following from `git status`:
+
+```
+On branch issue-123
+Changes to be committed:
+  (use "git reset HEAD <file>..." to unstage)
+
+        new file:   newfile.py
+```
+
+You can view the changes in files you have staged with `git diff --cached`. To
+view changes to files you haven't yet staged, just use `git diff`.
+
+If you want to add all changes in the working directory, use `git add -A`
+([documentation][gitbook-add]).
+
+
+You can also stage changes using your graphical Git client.
+
+If you stage a file, you can undo it with `git reset HEAD <filename>`. Here's
+an example where we stage a file `test3.txt` and then unstage it:
+
+```
+$ git add test3.txt
+On branch issue-1234
+Changes to be committed:
+  (use "git reset HEAD <file>..." to unstage)
+
+        new file:   test3.txt
+
+$ git reset HEAD test3.txt
+$ git status
+On branch issue-1234
+Untracked files:
+  (use "git add <file>..." to include in what will be committed)
+
+        test3.txt
+
+nothing added to commit but untracked files present (use "git add" to track)
+```
+
+### Stage deletions with git rm
+
+To remove existing files from your repository, use `git rm`
+([documentation][gitbook-rm]). This command can either stage the file for
+removal from your repository AND delete it from your working directory or just
+stage the file for deletion and leave it in your working directory.
+
+To stage a file for deletion and **remove** it from your working directory, use
+`git rm <filename>`:
+
+```
+$ git rm test.txt
+rm 'test.txt'
+
+$ git status
+On branch issue-1234
+Changes to be committed:
+  (use "git reset HEAD <file>..." to unstage)
+
+        deleted:    test.txt
+
+$ ls test.txt
+ls: No such file or directory
+```
+
+To stage a file for deletion and **keep** it in your working directory, use
+`git rm --cached <filename>`:
+
+```
+$ git rm --cached test2.txt
+rm 'test2.txt'
+
+$ git status
+On branch issue-1234
+Changes to be committed:
+  (use "git reset HEAD <file>..." to unstage)
+
+        deleted:    test2.txt
+
+$ ls test2.txt
+test2.txt
+```
+
+If you stage a file for deletion with the `--cached` option, and haven't yet
+run `git commit`, you can undo it with `git reset HEAD <filename>`:
+
+```
+$ git reset HEAD test2.txt
+```
+
+Unfortunately, you can't restore a file deleted with `git rm` if you didn't use
+the `--cache` option. However, `git rm` only deletes files it knows about.
+Files you have never added to git won't be deleted.
+
+## Commit changes
+
+When you've staged all your changes, you're ready to commit. You can do this
+with `git commit -m "My commit message."` to include a commit message.
+
+Here's an example of committing with the `-m` for a one-line commit message:
+
+```
+$ git commit -m "Add a test commit for docs."
+[issue-123 173e17a] Add a test commit for docs.
+ 1 file changed, 1 insertion(+)
+ create mode 100644 newfile.py
+```
+
+You can also use `git commit` without the `-m` option and your editor to open,
+allowing you to easily draft a multi-line commit message.
+
+How long your commit message should be depends on where you are in your work.
+Using short, one-line messages for commits related to in-progress work makes
+sense. For a commit that you intend to be final or that encompasses a
+significant amount or complex work, you should include a longer message.
+
+Keep in mind that your commit should contain a 'minimal coherent idea' and have
+a quality commit message. See Zulip docs [Commit
+Discipline][zulip-rtd-commit-discipline] and [Commit
+messages][zulip-rtd-commit-messages] for details.
+
+Here's an example of a longer commit message that will be used for a pull request:
+
+```
+Integrate Fail2Ban.
+
+Updates Zulip logging to put an unambiguous entry into the logs such
+that fail2ban can be configured to look for these entries.
+
+Tested on my local Ubuntu development server, but would appreciate
+someone testing on a production install with more users.
+
+Fixes #1755.
+```
+
+The first line is the summary. It's a complete sentence, ending in a period. It
+uses a present-tense action verb, "Integrate", rather than "Integrates" or
+"Integrating".
+
+The following paragraphs are full prose and explain why and how the change was
+made. It explains what testing was done and asks specifically for further
+testing in a more production-like environment.
+
+The final paragraph indicates that this commit addresses and fixes issue #1755.
+When you submit your pull request, GitHub will detect and link this reference
+to the appropriate issue. Once your commit is merged into zulip/master, GitHub
+will automatically close the referenced issue. See [Closing issues via commit
+messages][github-help-closing-issues] for details.
+
+Make as many commits as you need to to address the issue or implement your feature.
+
+## Push your commits to GitHub
+
+As you're working, it's a good idea to frequently push your changes to GitHub.
+This ensures your work is backed up should something happen to your local
+machine and allows others to follow your progress. It also allows you to
+[work from multiple computers][self-multiple-computers] without losing work.
+
+Pushing to a feature branch is just like pushing to master:
+
+```
+$ git push origin <branch-name>
+Counting objects: 6, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (4/4), done.
+Writing objects: 100% (6/6), 658 bytes | 0 bytes/s, done.
+Total 6 (delta 3), reused 0 (delta 0)
+remote: Resolving deltas: 100% (3/3), completed with 1 local objects.
+To git@github.com:christi3k/zulip.git
+ * [new branch]      issue-demo -> issue-demo
+```
+
+If you want to see what git will do without actually performing the push, add
+the `-n` (dry-run) option: `git push -n origin <branch-name>`. If everything
+looks good, re-run the push command without `-n`.
+
+If the feature branch does not already exist on GitHub, it will be created when
+you push and you'll see `* [new branch]` in the command output.
+
+## Examine and tidy your commit history
+
+Examining your commit history prior to submitting your pull request is a good
+idea. Is it tidy such that each commit represents a minimally coherent idea
+(see [commit discipline][zulip-rtd-commit-discipline])? Do your commit messages
+follow [Zulip's style][zulip-rtd-commit-messages]? Will the person reviewing
+your commit history be able to clearly understand your progression of work?
+
+On the command line, you can use the `git log` command to display an easy to
+read list of your commits:
+
+```
+$ git log --all --graph --oneline --decorate
+
+* 4f8d75d (HEAD -> 1754-docs-add-git-workflow) docs: Add details about configuring Travis CI.
+* bfb2433 (origin/1754-docs-add-git-workflow) docs: Add section for keeping fork up-to-date to Git Guide.
+* 4fe10f8 docs: Add sections for creating and configuring fork to Git Guide.
+* 985116b docs: Add graphic client recs to Git Guide.
+* 3c40103 docs: Add stubs for remaining Git Guide sections.
+* fc2c01e docs: Add git guide quickstart.
+| * f0eaee6 (upstream/master) bug: Fix traceback in get_missed_message_token_from_address().
+```
+
+Alternatively, use your graphical client to view the history for your feature branch.
+
+If you need to update any of your commits, you can do so with an interactive
+[rebase][github-help-rebase]. Common reasons to use an interactive rebase
+include:
+
+- squashing several commits into fewer commits
+- splitting a single commit into two or more
+- rewriting one or more commit messages
+
+There is ample documentation on how to rebase, so we won't go into details
+here. We recommend starting with GitHub's help article on
+[rebasing][github-help-rebase] and then consulting Git's documentation for
+[git-rebase][gitbook-git-rebase] if you need more details.
+
+If all you need to do is edit the commit message for your last commit, you can
+do that with `git commit --amend`. See [Git Basics - Undoing
+Things][gitbook-basics-undoing] for details on this and other useful commands.
+
+## Force-push changes to GitHub after you've altered your history
+
+Any time you alter history for commits you have already pushed to GitHub,
+you'll need to prefix the name of your branch with a `+`. Without this, your
+updates will be rejected with a message such as:
+
+```
+$ git push origin 1754-docs-add-git-workflow
+To git@github.com:christi3k/zulip.git
+ ! [rejected] 1754-docs-add-git-workflow -> 1754-docs-add-git-workflow (non-fast-forward)
+error: failed to push some refs to 'git@github.com:christi3k/zulip.git'
+hint: Updates were rejected because the tip of your current branch is behind
+hint: its remote counterpart. Integrate the remote changes (e.g.
+hint: 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+
+```
+
+Re-running the command with `+<branch>` allows the push to continue by
+re-writing the history for the remote repository:
+
+```
+$ git push origin +1754-docs-add-git-workflow
+Counting objects: 12, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (12/12), done.
+Writing objects: 100% (12/12), 3.71 KiB | 0 bytes/s, done.
+Total 12 (delta 8), reused 0 (delta 0)
+remote: Resolving deltas: 100% (8/8), completed with 2 local objects.
+To git@github.com:christi3k/zulip.git
+ + 2d49e2d...bfb2433 1754-docs-add-git-workflow -> 1754-docs-add-git-workflow (forced update)
+
+```
+
+This is perfectly okay to do on your own feature branches, especially if you're
+the only one making changes to the branch. If others are working along with
+you, they might run into complications when they retrieve your changes because
+anyone who has based their changes off a branch you rebase will have to do a
+complicated rebase.
+
+[gitbook-add]: https://git-scm.com/docs/git-add
+[gitbook-basics-undoing]: https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things
+[gitbook-fetch]: https://git-scm.com/docs/git-fetch
+[gitbook-git-branch]: https://git-scm.com/docs/git-branch
+[gitbook-git-pull]: https://git-scm.com/docs/git-pull
+[gitbook-git-rebase]: https://git-scm.com/docs/git-rebase
+[gitbook-git-status]: https://git-scm.com/docs/git-status
+[gitbook-other-envs-bash]: https://git-scm.com/book/en/v2/Git-in-Other-Environments-Git-in-Bash
+[gitbook-other-envs-zsh]: https://git-scm.com/book/en/v2/Git-in-Other-Environments-Git-in-Zsh
+[gitbook-rm]: https://git-scm.com/docs/git-rm
+[github-help-closing-issues]: https://help.github.com/articles/closing-issues-via-commit-messages/
+[github-help-push]: https://help.github.com/articles/pushing-to-a-remote/
+[github-help-rebase]: https://help.github.com/articles/using-git-rebase/
+[github-help-sync-fork]: https://help.github.com/articles/syncing-a-fork/
+[how-git-is-different]: ./the-git-difference.html
+[zulip-git-guide-up-to-date]: ../git/using.html#keep-your-fork-up-to-date
+[zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline
+[zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages

docs/git/zulip-tools.md

@@ -0,0 +1,148 @@
+# Zulip-specific tools
+
+This section will document the zulip-specific git tools contributors will find helpful.
+
+## Set up git repo script
+
+In the `tools` directory of [zulip/zulip][github-zulip-zulip] you'll find a
+bash script `setup-git-repo`. This script installs the Zulip pre-commit hook.
+This hook will run each time you `git commit` to automatically run linters,
+etc. The hook passes no matter the result of the linter, but you should still
+pay attention to any notices or warnings it displays.
+
+It's simple to use. Make sure you're in the clone of zulip and run the following:
+
+```
+$ ./tools/setup-git-repo
+```
+
+The script doesn't produce any output if successful. To check that the hook has
+been installed, print a directory listing for `.git/hooks` and you should see
+something similar to:
+
+```
+$ ls -l .git/hooks
+pre-commit -> ../../tools/pre-commit
+```
+
+## Set up Travis CI integration
+
+You might also wish to [configure your fork for use with Travis CI][zulip-git-guide-travisci].
+
+## Reset to pull request
+
+`tools/reset-to-pull-request` is a short-cut for [checking out a pull request
+locally][zulip-git-guide-fetch-pr]. It works slightly differently from the method
+described above in that it does not create a branch for the pull request
+checkout.
+
+**This tool checks for uncommitted changes, but it will move the
+  current branch using `git reset --hard`.  Use with caution.**
+
+First, make sure you are working in a branch you want to move (in this
+example, we'll use the local `master` branch). Then run the script
+with the ID number of the pull request as the first argument.
+
+```
+$ git checkout master
+Switched to branch 'master'
+Your branch is up-to-date with 'origin/master'.
+
+$ ./tools/reset-to-pull-request 1900
++ request_id=1900
++ git fetch upstream pull/1900/head
+remote: Counting objects: 159, done.
+remote: Compressing objects: 100% (17/17), done.
+remote: Total 159 (delta 94), reused 91 (delta 91), pack-reused 51
+Receiving objects: 100% (159/159), 55.57 KiB | 0 bytes/s, done.
+Resolving deltas: 100% (113/113), completed with 54 local objects.
+From https://github.com/zulip/zulip
+ * branch            refs/pull/1900/head -> FETCH_HEAD
++ git reset --hard FETCH_HEAD
+HEAD is now at 2bcd1d8 troubleshooting tip about provisioning
+```
+
+## Fetch a pull request and rebase
+
+`tools/fetch-rebase-pull-request` is a short-cut for [checking out a pull
+request locally][zulip-git-guide-fetch-pr] in its own branch and then updating it with any
+changes from upstream/master with `git rebase`.
+
+Run the script with the ID number of the pull request as the first argument.
+
+```
+$ tools/fetch-rebase-pull-request 1913
++ request_id=1913
++ git fetch upstream pull/1913/head
+remote: Counting objects: 4, done.
+remote: Compressing objects: 100% (4/4), done.
+remote: Total 4 (delta 0), reused 0 (delta 0), pack-reused 0
+Unpacking objects: 100% (4/4), done.
+From https://github.com/zulip/zulip
+ * branch            refs/pull/1913/head -> FETCH_HEAD
++ git checkout upstream/master -b review-1913
+Branch review-1913 set up to track remote branch master from upstream.
+Switched to a new branch 'review-1913'
++ git reset --hard FETCH_HEAD
+HEAD is now at 99aa2bf Add provision.py fails issue in common erros
++ git pull --rebase
+Current branch review-1913 is up to date.
+```
+
+## Fetch a pull request without rebasing
+
+`tools/fetch-pull-request` is a similar to `tools/fetch-rebase-pull-request`, but
+it does not rebase the pull request against upstream/master, thereby getting
+exactly the same repository state as the commit author had.
+
+Run the script with the ID number of the pull request as the first argument.
+
+```
+$ tools/fetch-pull-request 5156
++ git diff-index --quiet HEAD
++ request_id=5156
++ remote=upstream
++ git fetch upstream pull/5156/head
+From https://github.com/zulip/zulip
+ * branch            refs/pull/5156/head -> FETCH_HEAD
++ git checkout -B review-original-5156
+Switched to a new branch 'review-original-5156'
++ git reset --hard FETCH_HEAD
+HEAD is now at 5a1e982 tools: Update clean-branches to clean review branches.
+```
+
+## Delete unimportant branches
+
+`tools/clean-branches` is a shell script that removes branches that are either:
+
+1. Local branches that are ancestors of origin/master.
+2. Branches in origin that are ancestors of origin/master and named like `$USER-*`.
+3. Review branches created by `tools/fetch-rebase-pull-request` and `tools/fetch-pull-request`.
+
+First, make sure you are working in branch `master`. Then run the script without any
+arguments for default behavior. Since removing review branches can inadvertently remove any
+feature branches whose names are like `review-*`, it is not done by default. To
+use it, run `tools/clean-branches --reviews`.
+
+```
+$ tools/clean-branches --reviews
+Deleting local branch review-original-5156 (was 5a1e982)
+```
+
+## Merge conflict on yarn.lock file
+
+If there is a merge conflict on yarn.lock, yarn should be run to
+regenerate the file. *Important* don't delete the yarn.lock file. Checkout the
+latest one from origin/master so that yarn knows the previous asset versions.
+
+Run the following commands
+```
+git checkout origin/master -- yarn.lock
+yarn install
+git add yarn.lock
+git rebase --continue
+```
+
+[github-zulip-zulip]: https://github.com/zulip/zulip/
+[zulip-git-guide-fetch-pr]: ../git/collaborate.html#checkout-a-pull-request-locally
+[zulip-git-guide-travisci]: ../git/cloning.html#step-3-configure-travis-ci-continuous-integration

docs/index.rst

@@ -35,6 +35,7 @@ Contents:
 * :ref:`Zulip in Production <zulip-in-production>`
 * :ref:`Development Environment <development-environment>`
 * :ref:`Developer Tutorials <developer-tutorials>`
+* :ref:`Git Guide <git-guide>`
 * :ref:`Code Contribution Guide <code-contribution-guide>`
 * :ref:`Code Testing <code-testing>`
 * :ref:`Subsystem Documentation <subsystem-documentation>`
@@ -68,6 +69,13 @@ Contents:
 
    tutorials/index
 
+.. _git-guide:
+
+.. toctree::
+   :maxdepth: 3
+
+   git/index
+
 .. _code-contribution-guide:
 
 .. toctree::

docs/testing/travis.md

@@ -70,7 +70,7 @@ our configuration, you'll want to look at these closely.
   that every remote branch you push will be tested, which can be
   helpful when debugging something complicated.
 
-[travis-fork]: ../contributing/git-guide.html#step-3-configure-travis-ci-continuous-integration
+[travis-fork]: ../git/cloning.html#step-3-configure-travis-ci-continuous-integration
 
 ## Performance optimizations
 
@@ -114,4 +114,3 @@ that are irrelevant to Zulip in
 [`tools/travis/setup-production`][setup-production].
 
 [setup-production]: https://github.com/zulip/zulip/blob/master/tools/travis/setup-production
-

docs/tutorials/reading-list.md

@@ -148,7 +148,7 @@ Some titles have been shortened for organizational purposes.
 
 You may want to take a look first at our [Git and GitHub guide][].
 
-[Git and GitHub guide]: ../contributing/git-guide.html
+[Git and GitHub guide]: ../git/index.html
 
 *Article* - [Git tips][]
 

docs/tutorials/shell-tips.md

@@ -339,7 +339,7 @@ At first it seems like magic, but once you get the basic concepts you find it
 extremely useful and even easy to use (at least the 99% of the time).
 
 To learn more about how to use it, read
-[our docs](../contributing/git-guide.html) on Git and
+[our docs](../git/index.html) on Git and
 Github.
 
 [This cheatsheet][git-cheat-detailed]