Skip to content

Latest commit

 

History

History
53 lines (34 loc) · 5.85 KB

git better · shoes:shoes3 Wiki.md

File metadata and controls

53 lines (34 loc) · 5.85 KB

Prerequisites

Create a free GitHub account. Install Git on your computer and configure it.

Forking the repository

On the page of the Shoes3 repository, click Fork. This will put a copy of the Shoes3 repository onto your web GitHub account.

Cloning the fork

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.)

Connecting your local repository to the official repository

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.


Workflow

Syncing your local clone with the official repository

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.

Branching

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.)

Cleaning (optional)

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.

Making a pull request (invite the maintainers to pull your changes)

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.


Resources

This guide was mostly based on these wonderful resources: