Create a free GitHub account. Install Git on your computer and configure it.
On the page of the Shoes3 repository, click Fork. This will put a copy of the Shoes3 repository onto your web GitHub account.
In order to edit the fork on your computer, you need to clone it. On the page of your forked repository, click Clone. This shows the URL you need to give to git. (If you have configured GitHub with SSH, you should rather use the URL you get with the link Use SSH.) Using the command line, go to the directory where you want the repository folder, and type $ git clone URL
. (You can tell Git how to name the repository folder: $ git clone URL FOLDER
.)
In order to get updates from the official Shoes3 repository, you need first to add it as a remote. You can check your current remotes: $ git remote -v
. Right now, you should only have one remote, named origin
: your GitHub fork. To add the official repository as a remote named upstream
, type $ git remote add upstream URL
. (You can get the URL from the official page of the Shoes3 repository with the Clone button.) You can check again your list of remotes: $ git remote -v
.
Go to your local master
branch: $ git checkout master
. Assuming you named the official repository upstream
, integrate the changes of the official repository's master
branch into your branch: $ git pull upstream master
. You can use $ git log
to see the latest commits.
You can list your branches with $ git branch
If you want details: $ git branch -v
or $ git branch -vv
.
Create a branch named testing
based on your master
branch: $ git checkout -b testing master
. (If you omit the last argument, Git may base the new local testing
branch on a testing
branch of your GitHub fork if there is already such a branch there. Here, we prefer to base our new branch on the local master
branch, because we just updated that branch at the previous step.)
Make your changes to the code. You can check your changes with $ git status
and $ git diff
. Mark any file you want to commit: $ git add FILE
. Save the changes to the branch: $ git commit
.
If you made commits you dislike and which you did not publish online, you can make the branch come back to a past commit:$ git reset COMMIT_ID
. (You can get commit IDs with $ git branch -v
and $ git log
.)
Once you are satisfied with your committed changes, you may want to create a specific branch for your pull request: $ git checkout -b patch-1 testing
. One reason for doing so is that you can have only one open pull request by branch. Another reason is that if you make the decision to rebase (as explained below), doing so on a new branch allows you to come back to the testing
branch in case you dislike the result.
To simplify the commit history of that new patch-1
branch (to make it easier for maintainers to understand your changes), you can type $ git rebase -i BASE_BRANCH
, which allows you to manually omit commits, reorder them, change their description, or squash (combine) them into a single commit. The command uses BASE_BRANCH
as the new base for these commits, so it makes sense in our case to use master
as the base branch. (As a rule of thumb, never rebase a branch which is already public. Here, it's ok because patch-1
is a branch which is only on your private local repository, assuming you created that branch there and did not push it to any repository.)
If you are unhappy with your patch-1
branch, you can still come back to the testing
branch and delete the patch-1
branch: $ git checkout testing; git branch -d patch-1
.
If you are happy with the patch-1
branch, you can remove the testing
branch: $ git branch -d testing
.
Update your GitHub fork with the branch you want to share: $ git push origin BRANCH_TO_SHARE
. If there is an error due to a branch which was already on your GitHub repository, you can pick a new branch name and run $ git push origin BRANCH_TO_SHARE:NEW_BRANCH
to create on your GitHub fork a branch reflecting the local branch you want to share.
On your GitHub fork webpage, create a pull request. As the base, choose the official repository (shoes/shoes3) and the master
branch. As the head, choose your fork and the testing
branch.
Even once a pull request for a branch is open, you can still commit to that branch.
When the pull request for a branch is closed, GitHub invites you to delete the branch. If you delete it, GitHub allows you to restore it. Either way, the discussion board remains open.
This guide was mostly based on these wonderful resources: