Git & GitHub
Page Contents
Git & GitHub#
Tutorials & Courses#
Note
Everyone working with git at NeuroPoly Lab: Please take 2+ hours of your time and learn how to use git before using it.
Official Git Documentation****
Name |
Type |
|---|---|
Tutorial |
|
Course |
|
Resource List |
|
Tutorial |
|
Course |
|
Course |
|
Tutorial |
|
Guide |
|
Guide |
|
Another great tutorial from Elizabeth DuPre, and a video here |
Course |
Guide |
|
Notes |
|
Guide |
|
Snapshot of all commands: http://www.cheat-sheets.org/saved-copy/git-cheat-sheet.pdf |
Notes |
Guide |
Installation#
Full instructions to install git here. We have a quick-start below:
sudo apt-get update
apt-get install git-all
Probably the easiest way to install on MacOSX is to install via XCode Command Line Tools. To check if git is installed:
git --version
Recommended install: Go to https://git-scm.com/download/win and the download will start automatically.
Contribute to a Project#
Basic steps are:
Fork the repository
Create a branch
Create new features while updating your branch from the Master
Submit a pull request
1. Fork the repository#
Log in to your GitHub account
Fork the project repository: click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub server.
In a Terminal window, go to the folder where you want to copy locally the code.
Clone the copy of the code to your local disk:
git clone git@github.com:your_login/project_name.git
If you get the following error message, create an SSH key:
Warning
Warning: Permanently added the RSA host key for IP address ‘XX.XX.XX.XX’ to the list of known hosts.
Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights and the repository exists.
Keep your branch up-to-date #
Once the clone is complete your repo will have a remote named “origin” that points to your fork on GitHub. Don’t let the name confuse you, this does not point to the original repo you forked from. To help you keep track of that repo you need to add another remote named “upstream”:
open a terminal, go to your repos and type:
git remote add upstream git://github.com/neuropoly/spinalcordtoolbox.git
git fetch upstream
Then (like “git pull” which is fetch + merge):
git merge upstream/master master
Or if you want, replace your local work on top of the fetched branch (like a “git pull –rebase”)
git rebase upstream/master
The –rebase option can be used to ensure a linear history by preventing unnecessary merge commits. Many developers prefer rebasing over merging, since it’s like saying, “I want to put my changes on top of what everybody else has done.”
4. Submit a Pull Request#
In a Terminal window, go to your git repository and type:
git push origin <BRANCH_NAME>
Log in to your Github account and go to your branch.
Click on “Pull request”. You will be sent to a page asking you to describe your modifications; you can give any title you want to your modifications (it doesn’t need to be the name of your branch).
Click on “Create a pull request”.
Now you need to wait that the person in charge of the project accepts your modifications; if this person finds problems in your code, you can still push new changes to your code and they will be added to your pull request.Edit
How to “merge” specific files from another branch #
The tool to use is “git checkout”:
git checkout source_branch <paths>...
You simply need to give “git checkout” the name of the feature branch and the paths to the specific files that we want to add to your master branch as follows:
$ git branch
* master
your_branch
$ git checkout your_branch <path_to_file_1> <path_to_file_2>...
$ git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# new file: <path_to_file_1>
# new file: <path_to_file_2>
# ...
$ git commit -m “explanation of the commit you are doing”
See the page git tip how to merge specific files from another branch for more details.
It is not possible to do this on SourceTree yet but an issue was opened on July 17th 2013 and is not closed yet. See the issue here.
See also the interesting page Smart branching with sourcetree and git flow about using Git flow to set the right strategy to gang up to contribute to your project.
Branches#
List remote branches#
git remote show origin
Track remote branch #
git remote update
git fetch
Checkout existing branch #
git checkout <branch_name>
If branch is not tracked (use ```git remote show origin``` to check if branch is listed), then use:
git fetch
If you still don’t see the branch listed, maybe your local git repository does not allow to fetch all branches on master. This happens if you clone with –depth=X. To check if this is the case, run:
git config --get remote.origin.fetch
If result is not “+refs/heads/*:refs/remotes/origin/*”, then update the remote.origin.fetch variable using:
git config --add remote.origin.fetch +refs/heads/*:refs/remotes/origin/*
Then, fetch:
git fetch
Now, all tracked branches should appear when running:
git remote show origin
Clone specific branch #
git clone -b <branch> <remote_repo> --depth 1
Create a branch #
git checkout -b <branch_name>
Push to remote #
git push -u
git push -u origin <branch_name> # push to specific branch
Remove a branch #
To remove a local branch
git branch -D <branch_name>
To remove a remote branch (if you know what you are doing!)
git push origin :<branch_name>
General usage #
Upload local repository for the first time #
First, create repository in github or bitbucket. Then, open a Terminal and run:
cd </path/to/your/project>
git init # initialize local git repos
git remote add origin https://USERNAME@URL_TO_REPOSITORY.git # link to remote repos
git add . # add every file under folder
git commit -m 'First commit'
git push -u origin master
Switch local repository to another branch #
git checkout <BRANCH_NAME>
Check which branch you are currently working on #
git branch
Create repository inside repository #
Use submodules:
Commits#
Term |
Description |
|---|---|
tracked file |
A tracked file is one that is part of the git version control. New files are untracked. |
untracked file |
An untracked file is one that is not part of the git version control. This includes new files, and any files that are specified to be untracked. For example, you may want to ignore files in the |
head |
The HEAD is the most recent snapshot, or commit. |
commit ID |
The commit ID is the 40-character alphanumeric identifier for a given commit. It is a hash, generated using SHA1 (cryptographic algorithm). |
Commit Messages#
Your commit must be accompanied by a message. For short, simple commits, this can be achieved via:
git commit -m "A message describing your commit"
However, you may want a longer, more descriptive message. To do this, just run:
git commit
This will open the default text editor, so that you can add a more descriptive message:
Commit message style guide for Git
The first line of a commit message serves as a summary. When displayed
on the web, it's often styled as a heading, and in emails, it's
typically used as the subject. As such, you should capitalize it and
omit any trailing punctuation. Aim for about 50 characters, give or
take, otherwise it may be painfully truncated in some contexts. Write
it, along with the rest of your message, in the imperative tense: "Fix
bug" and not "Fixed bug" or "Fixes bug". Consistent wording makes it
easier to mentally process a list of commits.
Oftentimes a subject by itself is sufficient. When it's not, add a
blank line (this is important) followed by one or more paragraphs hard
wrapped to 72 characters. Git is strongly opinionated that the author
is responsible for line breaks; if you omit them, command line tooling
will show it as one extremely long unwrapped line. Fortunately, most
text editors are capable of automating this.
:q
For more information on commit messages:
https://thoughtbot.com/blog/5-useful-tips-for-a-better-commit-message
https://github.com/neuropoly/spinalcordtoolbox/wiki/git_rules
Amending Commits#
If you made a mistake in your last commit, want to add something, or change the commit message, you can do so with the –amend flag:
git commit --amend
or
git commit --amend -m "New commit message"
This will add the changes you have added to the most recent commit. Make sure to only use this on local commits (i.e. commits that have not been pushed).
Rollbacks#
What if you made a commit that you need to revert? The revert command allows for you to fix this. It undoes your last commit by performing the inverse of everything in the last commit. That way, you still have all the correct history, and you will be able to still see the commit you reverted.
git revert HEAD
Alternatively, you can revert any commit using the commit ID:
git revert <COMMIT_ID>
Reset Commit#
If you want to go back to a previous commit and ignore the latest ones:
git reset --hard <COMMIT_NUMBER>
git push -f
Warning
WARNING: This will erase the latest commits!
HOW TO#
Configure git #
Before starting: configure git to identify you for each commit
Define the author name to be used for all commits by the current user.
git config --global user.name <YOUR_NAME>
Define the author email to be used for all commits by the current user.
git config --global alias.<alias-name> <git-command>
more info: http://www.atlassian.com/git/tutorial/git-basics#!configEdit
Show changed files between two commits #
git diff --name-only SHA1 SHA2
GIT - repository solution
gitk → cool stuff
Download: http://git-scm.com/download
Create a repository
Create folder:
mkdir my_repos.git
Go there:
cd my_repos.git
Copy repository to your station
git clone path_to_my_repos/my_repos.git
Rename directory
mv my_repos.git working_dir
N.B. Now you can copy/modify files in your working_dir
Commit changes locally
Add the files you want to your commit list, e.g.:
git add *.m
To add all modified (or deleted) files automatically, use:
git add -u
Commit the files
git commit -m 'enter description here'
N.B. You have to configure the commit params (do only once):
git config --global user.name 'Your Name'
git config --global user.email you@somedomain.com
Cancel a “git add”
git reset <file_name>
Look at the status of the files (tracked? Modified? Added?)
git status -s
Update changes to your repos
git push path_to_my_repos/my_repos.git master
example:
git push jcohen@door.nmr.mgh.harvard.edu:/autofs/cluster/connectome/git/process_data.git master
or:
git push -u origin master
Download changes from your repos
git pull
Removed tracked files
git rm "file name"
Download #
Download (server → local station) a repository for the first time
get address of repos, and type
git clone git@bitbucket.org:neuropoly/spinalcordtoolbox_dev.git
Reset your branch (revert your local commits) #
Using the Terminal:
git fetch
git reset --hard origin/master
Moving the current branch backward by N commits:
git reset --hard HEAD~N
Warning: This comment effectively removes the N snapshots created from the project history. Remember that this kind of reset should only be used on unpublished commits. Never perform the above operation if you’ve already pushed your commits to a shared repository.
Using Sourcetree:
assume you are on the branch example-fix. Find the commit with origin/example-fix, and right click on it. Select in the menu Reset example-fix to this commit and a dialog will appear. If don’t want to keep the changes, you can select Hard, else select Soft
Upload #
Upload (local –> server) a repository for the first time
Create repository in github
Clone repository to local station:
git clone https://github.com/xxx/xxx.git
Copy files to upload to repository
Update repository:
git add *
git commit -m "First commit"
git push -u origin master
Discard local changes (if pull doesn’t work) #
For a specific file use:
git checkout path/to/file/to/revert
For all unstaged files use:
git checkout -- .
TODO#
Ignore file mode #
If you cannot do a pull due to a change of file mode, you can ignore it:
git config core.fileMode false
#
Rebase#
Fix conflicts during rebasing#
When doing git rebase master to update a working branch, if there are any conflicts,Edit
Recover lost commits after rebase#
If rebasing caused commits to be lost, use git reflog to find the commits that were deleted, and then do a git reset –hard HEAD@{XX}, XX being the commit that comes right before the merge (the one that says: checkout: moving from master to YOUR_BRANCH)
#
GitHub #
Add SSH key #
Log in to your Github account and click on the button at the top right-hand corner called “Account settings”.
Click on “SSH keys in the left panel”.
Click on “Add SSH keys”.
Copy and paste the content of id_rsa.pub (open a Terminal and type:
more ~/.ssh/id_rsa.pub)
If you don’t have the file id_rsa.pub, do the following:
open a terminal
go to the folder
~/.ssh/and type:
ssh-keygen -t rsa -C your_email@example.com
port 22: Connection refused #
If you get this message, try this:
vim ~/.ssh/config
Add:
Host github.com
Hostname ssh.github.com
Port 443
Connection closed by remote host #
If you get this:
ssh_exchange_identification: Connection closed by remote host
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
this might be due to wifi connection that does not allow ssh. So you can temporarily switch to https:
# check which username/remote you are set on
git remote -v
# it should give:
# origin git@github.com:USERNAME/REPOSITORY.git (fetch)
# origin git@github.com:USERNAME/REPOSITORY.git (push)
# then set to https:
git remote set-url origin https://github.com/USERNAME/OTHERREPOSITORY.git
Search file name #
Go to search and type:
filename:my_file
Useful aliases#
Here are useful aliases that you could add to your ~/.bash_profile
alias gs="git status -s"
alias gc="git commit -a"
alias gp="git push"
alias gl="git log --pretty=oneline"
alias glg="git log --pretty=oneline --decorate --all --graph"
alias gd="git diff"
alias gb="git branch"
Git Software#
Pycharm #
Interactive squash, rebase: https://www.jetbrains.com/help/pycharm/edit-project-history.html
SourceTree #
Select default branches for pushing
Preferences > “Git” > Push branches: select “current”
Switch to another branch
On the left side bar you will find a BRANCHES header with a list of branches. You are currently on the branch in bold. To change branch, you simply double click on the branch you want to work on.
Update your branch
In case you have not used fork and you want to update your branch from master, do this:
git checkout <YOUR_BRANCH>
git rebase master