GIT

From VISTA LAB WIKI

Revision as of 14:01, 12 August 2016 by Wandell (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

We store VISTASOFT and PDC project repositories on github.

The GIT model we have adopted for vistalab and scienstanford is this.

  • Obtain a github account. (They are free.)
  • To use software from a repository, clone it from github to your computer
  • Before editing, create a branch. (You can push the branch back to github, if you like).
  • When the edits are done, and if they are useful, issue a pull request at github. This is an email message asking others to check your edits and agree to merge your edits into the master branch

The vistlab github account and The scienlab github account include many public repositories. For example, the main visatsoft repository is there. Projects under development are there, but they are not public. These include projects on diffusion, fMRI modeling, and computational modeling.

Some lab members maintain additional personal repositories with related coding projects (Ariel Rokem, Jason Yeatman, and Brian Wandell).

This is a very clear book about git by Scott Chacon. It is worth your time as you get started.

Excellent summary of GIT commands.

Contents

Overview

Get a git account by going to github or go to directly get a free account. If you want an account where you can have a private repository - say you are developing code for a class - then you can make a request here.

Git and github can be used in two different modes: if you wish to use git from the command line, you will need to make sure that your computer runs git. You can also download and install the most recent version from here. Alternatively, there are a variety of gui tools you can use to interface with git and github, Github software download. The tortoisegit software seems pretty good.

Learning how to use git

The web has a lot of resources for getting started with git. You should probably try to understand what git is doing first. There are also a bunch of online tutorials you can go through.

A good cognitive map of that territory is provided by the git parable. Ariel thinks you should go read it. Seriously.

Git download

We recommend learning how to use git command lines to interact with the repository. You can download git for all major platforms.

The github folks have visual interfaces to git and to github-hosted repositories for some popular operating systems. GIT itself is then part of the distribution.

Download the github software. This will be a form that is specific to your operating system.

Create a github account

We are sharing the vistalab repositories via a github account.

To work with the vistalab repositories, get a (free) github account for yourself.

Working on Vistalab repositories

Clone the vistalab repository on your local machine

  • Go to a folder where you want to keep the code (for example, ~/matlab/git/)
  • Use the following command to clone your forked vistalab repository onto your local machine
git clone http://github.com/vistalab/vistasoft.git

Editing the code in your repository

  • When you want to make a change to the code, create a branch to make your changes
git branch [new branch name]
  • Move into your new branch
git checkout [new branch name]
  • Edit on your branch
  • Commit your changes to your branch

Sharing your branch and changes with others

  • To share the changes on your branch, push it to github where others can see it
git push origin [your branch name] 
  • You can now see your branch and all of your changes on github!
  • If you think the changes are ready to be integrated into the main distribution, issue a pull request.

Working with Git Day to Day

Each operating system has different tools and ways to add a repository. We describe our current experiences here.

Make a new repository

If you already have code you want to put in your repository, go to the root directory of the code. Type

git init

If you type

git status

It will announce what files are there but they will not yet be added. To add everything you can type

git add *

This will add everything recursively. To check try

git status

To commit these, you can type

git commit -a

starting your default text editor. To get around this, use

git commit -am"Your commit message goes here"

This completes making the local repository on your machine.

Go to your github web site and sign in. Then create a repository on the github, following the instructions provided here. When you visit the web-page of the newly-created repository, it will contain the complete constructions of adding your branch to github. After you have added it (the first time), you can easily push any new changes that you have committed with the next line.

git push origin [branch name]

Converting an SVN repository to a GIT repository

Without history

First, SVN export versioned items into a directory.

  • Create the repository on github.
  • Clone it to your local machine
  • Move the versioned items into the cloned repository
  • git push

Another way is this: Create the local repository and then push up to github. This is more complex because it forces you to name upstream, and so forth. I think this works, but I struggled with it.

  • Change into the exported directory and run
git init
  • Then execute
git remote add origin URL-of-GITHUB-REPOSITORY
git branch --set-upstream-to=origin/master master
git pull
git push

With history

To save the history, use svn2git. We don't do this much.

GIT hints

Git commands for users of SVN: http://git.or.cz/course/svn.html

Look at the bottom of this page for information about how to avoid typing your password every time you push or pull.

A good resource

Commit and add in a single line

Rather than git add XXX and git commit XXX you can use

git commit -a

To also type a comment use

git commit -am "YOUR COMMENT HERE"

Pushing a local branch to github

Suppose you created a local branch, myBranch, and you want to expose to others through your GitHub repository. You can push that branch into the github repository using the command

git push -u origin myBranch

It is useful to set a global default for how you push data to github. The recommended default for our lab is

git config --global push.default simple

This option pushes your local branch (but not others) to github. Thus, you can change thisBranch and thatBranch. But only the changes in thisBranch will be pushed. Furthermore, the push will only occur if the name of the branch you are tracking on github matches the name of your local branch. (It is possible for myBranch to track otherNameBranch on github). Ugh.

The list of options (instead of simple) are described on this page.

Track a github branch locally

Suppose there is a branch called camera on github. You don't have a local version. To get it

git branch --track localName origin/remoteName

For example, to track dev on github with a local branch also named dev, type

git branch --track dev origin/dev

Viewing the commit history

This is a nice way to set an alias to show commits

git config --global alias.hist 'log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short'

From this page

Get file from branch

Link

git checkout master               # first get back to master
git checkout experiment -- app.js # then copy the version of app.js 
                                  # from branch "experiment"

Override local changes with repository

Provided that the remote repository is origin, and that you're interested in master:

Get the origin and then

git fetch origin
git reset --hard origin/master

This tells to fetch the commits from the remote repository, and position your working copy to the tip of its master branch. All your local commits not in the remote will be gone.

Revisiting a previous commit

Use git checkout to set the files to a previous commit. For example, suppose you know the SHA number of a commit. Then

 git checkout SHA-NUMBER

will keep your repository in place but bring you back to the state at the time of that earlier commit. When you make this change, you will be told you are in a 'detached HEAD' state that lets you look around. To return to the HEAD, you can use git checkout <branchName>, or, I think git checkout HEAD.

There are related commands (reset and revert). But they do something more scary.

Stashing your work

Sometimes you are doing something and need to change to another branch. You aren't ready for a commitment. So, you want to stash your work. You can use

git stash

To see the list of things you have stashed you can use

git stash list

This shows you what has been stashed on all your branches. When you change back to the branch and want to get the stashed stuff back type

git stash apply

Revert a merge

Sometimes you merge and then want to undo it. This is straightforward if you have not yet pushed to the repository. In that case you can revert by the command

git revert commit_sha

This puts you back to the commit with the sha number commit_sha. You can see the different commit_sha values and their messages with the command

git log

If you have NOT pushed to github and you just want to go back 1 commit, you can use

git revert HEAD~1

See what you are about to push

If you want to see the differences between your local branch and the one on github, to understand what will happen if you execute a push, you can use

 git diff --stat [remote/branch]

For example,

 git diff --stat origin/master

Add a tag (label) to a commit

Label a commit (e.g., version 2.3)

git tag (shows the tags)
git tag -a v1.4 -m 'my version 1.4' (Adds a tag and a message for this tag)
From the book

Configure

git config --global user.name
git config --global core.editor

Delete a branch

 git branch -D branchName               % Local branch
 git push origin --delete branchName    % Remote branch

Show the origin and branches

Let's you know who is tracking what

git remote show origin


Tips and tricks

Add branch name to terminal prompt

Once you start having many different branches of your repo, you will want to avoid getting confused about which branch you are currently working on. One way to do that is to make your terminal "git aware", by entering the following lines in your bashrc:

 # Set the prompt to show the current git branch:
 function parse_git_branch {
   ref=$(git symbolic-ref HEAD 2> /dev/null) || return
   echo "("${ref#refs/heads/}")" 
 }
 PS1="\h:\W$RED \$(parse_git_branch)$NO_COLOR $"

Add global git account information

Git needs to recognize your name and email address to be able to access your online account.

If you do not specify them in the global configuration file they are configured automatically based on your username and hostname on the local computer.

You can set them explicitly as follows:

   git config --global user.name "Your Name"
   git config --global user.email you@example.com

After doing this, you may fix the identity used for this commit with:

   git commit --amend --reset-author
Personal tools