This document provides a quick step by step (using command line), on how to get a branch quickly up and running.
You can create a single working copy for your projects or many working copy's. In general Git branching allows you to work on multiple projects in a single working copy relatively easily. If you want to work on concurrent projects you may wish to have multiple working copies. You can work out the flow that works best for you. Complete these instructions per working copy:
git clone <paste copied URL here> <path to target directory>. It should look something like this:
git clone https://github.com/pasamio/joomla-platform.git /Users/pasamio/joomla_platform. Git will automatically create the path to the directory if it doesn't exist.
cd <path to target directory>, e.g.
git remote add joomla <copied URL>it should look like this:
git remote add joomla git://github.com/joomla/joomla-platform.git.
At this point we've cloned your repository (it will be the remote known as 'origin') and add a remote for the Joomla Project repository you're working on (as 'joomla').
Each time you start working on a new feature/bug fix/concept, I suggest that you start a new branch. Branching and merging in Git is easier than in Subversion with many conflicts around the same changes being made in two places handled automatically. Each branch can contain a particular project that you are working on and you can easily switch between branches in the same working copy. Because Git is designed to be distributed, you can commit changes to work in a branch prior to switch branches without having to push this to the wider world.
git fetch --all
git checkout -b <yourbranchname> joomla/master
git push -u origin
This may ask for your GitHub username and password if you are using the HTTP protocol. If you are using the SSH protocol it may ask you for the passphrase for your SSH key. The "-u" option is used to mark this as the "upstream" version and will track against this branch. This means in future you can "git push" and "git pull" to receive updates from this remote and branch automatically (if you're working on your own, you'll likely only be doing a 'git push').
Now you've created a new branch and set it up to push and pull from your server. You can then use this branch to make a pull request.
After a while it will become necessary to merge down changes from the upstream repository. This may be because those changes conflict with other changes in the repository (making a pull request "unmergeable"), because you need/want updates from the repository to continue working or just to keep the delta of changes small between your commits.
You have two major options. The first is to use a simple merge. This will attempt to pick up the changes from the remote repository and merge them locally automatically. This may result in a conflict with your work which you will be required to merge manually (just like what would happen with Subversion if there is a conflict).
You can merge either by doing an explicit "git merge" or by doing a "git pull". Doing a "git pull" is like doing a "git fetch" followed by a "git merge" and will ensure you're merging the latest changes from the remote repository:
git merge joomla master
This will pull down the latest changes from the repository and merge them. You may get a notice that there is a conflict you need to resolve. Once you've resolved the conflict, you will need to do a commit to mark those changes.
The last step you might need to do is to squash your commits. Squashing commits takes many commits and makes them into a single commit. This helps with keeping the history clean and concise. It also helps later on tracking down changes.
Instead of repeating some already well written documentation, here I'll refer to the Git book: http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits
This is a copy of step 2 and 3:
silversaviour:~ pasamio$ git clone https://github.com/pasamio/joomla-platform.git /Users/pasamio/joomla_platform Cloning into /Users/pasamio/joomla_platform... remote: Counting objects: 53264, done. remote: Compressing objects: 100% (19227/19227), done. remote: Total 53264 (delta 35370), reused 50211 (delta 33139) Receiving objects: 100% (53264/53264), 13.51 MiB | 2.48 MiB/s, done. Resolving deltas: 100% (35370/35370), done. silversaviour:~ pasamio$ cd /Users/pasamio/joomla_platform silversaviour:joomla_platform pasamio$ git remote add joomla git://github.com/joomla/joomla-platform.git silversaviour:joomla_platform pasamio$ git fetch --all Fetching origin Fetching joomla remote: Counting objects: 592, done. remote: Compressing objects: 100% (266/266), done. remote: Total 485 (delta 290), reused 380 (delta 192) Receiving objects: 100% (485/485), 169.43 KiB, done. Resolving deltas: 100% (290/290), completed with 59 local objects. From git://github.com/joomla/joomla-platform * [new branch] gh-pages -> joomla/gh-pages * [new branch] master -> joomla/master * [new branch] staging -> joomla/staging * [new tag] 11.2 -> 11.2 * [new tag] 11.3 -> 11.3 * [new tag] 11.4 -> 11.4 * [new tag] 12.1 -> 12.1 silversaviour:joomla_platform pasamio$ git checkout -b branch_demo joomla/master Branch branch_demo set up to track remote branch master from joomla. Switched to a new branch 'branch_demo' silversaviour:joomla_platform pasamio$ git push -u origin Username: Password: Branch master set up to track remote branch master from origin. Everything up-to-date silversaviour:joomla_platform pasamio$
Note: This document may not be internally linked, I'm using it on GitHub to reference.