git less better

If you want to ask questions or answer them on github you'll need a github account - it's free. If you want to work on the Shoes internals (C, Obj-C, and Ruby) then you'll need three more things - a copy of the Shoes code, an invitation/role at the Shoes3 repo and you'll need the git program on your machine.

Prerequisites

Getting a Role

All you have to do is request an invitation. File a new issue or ask on the mailing list. No need for a long description of what you want to do or your background unless you'd like give that info as an introduction. Then respond to the email that you'll receive. That email could take a while to arrive - invitations are processed by hand.

Getting Git

The git program runs on your machine and communicates with github repo (short for repository). Getting the cmd line git on Windows may take some effort. [need an update here]

Getting a copy of Shoes

You have a choice to make: fork, clone, or download a zip. Do not download the zip. Fork is the most flexible but slightly harder to work with. Keep reading before making that choice.

How Shoes and Github like to work.

Branches

Shoes uses branches - that means you want to use branches too. The master branch is the one we use to build the Shoes releases that we distribute and people download and install. We strive for the master branch to alway be build-able for all platforms, anytime. Someone gets cranky when master is broken so there is a rule or best practice - don't push to master unless you issue a pull request or create a branch. It's hard to create a pull request from a forked repo. [info needed] [does a git clone only allow PR?]

It's best to create a branch on your machine, do your work and when you're ready, create a remote branch (aka tracking) at github and push your commits to that remote tracking branch. That way, Mr Cranky can review your changes, and eventually merge them into 'master'.

Create a branch and commit

$ git branch foobar did that work? git branch will list all the branches you have. git checkout foobar will switch you to the foobar branch. I hope you know that your branch should not be named foobar - pick a name you like that is not in use at the github repo - foobar is just for illustration purposes. Make your changes to the file in your foobar branch and commit them: git status will show the files that were modified and untracked and then you pick the files to be in your commit with git add README.md assuming you modified README.md.

Create a remote (tracking) branch

So branch 'foobar' on your machine is ready for a review by Mr Not-That-Really-Cranky. Create a remote branch by

$ git push -u origin foobar
Counting objects: 12, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 288 bytes | 0 bytes/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
To [email protected]:Shoes3/shoes3.git
 * [new branch]      foobar -> foobar
Branch foobar set up to track remote branch foobar from origin.

Point your web browser at the Mothership and look in the pull down for 'branches'. Do you see your branch? I sure hope so. Again, you'll replace 'foobar' in this example with the name of your branch.

Using your local branch with a remote

Just modify your local files and 'git add' them to your commit. Commit $ git commit and $ git push. Repeat as you like. If someone modifies your remote branch after your last push you'll get an error message when you push next. You'll have to $ git pull to get their changes and resolve the conflict. It happens.

Remove branches

Some people like a tidy git experience. Mr Cranky does, others - not so much. When foobar is merged into master or rejected, there is no reason for foobar on your machine or at the website, unless you want to keep working on it and pushing new commits to your remote branch. Eventually, you'll be done with your branch.

To remove the remote (tracking) branch - aka the branch at github: git push origin --delete foobar Point your browser back to the Mothership and reload the page - foobar is not in the drop down list of branches. Success!

To remove your local branch, you have to switch to your master branch first

$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
$ git branch -d foobar
error: The branch 'foobar' is not fully merged.
If you are sure you want to delete it, run 'git branch -D foobar'.
$ git branch -D foobar
Deleted branch foobar (was 1812bef).

In this example, Mr Cranky did not merge your commit to master or it was a bad idea on your part. Just get rid of my local branch damn it. That is when you use -D.

Deleting your copy of dead remotes

If you have forked Shoes3 then you might have a bunch of remote branches on your machine that don't really exist at the mother ship. You'll want to trim them down to what does exist. I, "Mr Cranky, but not really that cranky" can't test this because his branches are up to date. For example, you might have a local 'svg' branch that does not exist at the mother ship. Since the mother ship doesn't have a remote you can just delete your local branch as shown above.