Development Using Git GUI

From Metro Studios Knowledgebase

Jump to: navigation, search


[edit] Setting Up

We use the msysgit "Git for Windows" package available off of Google code - msysGit Installation Instructions, msysGit Downloads.

The setup will ask you how you want to check in and check out assets in regards to new line characters. The best way to handle this is to check-out everything with Windows style new lines, and check-in with UNIX style new lines. Since all of our hosting is *nix based this practice helps keep our source cleaner.

[edit] Identifying Yourself

Once Git is installed, you will need to configure the name and email settings so Git can track each user's changes to a project. These configuration values can be set using the Git Bash shell and the Git config command. Set your name:

git config --global "James Smith"

And your e-mail address:

git config --global "[email protected]"

[edit] Cloning Remote Projects

On opening Git GUI you will be given an option for "Clone Existing Repository". Click on this and you will see a window similar to the following. Alternatively you can go to "Repository" > "Clone Existing Repository" from the window's menu bar.

The two fields here are the "Source Location" which is where we will be referencing the target repository that we wish to clone, and "Target Directory" where we will define where our new repository will be built:


For any cloning use the "Full Copy" clone type even if it is a local clone.

Once you click the "Clone" button it will ask you for credentials and attempt to clone the "Source Location" repository. When this is finished you will be able to begin working with your site files/assets locally (example: D:/Projects/Boost/repo/).

[edit] Constructing SSH Strings

This is the formatting for the SSH string that Git GUI uses for cloning remote projects via SFTP over SSH:


An example of this for a standard development domain would be:


[edit] Local Development/Committing

[edit] Rescan/Staging

Once you have made some changes to a file it is ready to start scanning for changes and staging your edits.

The first step is to click "Rescan" from within the main Git GUI window:

Git GUI tut rescan.png

As you can see I've added and removed lines from this document which has caused the document to show up in the "Unstaged Changes" list. This list will show you all modified files since your last commit when you "Rescan" your working directory.

By clicking on the "Stage Changed" button in the main window you will stage all of your changed files and they will move from the "Unstaged Changes" to the "Staged Changes (Will Commit)" list. This only will stage changed files (not new files, or deletions) so you will have to stage those manually by selecting the files from the "Unstaged Changes" list and either using "Commit" > "Stage To Commit" from the window's menu bar or using the keyboard shortcut "Ctrl-T".

[edit] Committing

Once there are files in the "Staged Changes" list you're ready to make a commit. A commit is more or less just a checkpoint in development. Once you are finished with a specific edit, deletion, or addition to your code it is best practice to document that. Writing a good commit message is a must.

To write a commit message type it into the "Commit Message:" box at the bottom of the screen and hit the "Commit" button. This will commit your programmatic change to your local repository (but not push the change live) and give you a point in which you can reference and roll back to in the repository's history.

Below is an example of a staged change and a well written commit message that is ready to be committed:

Git gui tut commit message.png

Once you commit you will see the "Staged Changes (Will Commit)" and the "Commit Message:" areas reset and the status message at the bottom of the screen should say "Created Commit" followed by a hash and your commit message.

[edit] Atomic Committing Principal

A commit should be rationalized as one logical unit of updates to code. Run-on commits that end up with messages like "Required things out, added contact form, moved debug template, added deny from all .htaccess" are terrible. All of those updates to the code are relatively unrelated and make any sort of rollback a headache - split them out. Though it creates many commits the messages will be short, concise, searchable, and readable.

[edit] Staggered Committing

When committing you have the option of using the staging area to stagger your commits, or only commit certain files at a time. You can do this by using the "Commit" > "Stage to Commit" option from the menu bar or selecting individual files and using the keyboard shortcut Ctrl + T.

This especially helps to maintain atomic committing during large code updates/pushes.

[edit] Writing Good Commit Messages

We use commit messages for three purposes:

Remember this when you're writing BS commit messages (we all do it/will do it) and try as best you can to maintain best practices when it comes our documentation.



[edit] Pushing/Fetching Changes

[edit] Pushing

In order to push your code out to the development or live areas (specifically the virtual host’s /httpdocs.git bare repository, then automatically to the /httpdocs/ document root) you must push the changes you’ve made and committed locally.

This is done by clicking the "Push" button at the bottom of the main Git GUI interface. This will bring up a window that has a "Source Branch" and a "Destination Repository". The source branch will almost always be "Master" and the destination repository will almost always be "Remote: origin".


You will not need to edit anymore of the parameters shown on this interface.

Once you have verified that there is a source branch selected (master) and a destination repository specified (remote: origin) then click "Push" to push your local changes to the remote bare repository.

If the push was successful a notification window similar to the following will appear:


If there was a conflict (two branches of code must be merged together) then you will see a notification window similar to this:


If this happens this means that someone has pushed their branch onto the bare repository and you must "fetch" their changes and merge them into your branch before pushing your branch.

[edit] Fetching

To fetch code changes from the remote bare repository we will be fetching from the origin repository that we originally cloned our branch off of.

To do this we will need to click on the "Remote" menu item and select "Fetch from" and then "origin":


This will pull down the current branch from the remote bare repository as "origin/master", which is the master branch of the repository will be represented locally at all times.

If this was successful a notification window similar to the following will appear depicting the "master" remote repository getting fetched (->) to the "origin/master" repository locally:


Once you have fetched the origin/master branch you will have to merge it with your local repository.

[edit] Local Merging and Handling Conflicts

[edit] Local Merging

After you have fetched changes from the remote repository, you will need to merge those changes with your local working copy. This can be done using the Merge > Local Merge... function in Git GUI:


When you access this function you will be presented with a dialog where you can specify the options for your merge:


In nearly all cases you will be merging the "origin/master" tracking branch with your local working copy as shown above. This will pull the changes from the remote repository into your working copy. Press the Merge button to complete the local merge.

If Git is able to merge the changes automatically, you will receive a success message like the following:


[edit] Merge Conflicts

If a file has been modified in a way that prevents Git from being able to automatically merge the changes, you will receive a conflict notice when you try to do a local merge:


This generally happens when another user has modified the same lines of the file as you have. In this case you will have to manually edit the file to resolve the conflict. When Git notices a conflict, it will add markup to the file indicating where that conflict occurs:


In the screenshot above the conflicting lines are displayed between the "<<<<<<< HEAD" and ">>>>>>> origin/master" markup that Git has added to the file. The lines between "<<<<<<< HEAD" and "=======" are the contents of your local working copy, and the lines between "======" and ">>>>>>> origin/master" are the contents of the file in the remote repository.

At this point you will need to decide how to handle the conflict. It may be as simple as deciding to use one section or the other, or you may need to manually merge the lines together. Consult with the other users working on the project if necessary.

Once you have decided how to resolve the conflict, make the changes in your local copy of index.php that has been marked up by Git. In the example above, assume that the decision was made to use the HEAD contents. That would mean the file content changes from this:

  <<<<<<< HEAD
  <title>This Title is Different</title>
  <title>Change TO The Title</title>
  >>>>>>> origin/master
  <meta http-equiv="...

To this:

  <title>This Title is Different</title>
  <meta http-equiv="...

Now that the conflict has been resolved, you can stage, commit and push as you normally would.

[edit] Additional

[edit] Boost

[edit] Administrative Articles

Personal tools
Wiki Navigation