zulip/docs/working-copies.md

Working copies

When you work on Zulip code, there are three working copies of the Zulip git repo that you are generally concerned with:

• local copy: This lives on your laptop or your remove dev instance.
• forked copy: This lives on GitHub, and it's tied to your account.
• official Zulip repo: https://github.com/zulip/zulip

We sometimes call the forked copy the origin remote.

We sometimes call the official repo the upstream remote.

When you work on Zulip code, you will end up moving code between the various working copies.

Workflows

Sometimes you need to get commits. Here are some scenarios:

• You may fork the official Zulip repo to your GitHub fork.
• You may fetch commits from the offical Zulip repo to your local copy.
• You occasionally may fetch commits from your forked copy.

Sometimes you want to publish commits. Here are scenarios:

• You push code from your local copy to your GitHub fork. (You usually want to put the commit on a feature branch.)
• You submit a PR to the official Zulip repo.

Finally, the Zulip core team will occasionally want your changes!

• The Zulip core team can accept your changes and add them to the official repo, usually on the master branch.

Names

We call remote working copies of the repository by these short names.

• origin: This is your fork.
• upstream: This is the official Zulip repo.

Relevant git commands

The following commands are useful for moving commits between working copies:

• git fetch: This grabs code from another repo to your local copy.
• git push: This pushes code from your local repo to one of the remotes.
• git remote: This helps you configure short names for remotes.
• git pull: Do not use this, please!