Guide to Using Git

From GlueXWiki
Revision as of 14:59, 1 August 2015 by Pmatt (Talk | contribs) (→‎Preface)

Jump to: navigation, search

Preface

  • This document is intended to contain the basic information needed for GlueX users and code developers to use git in the GlueX software environment. Many expert operations (e.g. making a tagged release) are excluded. Also, some shortcuts/features are skipped so as not to clutter this document.
  • In other words, this document should be considered to be the "Cliff Notes" of the full documentation (linked below).
  • The steps outlined here can be performed in the order as listed to set everything up properly and to use git.

References

First-time Setup

  • The GlueX repositories are hosted on GitHub. See Mark Ito's email about how to create an account on GitHub and how to join the "gluex" team on github: Link
  • The first time you use git on your machine, it is recommended that you setup the following information (optional).
    • The <myeditor> line tells git which editor to use to enter comments when making commits. Alternatively, you can set it via $EDITOR. 
git config --global user.name "<myname>"
git config --global user.email "<myemail>"
git config --global core.editor <myeditor>

Creating a local clone of the repository

The first thing you need to do is to create a clone of the master repository on your local machine. The "git clone" command pulls all of the code, branches, etc. for the entire history of the project into the current, local directory.

Setup Philosophy

  • In general, you probably want to have several separate copies of the repository built simultaneously on your machine. For example, you may want to have a program running off of a tagged release, and meanwhile develop code separately on a different branch.
  • The recommended way of doing this is to have a wholly separate clone of the repository for each tagged release, in addition to one (or multiple) clone(s) of the repository used for code development.
  • Each new code development project (bug fix, feature addition, etc.) should have it's own code development branch (if not it's own clone of the repository).
    • This way, you can switch between projects/branches as needed, keeping them clean and separated from each other, and merge them back to the "master" branch individually when they're ready.

Examples

To create clones of the master repositories into the directories <mydir>: 

# SIM-RECON
cd $GLUEX_TOP/sim-recon/
git clone https://github.com/jeffersonlab/sim-recon/ <mydir>

# HDDS
cd $GLUEX_TOP/hdds/
git clone https://github.com/jeffersonlab/hdds/ <mydir>

References

Creating & Switching Branches

  • In git, branches are simply pointers to different snapshots of the content of the git repository.
  • By default, the "master" branch is created on your local machine after performing "git clone," but it is not a special or unique branch. There is no inherent definition of a "trunk" in git like there is svn, just a series of branches.
  • However, for GlueX, we treat the remote, "origin," "master" branch of the sim-recon/hdds/etc. repositories (stored on Github) as the "trunk" from which we create tagged releases.
  • "Checking out" a branch replaces the local files/folders with those in the new, current branch. Checking out a different branch is not possible if you have uncommitted changes in your current branch.

Examples

To create the branch <mybranch> (whose content will be identical to the current branch): 

git branch <mybranch>

To show all of your branches, along with which branch you are currently using (marked by an asterisk (*)): 

git branch

To switch to the branch <mybranch> (this replaces the local files/folders of your current branch with those of the new branch): 

git checkout <mybranch>

References

Adding files and/or Committing changes

  • There are two cases where you might want to commit changes: New content and changes to existing content. In both cases, you must first "stage" the change with "git add," before committing it with "git commit."
    • Note that any changes made after "git add" but prior to "git commit" will NOT be committed; run "git add" again on the changed files in order to re-stage them for committing.
    • When you run "git commit" the text editor defined by the environment variable $EDITOR will be launched for you to add commit comments.
  • These operations add/commit the changes to your current, active branch.

Examples

To stage a file/folder for the next commit to the current branch (and/or add a new file): 

git add <myfile>

To commit all of the staged files/folders in the current folder to the current branch: 

git commit

To commit all changes to "tracked" files/folders in the directory to the current branch (bypassing the "add" staging: similar to "svn commit"): 

git commit -a

References

Terminology

  • Tracked/untracked files: Untracked files are files that have never been added to git (via git add). Tracked files are ones that have been previously added to git.

Removing Files

  • Use "git rm <myfile>" followed by "git commit" to remove files from the current git branch.

Examples

To remove the file/directory <myfile> from the current branch: 

git rm <myfile>
git commit

References

Merging and Deleting Branches

  • Once you finish the project/feature/bugfix for which you created your current branch, you can merge those changes back to the "master" branch by using the "git merge" command.
  • Since you've finished with this branch, you can then delete it using the "git branch" command.
  • For handling merging conflicts, see the "Basic Merge Conflicts" section of the git book: Link

Examples

To merge the changes committed to branch <my_work_branch> into the branch <my_master_branch>: 

git checkout <my_master_branch> # Switch to make the master branch active
git merge <my_work_branch> # Merge

To delete the branch <my_work_branch> 

git branch -d <my_work_branch>

References

Remote Repositories

  • The "origin" remote repository is the repository that you cloned when you initialized your setup with "git clone." You can rename this reference on your local machine, but it's not necessary. "origin" should typically be the <my_remote> in the examples below.

Examples

To list the remote repositories that your clone is connected to: 

git remote -v

To update your local repository with information from the remote repository <my_remote> (does not change any of your local branches): 

git fetch <my_remote>

To list all of the branches in the remote repository <my_remote> that your clone knows about (updated via "git fetch" above): 

git remote show <my_remote>
Retrieved from "https://halldweb1.jlab.org/wiki/index.php?title=Guide_to_Using_Git&oldid=69073"