Git

From OPS
Jump to: navigation, search

Return to Main page or CReSIS Toolbox Setup.

Git is a distributed version control system available at Git. This website includes links to documentation and tutorials. (We recommend reading the first three chapters of the Git Book through "Branching".) After going through a tutorial, web searches in combination with the documentation are often the best way to find answers for particular usage questions.

A project in git is called a repository and a repository contains a copy of all the versions of the project.

You can modify a repository independently of anyone else since your working directory of the repository is a local copy and does not affect anyone else. If you make changes that you want to share, then you will "commit" these changes and "push" them back to the main repository. This makes your changes available to everyone so that they can "pull" them into their own working directory. Typically you can only "push" to your own branch and the maintainers will "merge" your changes to the "master" branch in the repository.

Remember to "git pull" often to update your repository to get the latest changes from others. Also: every revision is saved by Git and you can very easily revert back to any previous revision in case a mistake is made. It is very difficult to permanently delete files from the repository so be careful to never commit sensitive information such as passwords.

Note that when you "git commit" this creates a new version in your local repository only. This new version will not be available to anyone else until you "git push" the changes to a repository that others have access to (e.g. https://git.cresis.ku.edu).

In the ct_docs repository, the File:CReSIS Git Tutorial.ppt covers some special uses of git.

Contents

Git Install

For windows this usually means Git for Windows and TortoiseGit installed. For mac, this usually means downloading and installing from https://git-scm.com/download/mac. For Linux, each of the major distributions have git: ubuntu "sudo apt-get install git-core", redhat "yum install git". There are many online resources for Git, but we have compiled the most frequently used commands on our local Git page.

Command Line Git

Branch

HEAD points to some commit on the active branch. You can move head around and it affects the default operation of all git commands.

Specific commits can be referenced by there 40-character SHA-1 hash. The whole SHA does not need to be used as long as you add enough to be unambiguous (sort of like tab completion of filenames). One useful shortcut is: HEAD~2 points to the commit two before the current one HEAD is pointing at.

Command Description
git branch -a List all branches and indicate the active branch. The active branch means that any new commits will be applied to that branch.
git branch BRANCH COMMIT Create a new branch called "BRANCH" which points to commit "COMMIT". If COMMIT is omitted, then "HEAD" is used. Note that this new branch is not checked out as the active branch.
git checkout BRANCH Change HEAD to point to most recent commit of BRANCH. Working directory will be updated to match this commit EXCEPT for changes that have been made. I.e. Any modified, added, and deleted files will remain in that state. To change to a branch that you do not have: git checkout -b BRANCH remotes/origin/BRANCH.
git checkout COMMIT Change the working directory and HEAD to match COMMIT.
git merge BRANCH Apply the changes from BRANCH that have not already been applied to the current branch. These changes are applied to the current working directory. Also, it automatically creates a new commit with the changes if there were no conflicts (option --no-commit stops the commit from happening automatically). If there are conflicts, each conflicted file must be corrected. Once this is done, git merge --continue must be run if successful and git merge --abort if not. NOTE: You should not merge if you have uncommitted changes to your working directory. First commit the changes and then merge.
git reset COMMIT Change HEAD to point to a particular commit. If --hard is used, then the working directory will be updated to match this commit.

Checkout Existing Branch

If you need to switch to an existing branch called BRANCH that is not in your repository yet:

  1. Create the new branch locally and check it out so it becomes the active branch: git checkout -b BRANCH remotes/origin/BRANCH
  2. Set the default up stream: git branch --set-upstream-to remotes/origin/BRANCH
  3. Verify it is setup: git branch -vv
  4. To update this branch: git pull

Create New Branch For Temporary Development

  1. Assume active branch is CURRENT (run git branch to get the active branch). Usually the current development branch is "master".
  2. Assume temporary branch is or is going to be called TEMP
  3. Optionally make changes to code
  4. git branch TEMP
  5. git checkout TEMP
  6. Optionally make changes to code
  7. Commit and push changes (see sections on git commit and git push), but push to a new up stream branch now:
    • git push -u origin TEMP
  8. Keep your temporary branch up to date with the CURRENT branch by merging changes to CURRENT into your new TEMP branch: git pull origin CURRENT
  9. Continue making changes to code and doing commits, merges, and pushes to the TEMP branch
  10. Use github to do a "pull request" when you want the owner of the CURRENT branch to merge your TEMP work back into the CURRENT branch. Make sure to merge the CURRENT branch into your TEMP branch first: git pull origin CURRENT
  11. Optional: When finished with the TEMP branch, merge it to the CURRENT branch and then optionally delete it:
    1. Make sure you have committed and pushed all your changes and ideally have no changes in your working directory
    2. git checkout CURRENT
    3. git pull origin TEMP
    4. git push
    5. git push --delete REMOTE TEMP (optional)
    6. git branch --delete TEMP (optional)

Clone

Examples:

git clone https://GITLAB_USERNAME@git.cresis.ku.edu/dangermo/cresis-toolbox.git

git clone https://GITLAB_USERNAME@git.cresis.ku.edu/dangermo/ct_params.git

git clone https://GITLAB_USERNAME@git.cresis.ku.edu/dangermo/ct_docs.git

Commit

Step 1: Files

Determine which files will be added to the commit. To add a file to the commit, you "stage" the file (also known as adding it to the "index"). All changes that are staged will be part of the commit when you run "git commit".

  • git diff will let you view the changes you have made to specific files
  • git status will let you view the changes you have made
  • git add will let you stage and unstage files.

git diff

Typically you would use git diff while you are adding files to be committed since it will then show only differences that you have not prepared for commit. However, if you want to check the differences after a file has been staged then run git diff HEAD (assuming you have not made modifications to the file after staging it).

Command Description
git diff Compare staged with working directory.
git diff --staged Compare HEAD (last commit) with staged.
git diff HEAD Compare HEAD to with working directory.
Diff tools

TortoiseGit is probably the best tool for Windows diff and merge. Meld is one of the best tools for other platforms. However, if meld is not available or you only have a terminal window, "gvim vimdiff" and "vimdiff" can be used and these are some of the basic commands. To control the behavior of vim, set the configuration in ~/.vimrc. See example cresis-toolbox/vim/vimrc file which includes example commands for setting the vimdiff color scheme which is useful when the default colors make text unreadable.

Command Description
]c advance to the next block with differences
[c reverse search for the previous block with differences
 :e Reload file modified outside vimdiff (:e! to override changes made in vimdiff).
 :diffupdate Rerun diff after making changes in vimdiff.
 :qa Close all files and quit vimdiff
 :w! Write current file
 :set formatoptions-=cro Turns off auto-comment insertion
 :setl noai nocin nosi inde= Turns off auto-indent
ctrl-w twice Switch between splits (i.e. between the two documents being differenced)
do (diff obtain) bring changes from the other file to the current file
dp (diff put) send changes from the current file to the other file
zo unfold/unhide text
zc refold/rehide text
zr unfold both files completely
zm fold both files completely

git status

Provides a quick overview of the status of the staged, unstaged modified, and untracked files.

[jpaden@i2 cresis-toolbox]$ git status
# On branch dev
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#	new file:   cresis-toolbox/processing/array.m
...
#	new file:   cresis-toolbox/utility/print_struct.m
#
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   cresis-toolbox/OPS-MATLAB/output/opsLoadLayers.m
...
#	modified:   cresis-toolbox/utility/nanstd.m

git add

From the command line, you can run one of the following:

  • git add FILENAME: stage
  • git reset FILENAME: unstage
  • git add -i Interactive interface to stage and unstage files from the index.

For the interactive interface, you choose a command, select which files you want to run the command on, and then run the command.

Command Description
"add untracked" Stages new files (called "untracked"). These are files that you have never committed before.
"revert" Unstages files.
"status" Prints the status of all files (does not include new files which are not staged).
"update" Stages files that are modified. These are files that you have committed before.
[jpaden@i2 cresis-toolbox]$ git add -i
           staged     unstaged path
  1:    unchanged        +7/-0 cresis-toolbox/OPS-MATLAB/output/opsLoadLayers.m
...
 33:       +56/-0      nothing cresis-toolbox/utility/print_struct.m

*** Commands ***
  1: status	  2: update	  3: revert	  4: add untracked
  5: patch	  6: diff	  7: quit	  8: help
What now> a
  1: cresis-toolbox/processing/array.m
...
  7: cresis-toolbox/processing/sar_task.m
Add untracked>> ?
Prompt help:
1          - select a single item
3-5        - select a range of items
2-3,6-9    - select multiple ranges
foo        - select item based on unique prefix
-...       - unselect specified items
*          - choose all items
           - (empty) finish selecting
* 1: cresis-toolbox/processing/array.m
...
* 7: cresis-toolbox/processing/sar_task.m
Add untracked>> 1-7
* 1: cresis-toolbox/processing/array.m
...
* 7: cresis-toolbox/processing/sar_task.m
Add untracked>> 
added 7 paths

*** Commands ***
  1: status	  2: update	  3: revert	  4: add untracked
  5: patch	  6: diff	  7: quit	  8: help

What now> s
           staged     unstaged path
  1:    unchanged        +7/-0 cresis-toolbox/OPS-MATLAB/output/opsLoadLayers.m
...
 39:    unchanged        +1/-1 cresis-toolbox/utility/nanstd.m
 40:       +56/-0      nothing cresis-toolbox/utility/print_struct.m

What now> u
           staged     unstaged path
  1:    unchanged        +7/-0 cresis-toolbox/OPS-MATLAB/output/opsLoadLayers.m
...
 31:    unchanged        +1/-1 cresis-toolbox/utility/nanstd.m
Update>> 31
           staged     unstaged path
  1:    unchanged        +7/-0 cresis-toolbox/OPS-MATLAB/output/opsLoadLayers.m
...
*31:    unchanged        +1/-1 cresis-toolbox/utility/nanstd.m
Update>> 
updated one path

*** Commands ***
  1: status	  2: update	  3: revert	  4: add untracked
  5: patch	  6: diff	  7: quit	  8: help
What now> s
           staged     unstaged path
  1:    unchanged        +7/-0 cresis-toolbox/OPS-MATLAB/output/opsLoadLayers.m
...
 39:        +1/-1      nothing cresis-toolbox/utility/nanstd.m
 40:       +56/-0      nothing cresis-toolbox/utility/print_struct.m

Step 2: Commit

git commit

Run git status one more time to verify that you have added the correct files for committing. Then run git commit to actually do the commit. When the editor opens, add a commit message that describes what you have done at the top of the message and then save and exit. Git will then create a commit (version) in your local repository.

git pull

Run git pull to pull (download) the latest source code and merge your changes with any changes that others have done. If there are remote changes, a new commit (version) will be generated which contains the merged files.

git push

Run git push to push (upload) your merged changes so that others can pull them.

Patch

Create a PATCHFILE file that contains the changes for a particular commit:

git format-patch -1 <sha>

Apply the PATCHFILE:

git apply --stat PATCHFILE # show stats
git apply --check PATCHFILE # check for error before applying
git am < PATCHFILE # apply the patch finally

Prune

To remove non-referenced objects. Remote branches from other developers that are merged/deleted still appear as local branches in: git branch -a

To safely report without removing:

  • git remote prune origin -n

To prune branches reported as: * [would prune] origin/BRANCH, run the above command without -n

Alternative: gc (garbage collection)

Pull

Push

Remote

To list remote repositories that are setup for this repository:

git remote -v

To change the URL for a remote:

git remote set-url REMOTE_NAME NEWURL

REMOTE_NAME is usually origin. For example:

git remote set-url origin https://cresis1@git.cresis.ku.edu/dangermo/ct_docs.git

To switch to github

If you only need to read from the CReSIS Github repository, run these commands from the cresis-toolbox repository directory:

git remote set-url origin https://github.com/CReSIS/cresis-toolbox.git
git pull

If you want to contribute/write to the CReSIS Github repository, send cresis_data@cresis.ku.edu your github account and request write access. In this case, add your username to the URL in the commands above as follows:

git remote set-url origin https://GITHUB_USERNAME@github.com/CReSIS/cresis-toolbox.git
git pull

For ct_docs and ct_params, move the original repositories to a backup location (e.g. "mv ct_docs archive_ct_docs") and then re-clone the repositories by running the following commands in the scripts directory:

# Read only access
git clone https://github.com/CReSIS/ct_docs.git
# Read/Write access
git clone https://GITHUB_USERNAME@github.com/CReSIS/ct_docs.git
# Read only access
git clone https://github.com/CReSIS/ct_params.git
# Read/Write access
git clone https://GITHUB_USERNAME@github.com/CReSIS/ct_params.git

Undo

Undo specific files

To change specific files that have not been committed (git commit) or staged (git add), run: git checkout -- FILEPATH

To change specific files back to their state in a particular commit: git checkout COMMIT -- FILEPATH Changes the working directory file FILEPATH to the version in COMMIT. If COMMIT is omitted, then "HEAD" is used. Note that this only changes the working directory. If you want the change to be permanent, then the change will need to be committed in the usual way.

Unstage all files

If you have staged files through "git add", this unstages the files:

git reset

This does not change the contents of any files, it just says remove all files from the list of files that you were planning to commit.

Undo all changes in working directory and unstage all files

Warning: This will undo all uncommitted changes in your working directory! git cannot recover these changes.

git reset --hard

Undo changes, but save them somewhere in case you need them later

git stash save MESSAGE Saves all working directory changes into the commit with message MESSAGE and then undoes all changes in the working directory. This is useful if you need to git pull, but you don't want to commit your local changes yet.

git stash list Lists all previously stashed commits. (git stash drop to remove specific entries.)

git stash pop Redoes previously stashed changes and removes them from stashed list. To pop a specific stash, git stash pop stash@{0}. Note that certain characters may need to be escaped so the shell won't act on them. For example, in Linux/Mac bash the curly brackets must be escaped:

git stash pop stash@\{0\}

git stash apply Redoes previously stashed changes, but keeps them on stashed list.

Undo whole commits which have been pushed

To change all files to a particular commit:

  1. cd to the root of the repository
  2. Change index and working directory to the particular commit that is good (note that because we specify a path ".", the HEAD will not be updated): git checkout -f COMMIT -- .
  3. Commit the files to the HEAD: git commit -a

Undo whole commits which have not been pushed

If commits have not been pushed, then it is safe to remove them locally: To remove all commits back to a particular commit: git reset --hard COMMIT. For example, to remove the last 2 commits: git reset --hard HEAD~2.

If commits have not been pushed, then another possibility is to fix the changes and amend to the last commit. Add the "--amend" flag to do this:

git commit --amend

ssh setup

# Create private and public keys, run the following and use default locations for keys:
ssh-keygen

# Go to git.cresis.ku.edu, login, user settings, add your new public ssh-key (~/.ssh/id_rsa.pub)

# May need to run this if you have not already:
eval $(ssh-agent)

# Make it so that you do not have to type in your password everytime (uses default location for keys):
ssh-add

# Set each repository to use the ssh authentication:
git remote set-url origin git@git.cresis.ku.edu:dangermo/cresis-toolbox.git

# Verify URLs are set
git remote -v

Tortoise Git

Branch

To checkout or switch to a different branch, choose "TortoiseGit->Switch/Checkout" and then select the branch (e.g. remotes/origin/new_branch). If this is the first time, then make sure "create new branch" is selected and name it to match the remote (so "new_branch" in this case).

Clone

  1. Open My Documents and create a new folder to contain the repository. The title of the folder is up to you.
  2. Right Click the folder and select Git Clone.
  3. In this new window enter the URL of the repository in the URL field and select OK.
  4. You will now be prompted for a username and password. Use your KU Online ID and Password.
  5. Once this is finished, close the window and the repository will be cloned within your folder.

Commit

Procedure for Updates:

  1. First git pull to get the latest changes to your development branch.
  2. Right-Click on the folder or file that you want to "Commit" and choose commit. Go through each of your changes in the file list and make sure all changes are what you want. You can select/deselect files from this list so that you only commit the ones that you want to. New files you created are not under version control and you have to right click and add them. Type in a message explaining what changes you have made and then click Commit or Okay.
  3. For Git, there is one more step: git push your changes. Commits only change your local copy of the repository. Push sends your commits to the main repository.

Pull

  1. Right Click your repository and select TortoiseGit > Pull.
  2. Select OK and enter your KU Online ID and Password.
  3. Your files are now up to date and ready to use.

Push

  1. Right Click your repository and select Git commit → "master"...
  2. In the text box enter a small comment identifying what you added or changed.
  3. Select OK and a new window will open.
  4. After the loading bar has finished, select the Push... button, press OK, and enter your KU Online ID and Password.
  5. The original repository will now be updated with your changes.

To switch to github

Right click on the repository folder and choose TortoiseGit->settings. Then choose the Git->Remote setting.

Select "origin" in the "Remote:" listbox. Change the URL and choose "Add New/Save".

For the URL, if you only need to read from the CReSIS Github repository,

https://github.com/CReSIS/cresis-toolbox.git

If you want to contribute/write to the CReSIS Github repository, send cresis_data@cresis.ku.edu your github account and request write access. In this case, add your username to the URL:

https://GITHUB_USERNAME@github.com/CReSIS/cresis-toolbox.git

For ct_docs and ct_params, move the original repositories to a backup location (e.g. change the folder name from ct_docs to archive_ct_docs) and then re-clone the repositories by right clicking in the scripts folder and choosing "Git Clone...". Set the URL and then press "OK":

# Read only access
https://github.com/CReSIS/ct_docs.git
# Read/Write access
https://GITHUB_USERNAME@github.com/CReSIS/ct_docs.git
# Read only access
https://github.com/CReSIS/ct_params.git
# Read/Write access
https://GITHUB_USERNAME@github.com/CReSIS/ct_params.git

Errors

Permission Denied

During git operations, the Windows file system may fail and print permission denied on directories that you have permission to access. This is common during large git operations such as "check out" and "merge". If it is a local file system, try restarting and doing the operation again. If it is on the network file system, you can try disconnecting the file share, restarting, and then reconnecting the file share. Or try from a different Windows machine.

Undo

Personal tools
Namespaces

Variants
Actions
Navigation
Tools