Oh My Zsh is a community-driven project and contributions are welcome, but it all works best with a proper setup. Here follow the best practices for setting up a fork and getting started for contributing.
The lifecycle every contribution follows — the two setups below differ only in what your remotes are called.
01Prerequisites
You will of course need Git and a UNIX terminal. You should be familiar with the basics of contributing on GitHub.
You will have to make a choice — whether you simply want to properly send PRs, or if you also wish to maintain your own fork (with your own changes) as a personal alternative version of OMZ. Think about it, it will come around later on.
The following section explains how to set up your local Oh My Zsh install with the proper remote repositories.
02Setting up
From this point on, <name> stands for your GitHub username.
1
Fork the original repository (button at the top of the repo's page).
This supposes that you have Oh My Zsh installed already in $ZSH (default: ~/.oh-my-zsh) with the origin remote pointing to the original repository.
2
Now make the choice: either we keep it easy and simple, need-to-know basis, or you want a fully maintained fork with your own changes. Here follows a binary dichotomy:
TRACK A
Simple contribution
auto-upgrade works
you can send clean PRs
your fork is not maintained
you are not using your own master branch
TRACK B
Maintained fork
you can send clean PRs
maintain your own fork with changes
use and share your master branch
auto-upgrade will not work
TRACK ASimple contribution setup
All the following uses <name> for the remote name, but you can use something else.
3
Go to your local install directory and add your own repository as a remote
cd $ZSH
git remote add <name> git@github.com:<name>/oh-my-zsh.git
Upgrading
As long as your local master branch cleanly follows origin/master (which still points to the original repository), auto-upgrade should work fine.
More setups
On a new machine, simply install OMZ as usual, do step 3, and of course copy your startup files; you will be able to get upgrades, and to work on your pending PRs.
When you want to get the latest upgrades from the original repository (aka upstream), simply git pull upstream master; you may have to solve conflicts with your own changes of course; when you are satisfied with the update you can git push origin master.
Upgrading — origin
When you want to get the latest upgrades from your own fork (aka origin), simply git pull --rebase origin master; you may have to solve conflicts with your local changes of course; when you are satisfied with the update you can git push --force origin master.
More setups
On a new machine, simply git clone git@github.com:<name>/oh-my-zsh.git ~/.oh-my-zsh and git remote add upstream git@github.com:ohmyzsh/ohmyzsh.git, and of course copy your startup files; you will be able to get upgrades, and to work on your pending PRs.
You are now on your dedicated PR branch. Time to commit some changes!
2
Send your commits
git push <name> my-new-pr
You can now go to GitHub and create the PR.
Updating
In case there are conflicting changes upstream after you created the branch, you will have to git pull --rebase origin master on my-new-pr branch and resolve conflicts, and then git push --force <name> my-new-pr, in order to keep your PR up to date.
More setups
On another machine, simply git checkout <name>/my-new-pr and git checkout -b my-new-pr to continue working on a pending PR.
You are now on your dedicated PR branch. Time to commit some changes!
2
Send your commits
git push origin my-new-pr
You can now go to GitHub and create the PR.
Updating
In case there are conflicting changes upstream after you created the branch, you will have to git pull --rebase upstream master on my-new-pr branch and resolve conflicts, and then git push --force origin my-new-pr, in order to keep your PR up to date.
More setups
On another machine, simply git checkout origin/my-new-pr and git checkout -b my-new-pr to continue working on a pending PR.
This wiki is automatically published from ohmyzsh/wiki. To edit this page, go to ohmyzsh/wiki, make your changes and submit a Pull Request.