Git workflow

With Commit Access

TODO

Without Commit Access

Repositories

• upstream repository - GitHub-hosted base repository, e.g. tiliado/nuvolaplayer. All official development happens there. This repository is the target for pull requests.
• origin repository - Your own GitHub-hosted copy/fork of the upstream repository, e.g. fenryxo/nuvolaplayer. You will push all your branches there and create pull requests from them.
• local repository - A local clone of your origin repository on your disk. You will create feature branches and will be hacking there.

GitHub repositories                    :: Your disk
Upstream account :: Your account       ::
                 ::                    ::
[upstream]-----(fork)--->[origin]<---(clone)--->[local] 
   ↑             ::         |          ::
   |             ::         ↓          ::
   +---<---(pull request)---+          ::
                 ::                    ::

Set-up your origin and local repositories

• Go to the upstream repository page, e.g. tiliado/nuvolaplayer, and click Fork button.
• You should be redirected to your fork, e.g. fenryxo/nuvolaplayer. The repository title should show "fenryxo/nuvolaplayer forked from tiliado/nuvolaplayer". This fork is your origin repository.
• Copy a clone URL at the top of your fork's page, either HTTPS URL starting with https://github.com or SSH URL starting with git@github.com. Create a local read-write clone of your origin repository. Lines starting with # are comments for better understanding, lines starting with $ are command you type (without the $ character itself). The remaining lines are output of commands.

# Clone over HTTPS
$ git clone https://github.com/fenryxo/nuvolaplayer.git
# Or clone over SSH
$ git clone git@github.com:fenryxo/nuvolaplayer.git
Cloning into 'nuvolaplayer'...
remote: Counting objects: 5835, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 5835 (delta 1), reused 0 (delta 0), pack-reused 5825
Receiving objects: 100% (5835/5835), 5.01 MiB | 3.13 MiB/s, done.
Resolving deltas: 100% (4130/4130), done.
Checking connectivity... done.

# Go into your clone
$ cd nuvolaplayer

# List remote repositories
# - You have configured your origin repository for both
#   fetching (downloading, read access) and pushing
#   (uploading, write access)
$ git remote -v
# name  URL                                     action
origin	git@github.com:fenryxo/nuvolaplayer.git (fetch)
origin	git@github.com:fenryxo/nuvolaplayer.git (push)

# Check status of the repository
# - Your current branch is called master.
# - Your local master branch is up-to-date with the
#   master branch in the origin repository.
# - There are no uncommitted changes.
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

• Go to the the upstream repository page, e.g. tiliado/nuvolaplayer, and copy a clone URL at the top of your the page, either HTTPS URL starting with https://github.com or SSH URL starting with git@github.com.

# Go into your clone
$ cd nuvolaplayer

# Add upstream remote repository
$ git remote add upstream git@github.com:tiliado/nuvolaplayer.git

# Set no-op push (upload) URL to prevent accidents. Your changes
# Will get to the upstream repository via pull requests.
$ git remote set-url --push upstream UPSTREAM_PUSH_DISALLOWED

# Fetch info about the upstream repository
$ git fetch upstream
From github.com:tiliado/nuvolaplayer
 * [new branch]      3.0.x      -> upstream/3.0.x
 * [new branch]      lyrics     -> upstream/lyrics
 * [new branch]      master     -> upstream/master

# List remote repositories
# - You have configured upstream repository only for
#   fetching (downloading, read access), because the
#   URL of pushing (uploading, write access) in invalid.
$ git remote -v
origin	git@github.com:fenryxo/nuvolaplayer.git (fetch)
origin	git@github.com:fenryxo/nuvolaplayer.git (push)
upstream	git@github.com:tiliado/nuvolaplayer.git (fetch)
upstream	UPSTREAM_PUSH_DISALLOWED (push)

Keep master branches in sync with upstream

• Remember: Always keep your local/origin master branches in sync with the upstream master branch.

• Remember: Never make any changes directly in the master branch, but use it to create side branches for that.

• Switch to your clone: $ cd nuvolaplayer

• Fetch info about the upstream repository

$ git fetch upstream
From github.com:tiliado/nuvolaplayer
 * [new branch]      3.0.x      -> upstream/3.0.x
 * [new branch]      lyrics     -> upstream/lyrics
 * [new branch]      master     -> upstream/master

• Check out your fork's local master branch.

$ git checkout master
Switched to branch 'master'

• Merge & fast-forward changes in upstream master branch.

$ git merge --ff-only upstream/master
Updating 22da496..b856f95
Fast-forward
 src/nuvolakit-runner/webkit/WebEngine.vala | 18 ------------------
 src/nuvolakit-runner/webkit/WebView.vala   | 18 ++++++++++++++++++
 2 files changed, 18 insertions(+), 18 deletions(-)

• Update your origin master branch.

$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean

$ git push
Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (1/1), done.
Writing objects: 100% (4/4), 601 bytes | 0 bytes/s, done.
Total 4 (delta 3), reused 3 (delta 3)
To git@github.com:fenryxo/nuvolaplayer.git
   22da496..b856f95  master -> master

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

Create a feature/side branch

TODO

Push your feature branch to GitHub

TODO

Make a pull request

TOO

Repeat

TODO