Using Git

Credit to https://github.com/pandas-dev/pandas/wiki/Using-Git since this is largely a copy of that.

For a well-done graphical introduction to Git, check this out:

http://pcottle.github.io/learnGitBranching/

This online book is also a good read

https://git-scm.com/book/en/v2/Getting-Started-Git-Basics

Create a fork and a local clone

You will need your own fork to work on the code. Go to the https://github.com/matthewgilbert/pdblp and hit the Fork button (top-right). The repository is forked under your account. Then, move to your account page and forked repository. You can clone your fork to your machine using URL displayed in SSH clone url on right. Note that URL must include your account name rather than matthewgilbert in below example:

git clone [email protected]:matthewgilbert/pdblp.git

add the pdblp remote repository to your fork and name it upstream

git remote add upstream git://github.com/matthewgilbert/pdblp

pull in the latest upstream changes without merging

git fetch upstream master

fetch changes from upstream and rebase off of latest upstream/master changes

git fetch upstream
git rebase upstream/master

fetch and then rebase interactively to squash, reword, fix, otherwise change some commits

git fetch upstream
git rebase --interactive upstream/master

This tip allows you to rebase relative to upstream/master which allows you to do squash commits from the point at which your fork diverged from pdblp upstream. This can also be done with

git rebase -i HEAD~#

where # is the number of previous commits to combine.

Pushing your changes and create a Pull Request (PR)

Push your commits to your own fork:

git push origin

To create a PR from there, see https://help.github.com/articles/creating-a-pull-request

To push subsequent commits to the remote repository from that branch use:

git push -f 

working on top of a branch that might be rebased

NOTE: This only applies if you are working on a branch other than master, which could be rebased by its current owner. If you're working off of a topic branch that might be rebased by others, you might want to keep closer track of where you started and the end of your commits so you can rebase painlessly.

When you checkout the branch initially, tag it as a base commit, e.g. (assuming upstream is a remote):

git checkout upstream/some-branch
# tag base of branch
git tag some-branch_base some-branch
git checkout -b my-working-branch

Then, when you want to put your commits on top of the updated branch (whether rebased or not), you can do:

git fetch upstream # update remote
git checkout upstream/some-branch # results in detached HEAD
# put your commits on top
git cherry-pick some-branch_base..my-working-branch
# delete previous branch and put your changes into the new branch
git branch -D my-working-branch
git checkout -b my-working-branch
# update the tag to refer to the new base
git tag -d some-branch_base
git tag some-branch_base some-branch

Making your git life easier when hacking on pdblp

list your global git config values

git config --list --global

don't clobber file permissions

git config --global core.filemode false

keep the line endings the same as the input file, i.e., don't convert them to your platform

git config --global core.autocrlf input