Joanne's Git Page

Git for sharing files and version control

Why git?

Want a simple way to back-up your projects and sync them on different machines (ie, laptop, ugrad server, etc.)?
Accidentally delete some key files you need to recover?
Need to share a codebase with a project team and work on it together, and avoid all the hassles of emailing or the limitations of Google Docs?
Need to look up where your codebase was two weeks ago, or roll back to that version because you took a wrong turn?
Need to make a temporary version of the project to try out a new approach, but you may not want to keep it?

Git is the answer to all the above needs. Git is a distributed version control system:

See a sketch of how this works.
You can have multiple clones (copies) of a repository on different machines/accounts by the same user or multiple users on a team.
Everyone on a team will have their own clone (copy) of a central repository which is called the remote in git terminology.
The central repository can be on any git machine, but we recommend using Bitbucket for repositories: they will have the master version of the files.
You will have a local version of the repository on your computer.
You must add files to the "staging area" before you can commit them to make them part of the local clone.
You can make commits to the local repository on your computer, creating a new version of all the files that had been added to the staging area.
In order for this new local version to be shared with other clones, you need to push it to the remote repository.
While you often want to commit all of your changes, you can commmit only changes to particular files. You can also delay pushing commits until you want your team-mates to see your changes.
If you want to update a local clone to the most recent pushes of your team-mates, you must pull the changes from the remote repository.
Your local copy of the repository is a staging area: you make some changes there, and then wrap them up in a commit with a message as to why you think the changes you made locally will be useful for other people. Lastly you push when ready to share with others.

Setting up Bitbucket

There are many options for hosting your central repository; we are recommending Bitbucket since it is free and private.

Go to to Bitbucket and create a free personal account.
To create a shared team code repository, one team member should go to the Team menu and make a new team. Invite your team members to join by entering their emails, and set them as administrators.
Go to Teams -> YourProjectTeam. Click "Create a Repository", give it a meaningful name.
In addition to team repositories, you can create your own personal repositories. Consider using git for other classes: its backing up your code for you and saving previous versions.
Make your repositories with coursework private so other people on the web can't publicly search your code.

Using git@Bitbucket on your machine

First, navigate in BitBucket to a repository you have created.
Now you will see Bitbucket is giving you two options to use to connect your local copy to it: SourceTree and the Unix shell.
- Sourcetree is a GUI-based program that works on Win/Mac. Download the application and hit the Clone button on the Bitbucket webpage to set up your local copy of this repository and view it within SourceTree.
- For Linux or Mac you can just use the command line version of git. You need the XCode command line tools installed for the Mac version to work.
- XCode has internal support for git from the "Source Control" menu
- The rest of this document will cover the command line version; the GUI tools have the same command names on the buttons so its largely self-explanatory; read the on-line help if you are stuck.
If you click on the "I'm starting from scratch" option it will give you the command line sequence needed to set up your local version. Type them in.
When you run the line git push -u origin master you will need to enter the password for your Bitbucket account at the prompt. (You can set up an ssh key if you want to avoid doing this every time - see the BitBucket tutorial for help on this.) Note you need to add a file before the commit/push will work.
From here on you can just use standard git commands to add files to the staging area, commit your changes, push them to your teammates, pull changes made by your teammates, etc. See the following section for details.

Using git from the unix command-line

Before using git, you need to tell it who you are. You should only have to do this once on each account that you will use to store local clones. On some systems, you may get a warning if you fail to do this; on others, it may be an outright error that prevents you from commiting your changes. To fix this, use the following two commands, substituting your own name and e-mail address for the placeholders:

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

After this, you can use the following git commands to manipulate your repository. Note you need to be within the directory tree of your project repository for these commands to work. (See below for creating a repository by initializing an existing project directory.)

Add a file to the current revision: git add newfile.c
- You must do this every time you add a new file or change a file and want to commit the changes
- Or, add the -a option to git commit and it will automatically add all the files that changed since your last revision. It won't add new files, only changed files.
To commit your current snapshot as a revision: git commit -m "Just started writing newfile.c"
- The message in quotes should briefly describe what you changed, for your teammates.
- Now you can always come back to this exact point.
- You probably want to add the -a option as well: git commit -a -m "changed output routine" -- it will automatically commit all files changed.
- A common error you will get on commit is error: failed to push some refs to 'https://me@bitbucket.org/myteam44/myrepo44.git': this means you need to first git pull changes by your team-mates before committing. It only happens if a team-mate changed a file you also changed.
To push your local commit changes to remote (Bitbucket for us): git push.
- Note that commit alone will not let your teammates see your changes, you need to commit then push.
- For the initial push to a remote, you probably want to say git push -u origin master - this pushes your (local) master (main) branch to origin, the remote server. Subsequent pushes will by default go to the same branch and remote so you can leave origin master off.
- If you overlapped on a line with one of your teammates you may have gotten a CONFLICT error message; see Resolving Conflicts below on how to deal with that.
To pull the last commit from your remote, getting you updated with what your teammates have been pushing: git pull. You could get a CONFLICT here, see Resolving Conflicts below on how to deal with that.
To set the master copy of your local repo to be at a remote address: git remote add origin https://blah...blah (the initial BitBucket setup instructions include this)
To replace one file with the version from the last commit: git checkout thatfileyoujustscrewedup
To list the status of all files git status - shows whether git is tracking them and if there is a change not yet commmitted to that file.
To see the changes you made since the last commit, you can type git diff
See the commit messages of your teammates: git log
To see what remote repository if any your local verion is hooked to: git remote (replies origin usually if hooked to one remote)
To see what if any branches you are on, type git branch -a. It probably will reply only
```
* master
  remotes/origin/master
```
which means you are on the master branch and that is in fact the only branch, but if there are other branches you will see them.
If you want auto-completion for git commands, there's a bash-completion script that you can get from https://raw.githubusercontent.com/git/git/master/contrib/completion/git-completion.bash. Download it, put it in your homedir, and then then add the line "source $HOME/git-completion.bash" to the .bashrc file in your homedir.

Other ways to set up repositories

To create a completely new local repository: type git init from inside the (likely new) directory where you want your repository to be. It creates a hidden .git folder, use ls -a to show it.
If you want a copy of a remote repository, you can just clone it without doing git init. Go to the directory in which you want the repository to appear (as a subdirectory) and type git clone https://bitbucket.org/username/myrepo.git (filling in the appropriate information on your repo)
You can also clone another repository from the filesystem: git clone /home/fr34/code/thisrepo/

Resolving Conflicts

What if two team members accidentally overlap on a change to a file? Note that changes to different lines of the same file will automatically be merged, so the only serious conflicts happen when one person commits a change to a line where a previous commit had changed.

Let's try changing the same line from different versions of the repositories: One person wants it to put "Goodbye World!" in myfile.txt, the other wants to say "Howdy, world!"
Suppose Howdy makes the commit first and pushes. Now Goodbye changes the same line. Goodbye's commit will go through, but upon push Goodbye will get something like CONFLICT (content): Merge conflict in myfile.txt
Looking at myfile.txt now, Goodbye will see something like
```
<<<<<<< HEAD
Howdy, world!
=======
Goodbye World!
>>>>>>> c0ebf4a3d93ee7288c6c6f216e69e7b019a1f27f
```
The <<<<<< through ======== lines are Howdy's, and the ======= to >>>>>>> are Goodbye's lines. These lines are around each place there is a conflict, make sure to look through the whole file.
Goodbye must resolve the conflict (e.g. let Howdy win and delete all but the Howdy line) index and then commit -a and push it to get the remote repository back in sync.
Any time you get a conflict you should work quickly to resolve it, as you can no longer commit or pull any changes until the conflict is resolved!
Moral: commit early and commit often to avoid such conflicts!
There are other fancier ways to resolve conflicts, the above describes the simplest approach.

Repository etiquette

You should make repository-using as easy as possible for the other people you're working with by only pushing code that compiles. It is also good practice to agree to a common coding style and only push code that has been style checked.

Git resources

The above covers only the most basic git features. You can also branch off a new version, just fetch changes without also merging explictly, rebase your changes over the remote changes, merge branches, stash a particular state, tag a commit with a label to find it later, etc. Ouch, I'm getting a headache from all these options!

Git - the simple guide is a good first overview
Git HowTo is a brief tutorial (guided tour)
Openhatch has another nice basic tutorial
Git tutorial by Lars Vogel begins with a very good overview of distributed version control and then covers many advanced features you likely won't need.
Try github walks you through the basics
git-scm.com has the official documentation and reference.