Symphony.

As you probably know by now, we use git for managing the Symphony source code. In addition to that, we give everyone the ability to grab code directly from git, or even contribute their own changes. Github is our way of making all this possible and you can browse the main repository at http://github.com/symphony/symphony-2/tree/master

To clear up a couple of things:

1. Clone. Makes an exact duplicate of the repository. Git is a distributed system, so there is no one central repository like in other systems. You clone is totally yours. You can modify the code, create new branches, do whatever you want. You can then update your clone based on someone else's repository. Most of the time you will be doing that by pulling from the github repository.

2. Fork. This is a GitHub term. It is the same as cloning, except, it creates a new github project for you and your clone url becomes slightly different. The advantage here is you can push your changes to github independent of the official repository you forked.

Here is the current structure of the Symphony 2 Git repository:

• Master: The latest stable code reflecting an official version release.

• Integration: This is where new code goes that is not apart of the official release (master). All pull requests must apply cleanly to this branch. Periodically it will be merged with the master branch to form a new official stable release. The name 'integration' may change, I haven't settled yet, but the idea remains.

Hope that made sense. So, given that, the idea is this:

a. You want to just get the latest offical copy of Symphony. You're not interested in unstable code. In this situation you would just clone the master branch. git clone git://github.com/symphony/symphony-2.git and then whenever there is a new official release, you would use git pull origin master to get that code.

b. You want the most recent code. Bug fixes and coolness. Same as (a), but you will need to use the 'integration' branch. Issuing the following commands would do it:

git clone git://github.com/symphony/symphony-2.git 
git checkout -b integration
git pull origin integration

That last line is reused anytime you want to update your repository.

c. You'd like to make contributions to the Symphony project. This is when you would fork the Symphony repository. It would create a new project under your name based on the Symphony repository. Have a look at this guide about forks and this slightly more advanced one on the github site. In this scenario you don't really want the master and integration branches, since you're contributing. The steps are similar to above, but instead, I would suggest you do the following:

git clone git://github.com/USERNAME/YOUR_FORK.git 
git pull origin integration
git push origin master
git push origin :integration

This will pull the integration branch directly into your master branch, then push straight back to master, merging the code. The last line removes the integration branch since you don't really need it. When you're ready to have your changes added to the Symphony repository, take a look at this guide to issuing pull requests.

I really hope that helped. It's a little tricky to wrap your head around, and I'm not sure if I did a very good job of explaining. Please ask questions and I'll do my best.

Thanks, I will include a version of this in the documentation.

I should mention that the idea in (c) of removing the integration branch and merging with master for your own forked copy is really a matter of personal preference. You could keep both master and integration as reflections of the official Symphony repo and create a new branch "my-funky-stuff" which your changes go to. Pull requests come from the "my-funky-stuff" branch, and keep master + integration clean.

git clone git://github.com/USERNAME/YOUR_FORK.git 
git checkout -b integration
git pull origin integration
git checkout -b funky
git merge integration
git push origin funky

I think that is what I mean. :p

I'm a visually thinking person and so I have to say that I really hate this git stuff.

I may be dump but how - after using method c and pulling and pushing the original integration branch into my master and making changes to my own fork - do I merge updates from the original repository to my own fork?!

Did I say that I ... "don't like" git?! Arghh!!

(And yes I know there should be tons of superb tutorials - but I don't get it!)

Nils, if Your console/terminal supports auto-completion it should be easy to pull changes. Just type:

git pull

and hit TAB (or hit it twice :). Name of repository depends on how You created Your fork, so i can't really tell You what full command should be. If You created Your fork like: "on github click fork button, clone Your fork on Your computer", then You may need to add remote repository path first (i mean, if it's not already there):

git remote add [NAME] git://github.com/symphony/symphony-2.git

where [NAME] is what You want to call it, e.g., "s21" :).

After Your local clone knows about original repo, use this command:

git pull [NAME] [BRANCH]

where name is the name You gave it, and [BRANCH] is the name of branch, e.g., "integration".

Thanks Marcin for your kind explanations.
I've read the guides at github (and a few other tutorials) and I'm sure I did what your are describing above, but for some reasons I'll always get errors or my repository messes up. I think I'll take a deep breath and wait until tomorrow - maybe I can get things working then.

At the moment this git thing really frustrats me.
I never liked DOS, I'm happily using an OS with graphic interface that allows drag and drop and visualizes everything that can be visualized ... and now that! Cryptographically advanced stuff to get Symphony working ;)

So, tomorrow certainly will be a better day for me, git and Symphony ...
Thanks again,
Nils

Nils, maybe errors are about merge conflicts? In that case it is pulling from repository, but Your changes are conflicting other changes made and applied to integration branch in meantime. Conflicts are pain in the a** to resolve ;/. Not because it's hard to decide how to change code, but because there is no easy way to find and edit conflicting lines of code (at least without some sort of specialized graphical tool :).

Maybe try looking for graphical tool? Maybe there is some kind of a git plugin/add-on for Your favourite code editor?

Not sure why, but to get (c) working I needed to use "Your clone URL" not "Public clonr URL" i.e. the command was not:

git clone git://github.com/nickdunn/symphony-2.git

But:

git clone git@github.com:nickdunn/symphony-2.git