Recommended Git Workflow - Test-More/test-more GitHub Wiki

You don't have to do it this way, but it makes working with remote repositories easier on you and merging your work easier on us.

We use the "Fork + Pull" model of development wherein you work in your own copy of the repository (the fork) and we pull your changes in.

If you get confused, let us know and we can help. Stack Overflow is another great place for getting git help. If working with git gets to be too frustrating, we will always accept normal patches. We'd rather have you submitting patches than fighting git.

Repository Setup

First, fork and clone https://github.com/schwern/test-more normally.
See http://help.github.com/fork-a-repo/ for instructions.

# Add schwern's repository as a remote called "upstream"
git remote add upstream git://github.com/schwern/test-more.git

# Fetch schwern's repository
git fetch upstream

# Set your Test-Builder1.5 to track upstream/Test-Builder1.5
# Not necessary for this example, but helpful.
git branch --set-upstream Test-Builder1.5 upstream/Test-Builder1.5

# Make sure your Test-Builder1.5 is up to date
# Also not strictly necessary, but helpful
git pull upstream

--set-upstream was added in git 1.7. If you're using an earlier git you'll have to set your branch config manually.

# Set your Test-Builder1.5 to track upstream/Test-Builder1.5
git config branch.Test-Builder1.5.remote upstream
git config branch.Test-Builder1.5.merge refs/heads/Test-Builder1.5

Feature branch management

For each issue you work on, do not work in the Test-Builder1.5 branch. Make your own branch for each issue. This will keep your work untangled and allow you to work on multiple issues at once.

# Branch off of the upstream Test-Builder1.5, not yours
git checkout -b issue/123 upstream/Test-Builder1.5

# You're now in a local feature branch tracking upstream/Test-Builder1.5
# Work normally, commit often
...edit test add commit...
...edit test add commit...

# When you commit, please mention the issue number in the commit message
# Like "For #123".

# Get updates from upstream
# --rebase explained below
# I have this aliased to "repull" in my .gitconfig
git pull --rebase

...fix conflicts...
...edit test add commit...
...edit test add commit...

# Get more updates
git pull --rebase

...fix conflicts...
...edit test add commit...
...DONE!

# One last check for updates
git pull --rebase

...fix conflicts...

# Run the whole test suite
prove -lr t

# Push your branch to Github
git push -u origin issue/123

Issue a pull request on Github.
See http://help.github.com/send-pull-requests/ for instructions. 
Remember to go to Branches and select your branch before trying to send the pull request.

Branching off upstream/Test-Builder1.5 instead of your Test-Builder1.5 means you can update in one step (git pull) instead of two (first pull from upstream to origin and then from origin to your branch).

If you're comfortable with it, I would recommend a rebase/pull (git pull --rebase)to update your branch with my changes rather than the normal merge/pull. This will provide a cleaner and easier to review history. If you're not comfortable, just use git pull and we'll cope with the extra merge points.

After the push

After you push and issue the pull request, you may want to do more work on the branch. Probably it will be reviewed and there will be some bits to fix. The process is very similar to the above, except you want to merge instead of rebase. Rebase will rewrite your commits and you won't be able to push normally.

# After you've pushed and issued a pull request.
# If you want to do more work...

...edit test add commit...
...edit test add commit...

# Get the updates from upstream
# It's important to *not* use --rebase
git pull

...fix conflicts...

# Run the whole test suite
prove -lr t

# Ready to submit more work
git push

That's it. The only difference is git pull instead of git pull --rebase.