How to Contribute to ShapeWorks?
git for managing source code so changes can be integrated from multiple people. Here are some of the basics to check out the repository, make and share modifications, and keep track of all your changes along the way.
The ShapeWorks repositories are stored on GitHub.
If you want to contribute, first make sure you have a developer account.
Source and Branches
To clone the ShapeWorks source, use one of the following commands:
$ git clone https://github.com/SCIInstitute/ShapeWorks
To avoid having to type your password every time you refresh your source code, you can copy your public ssh key (found in ~/.ssh/id_rsa.pub) and add it to your GitHub account. Now you can use this version to clone the code:
$ git clone email@example.com:sciinstitute/ShapeWorks
[remote "origin"]in .git/config to
url = firstname.lastname@example.org:SCIInstitute/ShapeWorks. All git commands remain the same.
Now that you've cloned the source you can build ShapeWorks from source if you want.
View current state (branch and modifications, both staged and unstaged):
$ git status
View all branches:
$ git branch -a
Checkout a branch (or a tag or a specific commit):
$ git checkout <branchname>
Fetch changes for a specific branch from GitHub:
$ git fetch origin <branchname>
Fetch changes for all branches from GitHub:
$ git fetch --all
Merge the fetched changes to your current branch:
$ git merge origin/<branchname>
git merge origin/master
Shortcut to both fetch and merge upstream changes to the current branch:
$ git pull
Push a branch to GitHub:
$ git push origin <branchname>
Delete a branch (e.g., after a pull request has been completed and merged ):
$ git branch -d <branchname>
Force delete a branch whether or not it's been merged:
$ git branch -D <branchname>
Prune old branches that have been removed from GitHub (--dry-run will show you what will be pruned):
$ git remote prune origin [--dry-run]
Check the current status of your changes scheduled to be committed using:
$ git status
To commit your current changes to current local branch (first, use
git diff to ensure they are correct):
$ git diff $ git commit -m "description of changes"
This commits only the files specifically scheduled to be committed.
If you want all changes to be committed, use the
$ git commit -am "description of changes"
$ git add <filename>
To push your local changes for a given branch to GitHub, first use
git diff to ensure they are correct, then push to origin:
$ git diff origin/<branchname> <branchname> $ git push origin <branchname>
Never push directly to master
After pushing, submit a pull request (click the "New pull request" button on the main GitHub page) for your changes to be checked and merged to the master branch.
Logs and diffs
View the diff of the most recent commit:
$ git diff HEAD~1
View the log of a particular file (including moves/renames):
$ git log --follow -- <filename>
View the commit history for a file showing the detailed diffs for each commit:
$ git log -p <filename>
View the commit history of a file/dir when its name is the same as a branch:
$ git log -- <filename>
View the diff between one commit and its predecessor:
$ git diff <commit_SHA>~1..<commit_SHA>
View only the files that changes for a given range of commits:
$ git diff --name-only <SHA1> <SHA2>
Specific versions and releases can be identified using tags.
List current tags:
$ git tag --list
Show details for a specific tag (
--quiet hides the diffs):
$ git show <tagname> --quiet
By default, checking out a tag puts your repo into a 'detached head' state. Use the following command the first time you check out a tag or a specific commit to create a local branch with that name (this happens automatically when checking out branches):
$ git checkout origin/<tag> -b <tagname>
Create a new tag using the following:
$ git tag <tagname>
Tags must be explicitly pushed to GitHub. Push your new tag using:
$ git push origin <tagname>
Delete a tag using:
$ git tag delete <tagname> $ git push origin --delete <tagname>
There are many other things that can be done, such as mashing together commits, temporarily "stashing" and retrieving stashed changes, etc. Please add anything here that seems useful.
Stash your current changes (temporarily set them aside without committing):
$ git stash -m "what is being stashed"
Retrieve the stashed changes:
$ git stash pop
Modify the description of the most recent commit:
Only use this if the commit has not yet been pushed to GitHub.
$ git commit --amend