Git Usage Guidelines

Git guideline are two sections down on this page!

SVN

If you are using SVN, see instructions here.

SSH Key (Optional to use)

If you need to use SSH public/private key for accessing a Git/SVN repo, see instructions here to generate your SSh public/private key. When you are ready to use, open your Git Bash or Git Shell (installed already in your system), and then "cd PATH_TO_LOCAL_DIR" where PATH_TO_LOCAL_DIR is the directory where you check out the Git/SVN repo. Then type in "svn co svn+ssh://XXXX@YY.illinois.edu/@ proposaldir" (replace this command with your real command). You will be prompted to enter the password for your local SSH private key: "Enter passphrase for key '/c/Users/USERNAME/.ssh/id_rsa':". Enter your password and then you are done in getting access!

Note that please double check your Windows OS => Control Panel => "Region and Language" => Administrative tab => Language for non-Unicode Programs section => Check whether "Current language for non-Unicode programs" is "English (United States)". If you set it to a different language such as "Chinese (Simplified, PRC)", your Git Bash or Git Shell will display strange characters when using SVN commands. You can type in "svn help" to check what you see on in the Git Bash or Git Shell command line window.

Note that you may get prompted to enter your passphrase for your private key every time you check out the SVN repo. See the instructions here for autorunning ssh-agent to allow you to enter your passphrase once when you start your Git Bash. If you are using Windows, here is a way: use Git Bash to "vi .profile" (you may learn somewhere on how to use vi, a Unix-style command, to create and edit a file content) to create a file named .profile under your home Git bash directory (e.g., C:\Users\taoxie). Note that the file manager/explorer may not allow you to create such ".profile" file in GUI. Then copy and paste the following contents as your .profile file content.

SSH_ENV=$HOME/.ssh/environment  function start_agent {      echo "Initialising new SSH agent..."      /usr/bin/ssh-agent | sed 's/^echo/#echo/' > ${SSH_ENV}      echo succeeded      chmod 600 ${SSH_ENV}      . ${SSH_ENV} > /dev/null      /usr/bin/ssh-add;}# Source SSH settings, if applicableif [ -f "${SSH_ENV}" ]; then      . ${SSH_ENV} > /dev/null      #ps ${SSH_AGENT_PID} doesn't work under cywgin      ps -ef | grep ${SSH_AGENT_PID} | grep ssh-agent$ > /dev/null || {          start_agent;      }else      start_agent;fi

Git

There is a free hosting site for git repositories from https://bitbucket.org/. Note that for a git repository there, you could configure it to be private and password-protected (rather than like other SVN repositories at Google Code, Codeplex..., which are publicly accessible). Please use your ncsu or illinois email address to sign, and then you could have unlimited number of users who could share read/write of your private repo; otherwise, you have only up to 5 users to share with (with a free account). If you already sign up with your other non-university address, please click "Manage Account", and then add your ncsu or illinois email and set it as the primary email to enjoy the unlimited sharing. Note that my email there for you to share your repository is taoxie@illinois.edu.

Please follow the above instructions for setting up SSH key without entering your password everytime doing Git commands. You can also see the instructions here for setting up SSH key for Git.

To access a Git repo, you need to install a Git client.

For Mac users, you may try one of the Git client tools mentioned here.

For Windows users, one strongly recommended Git client tool is TortoiseGit, which has nice integration with your Windows Explorer. If you want a standalone tool for Git client, one strongly recommended Git client tool is SmartGit, whose non-commercial license/usage is free. Other options are

free Eclipse Plugin EGit or free Git Extensions for Windows. Eclipse Plugin EGit is easy to use when you use Eclipse. Below we list instructions on using Git Extensions.

After you install Git Extensions, there are two tools: Git Bash and Git GUI. Here are some common instructions for using Git Bash: a convenient command line tool for you to use Git.

Step 0 (This step is needed only in your first time when creating the repository in your local machine) : Start Git Bash by clicking its icon. Then you see a command line window. In your command line, type in the local directory that you would like to check out a Git repository, such as

cd /d/taoxie/proposals/nsf12-ccf-floating/proposalgit

Then do the following to clone a remote git repository, e.g.,

    • git clone https://taoxie@bitbucket.org/zhendongsu/shf12m.git
        • You would be asked to type in your (user name and) password in the remote git repository
        • Then a local sub-directory "shf12m" is created as your local git repository

Step 1: Start Git Bash by clicking its icon. Then you see a command line window. In your command line, type in "cd" followed by the local directory that you already checked out your Git repository as in Step 0 earlier. Such command line could allow to switch to your local directory for the git repository, such as

cd /d/taoxie/proposals/nsf12-ccf-floating/proposalgit/shf12m

Step 2: In this local directory for the git repository, you need to make your current directory a Git repository and we simply run init by typing 

git init

Step 3: Then you could do the following for your local git repository (remember to change to your local directory for the git repository as in Step 1)

>> Add and Commit New Files: Initially, you may need to add some files to the repository following the steps below:

  • Substep a1: Copy files to your your local directory (e.g., cd /d/taoxie/proposals/nsf12-ccf-floating/proposalgit/shf12m)
  • Substep a2: Type in git add .. in your Git Bash command line window. If you have a subdirectory such as figs including copied-over files, also type in git add figs/.. If you would like to add specific files, type in instead git add FILENAME.EXTENSION
  • Substep a3: Type in git commit -m "Adding files for X reason"
  • Substep a4: Type in git push -u origin master

>> Get Updates from the Server, Change Local Files, and Commit Changes:

  • Substep b1: To get updates from the server, type in git pull
  • If you would like to change local files and commit changes, proceed with the following substeps:
  • Substep b2: Modify your local files
  • Substep b3: Type in git add FILENAME.EXTENSION to add each file that you modify
  • Substep b3: Type in git commit -m "Modifying files for X reason"
  • Substep b4: Type in git push -u origin master

Below are more details.

If you are using Mercurial for your BitBucket repo, SmartGit won't support it by default. You need to download and install Mercurial executable for your OS platform. Then you can find out the path to your installed Mercurial executable (e.g., "C:\Program Files\TortoiseHg" in Windows OS), then you open SmartGit and enter the path to your Mercurial executable in the Preferences: Edit -> Preferences -> Commands -> Executables -> Hg Executable. Then when you clone a repo, you will see an option of using Mercurial. However, SmartGit will not support Mercurial soon so you are suggested to use Git instead of Mercurial.

======================

Adding New Files

So we have a repository, but nothing in it. You can add files with the add command.

git add filename

To add everything in your directory try git add ..

Committing a Version

Now that we've added these files, we want them to actually be stored in the Git repository. We do this by committing them to the repository.

git commit -m "Adding files"

If you leave off the -m you will be put into an editor to write the message yourself.

Editing Files

When you've made changes to some files, you can run git status to see what will happen on commit. You'll notice a list of modified files, and a message:

no changes added to commit (use "git add" and/or "git commit -a")

So running git commit will do nothing unless you explicitly add files to the commit with git add. If you're looking for the commit command to automatically commit local modifications we use the -a flag.

git commit -a -m "Changed some files"

Or if you'd like to have only certain files, but still not run git add we pass specific files.

git commit -m "change some files" file1 file2

Do note that -a will not cause new files to be committed, only modified.

Publishing Your Repository

Here is the command line that you should use if you are using BitBucket:

git push -u origin master

If you want more complicated command lines when you are using a non-BitBucket system, see below:

If you haven't created a repository in your Git remote server, to put your repository on a server we'll start by making a "bare" repository, and upload it to a server.

cd /tmp git clone --bare ~/your/repo/path project.git scp -r project.git ssh://example.com/~/www/

Now if we have a couple of commits and want to push it up to that location:

git push ssh://example.com/~/www/project.git

If you dislike typing the URI each time we can take advantage that a cloned project remembers where it came from.

cd .. git clone ssh://example.com/~/www/project.git project

Now git push will push to the URI it was cloned from. You can do this manually by editing .git/config in your repository.

Get Upstream Changes

If you're already setup for push as above:

git pull

Will bring changes down and merge them in. To pull from a non-default location just specify the URI.

git pull http://git.example.com/project.git

More Than Five Minutes

Commits

You'll have noticed that Git thinks in "commits." These are uniquely identified by a hash. You can see the history and the hashes with git log. Each commit involves modifications, new files, and files being removed. add will put a file in a commit. git reset HEAD will remove everything from the planned commit, but not change files.

Remove

If you want to remove a file from the repository, removing it from future commits we use rm.

git rm file

Branching and Merging

Branches are done locally and are fast. To create a new branch we use the branch command.

git branch test

the branch command does not move us into the branch, just create one. So we use the checkout command to change branches.

git checkout test

The first branch, or main branch, is called "master."

git checkout master

While in your branch you can commit changes that will not be reflected in the master branch. When you're done, or want to push changes to master, switch back to master and use merge.

git checkout master git merge test

And if you're done with the branch you can delete with the branch command and pass the -d flag.

git branch -d test

Traveling Through Time

You can quickly very previous states of the repository using the checkout command again.

git checkout HASH

Uncommited changes will travel with you. Return to the preset with git checkout master as with normal branches. If you commit while in the past a branch is automatically created and your changes will have to be merged forward.

Sweeping Changes Under the Rug for Later

When moving between branches your local changes move with you. Sometimes you want to switch branches but not commit or take those changes with you. The Git command stash lets you put changes into a safe store.

git stash

You can retreive by passing an arguement of apply or pop.

git stash apply

The difference between apply and pop is simple. apply will take a stash state and apply it, but preserve that state in the stash. pop will take the stash state, apply it, and remove it from the stash. git stash clear empties the contents of the stash.

More info is at here.