Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

How to Develop Using Git

Stefano

Disclaimer: In writing this document, I don't claim to be an expert on Git. This information is a summary of what I have learnt as a first time user of Git. Hopefully this information is of use to a beginner like myself.

Introduction

As a first time user of Git, we need to understand what Git is.

Git is a Distributed Revision Control System. This means that we can create “stand alone” repositories, giving us complete control of our repository. Git contains mechanisms to allow us to obtain copies of other repositories, known as a clone and to share and synchronise our repositories with others. Once we obtain a repository from another user, the repository is now owned by us, but still maintains a link to the source repository known as origin

Git is generally command line driven, but tools for Windows have been created to make working with Git much easier.

Overview of Git

Git allows the creation of two repository types. These are:

Working Repository

  • The project folder contains a “.git” folder. This folder is constructed by Git and contains all the information needed to maintain the repository for our project.
  • The project folder contains all the files for our project we are currently working with.
  • Changes to any files are detected by Git, and can be saved to our local .git repository, known as a commit.
  • All committed changes can then be distributed to other linked repositories if they exist, as patches or direct saves known as: push
  • When a repository is cloned, we can obtain updates using: pull

Reference Repository

  • Git uses the project folder itself to maintain all the information needed for our project’s repository. This is known as a bare repository.
  • To identify a reference repository, by convention, the folder name is suffixed with “.git”
  • A reference repository, allows us to easily share our repository data with others.
  • Since we have no files to commit or push, updates to this repository type can only be obtained from another repository using: fetch
  • Given the correct access, other repositories can update our repository using: push
  • This repository type is small, and can therefore be used as a local backup, or centrally maintained on the internet for global shared access.

Sharing Repository Data

In order to create a clone of someone else’s repository, we need public read access to that repository. To make changes to any repository we need to have public write permissions. Repositories from others, are generally write protected, to prevent unauthorised changes.
So how would make changes to their repository?

GitHub

This is the reason for having an account with GitHub. GitHub provides a central location where reference repositories are kept. Using our favourite internet browser, we can access any public GitHub project. From our local GitHub account, we can clone and maintain our own reference repositories, giving others read access to our repositories.

GitHub Fork

GitHub has special features that allow us to clone another GitHub project. This is achieved with the GitHub command Fork. This command creates a reference clone of the original project, adds it to our own local GitHub area and maintains a link to the origin.

To answer the above question, we clone their reference repository to our local GitHub area using the command: Fork. We then create a clone of our clone to our local machine as a working repository. For this we require local tools to download the repositories. Now we have a local working repository, and our own public reference repository with write access.

Using our own local tools, we can now make changes to our project. When we are happy with the changes we can push our changes from our working repository to our reference repository on GitHub.

GitHub Pull Request

Because we do not have write access to the original project, any changes we have made to our clone, now also reside in our GitHub account. We now invite the original owner to have a copy of our changes using our GitHub clone. We tell GitHub to compare our changes to the original project, add any notes and explanations, and then we create a pull request.

The original author can now review your changes from your public repository. The original author can either accept or reject your changes. When changes are accepted, your changes are merged into their master repository. These changes can then be synchronised with everyone else's repository.

Git Rebase

An alternative to a pull request is to use rebase. To use this method, we first commit our work to a branch. More on working with branches below.

Local working with Git

Firstly, we need to install Git on our machine. This can be done by installing Git for Windows, or GitHub for Windows. Both have windows tools as well as a command line interface. Extra Git support can be added by using TortoiseGit. The installation of TortoiseGit will automatically locate and use Git supplied by Git for Windows, but can use Git supplied by GitHub for Windows by changing the general settings of git path.

GitHub For Windows

GitHub for Windows allows us to directly work with our GitHub account and provides us easy access to our data, as well as many other features. The primary features are:

  • Create local clones of our GitHub repositories.
  • View our project in our local working area.
  • Allows us to create new local projects, and then publish our new repository on GitHub.
  • Allows us to commit new project work into our local repository.
  • Allows us to synchronise our local and remote GitHub repositories.
  • View our project in our GitHub account. Useful to create Pull Requests.

Looking at our repository setting for our project will show us the origin link, as explained above.

Git For Windows

This provides similar functionality to TortoiseGit, with extra documentation on Git. The windows interface presents information similar to GitHub for Windows.

TortoiseGit

This is integrated directly into Windows Explorer, and allows us to perform the same functions as GitHub for Windows. Working with Git is all achieved via Windows instead of having to use the command line interface. TortoiseGit also allows working with multiple repositories.

Projects Containing Sub-Repositories

A sub-repository is a clone of another project which we incorporate into our project. Sub-repositories need to be initialised and updated separately. Cloning a project using GitHub for Windows, will automatically clone all the sub-repositories. Using TortoiseGit, we need to specifically request this by using the option: recursive. If this is not done, we will need to perform a submodule update in the Git Sync dialog.

Working with Multiple Repositories

In the case where we have a clone of someone else’s repository, in our GitHub account and our own local area, we still need to be able to obtain updates from the original repository. By convention our remote repository is known as origin, and the original repository is known as upstream.

When we make a clone from our GitHub account, GitHub for Windows will automatically add all the links to the other repositories. The repository settings will only show us origin.
(I am not sure how to update from upstream using GitHub for Windows.)

When doing the same using TortoiseGit, we need to adjust these associations ourselves. This is accessed by the project’s TortoiseGit remote settings. TortoiseGit will provide origin, but we need to add upstream ourselves. This now allows us to synchronise all repositories as follows: Using the Git Sync dialog, we pull changes from upstream then we perform a push to origin.

Working with Branches

The same repository can also contain branches and tags. Unlike SVN, what you initially see in the project folder is the .git repository and the files associated with the master branch. By convention, the master branch is created when the repository is created. When a new branch is created, we switch to the new branch.
Note: The files in the project folder are replaced with the files contained in the branch repository.

When we want to work with the master and another branch, we need to have separate working repositories which contain the files for that branch. The way I handle this situation is as follows:

  1. Create a fresh clone and then switch to the appropriate branch.
  2. Rename the project folder with the suffix: .branch
    Example: Develop branch of moneymanagerex becomes moneymanagerex.develop

TortoiseGit allows us to successfully work with this renamed project. Using GitHub for Windows (GFW) is a bit more difficult but can be achieved as follows:

  1. Removed the project from GFW’s local area. This only removes the association, and not the actual project.
  2. Using Windows Explorer, locate and drop the required project into GFW. This restores the correct association.

Combining work using Branches

Using a branch is especially useful for working in a team, because you would generally have write access to that repository. This is all good, except that at some point, we need a way to combine our work.

Although this can be done using the merge command, it will also add extra commits to fit it together.

In a team environment using branches, a better way to do this is to use the command rebase. We can use rebase to pull in the other team members work to our local branch. If there are errors, we can remove the last commit from our local repository. When all is well, we can publish our work by using push to our local branch and/or the master branch on GitHub as necessary. This has the effect of removing unnecessary commits as occurs with using the merge method.

Creating and Working with Patches

To users of SVN, this may seem strange, but it has definite advantages. Once we have modified our code, and are happy with the changes, we first need to commit our changes. Using TortoiseGit command: Create Serial Patch…; we have the option of selecting a range of commits. A patch is created for every commit in that range, which we can then apply or review in another repository.

Correcting Our Mistakes in a Git Repository

In the case where we have committed our change, to our local repository but have not made it public, we can simply remove this change by either:

  • Soft Option - Revert the change.
    This creates a commit which will undo the last commit.
  • Destructive Option - Reset to a previous commit.
    Via the Show Log, changes can be removed from the repository and working files with the command option: reset - hard

When we have pushed our change to our GitHub account, synchronising with upstream becomes difficult. This problem can be solved as follows:

  • On our local repository, use the destructive option command: reset - hard
    Best to use a commit point before the problem started.
  • Synchronise with upstream using the command: pull
  • Destroy the contents of the origin repository. (Our GitHub account repo)
    For this we need the command: push with force option on origin.

This will resynchronise all repositories to upstream master. (Assuming the master branch was used).
If another branch is used, the same can be done using that branch.

End of document.