Working with Git and TortoiseGit in Windows

In this topic we assume that Git and TortoiseGit have been installed.

Obtaining a Project Repository

To obtain an established project such as moneymanagerex we would do the following:

1. Create a folder that will hold the Git project
   • example: c:\mmex
2. Selecting this folder within Windows File Explorer, use the command: Git Clone...
3. In the dialog we provide:
   • The URL of the project
   • The directory of the project. This will be automatically populated with the name of the project in our selected folder.
4. Select the Recursive checkbox.
   • This will allow the installation of other repositories used by the main project known as Submodules.

This process will result in a copy of the remote repository downloaded to our machine. Files contained in the .git folder should not be touched as these files hold the git repository information maintained by Git/TortoiseGit for this project.

Making changes to our copy of the project

Any file within the project can now be modified accordingly. We can also add new files.

Adding new files

1. Use the TortoiseGit command: Add.
2. This tells Git that we have a new file to be tracked.

Our changes are made to our local Git working repository only.

• Use the TortoiseGit command: commit.. to save any change.
• Use the TortoiseGit command: Revert to abort any changes made. Changed files end up in the Recycle Bin

Combining small changes to a significant change

When working on a functionality that we continually keep saving our small changes, using the command commit, Git creates a save point for all our small changes. While these small changes can assist us when we are developing and debugging, these small commits may serve no useful purpose in keeping them. If this is the case then we can combine our work into a single commit. If our commits provide different functionality or affect different sections then we may decide to keep these save points to make it clear to others of the change process.

To combine all these small changes to a single change we would do the following:

1. Use the TortoiseGit command: Git Show Log
2. Select the commit point before our first commit in our series of small commits.
3. Use the TortoiseGit command: Reset "BRANCH" to this...
   • Where BRANCH represents the name of the branch being used.
4. In the Reset dialog, Use the 'Reset Type' Mixed option
   • This will remove all the commit points above this point in our local Git repository only.
   • The working files that we have progressively changed remain untouched in our project.
   • The changed files now show up in Git as uncommitted changes.
   • Any new file must be added again because we have reset the git repository.
5. Make a new Commit to our local Git repository.
   • This commit will contain all the changes we made, but saved as a single commit.
   • All the small change points are lost, unless we have saved these in a remote repository somewhere.
6. Using our new commit, we can now publish our work using the command: push to a remote repository.

Note: It is best to combine our commits before we publish our work. If we have published all our small changes, and then decide that we want to combine our work, the resulting command 'push' will fail. This is because our new commit to our local repository has created a misalignment to the Git link structure thus preventing further pushes to that remote repository. This can be clearly seen using the TortoiseGit 'Revision Graph'. To force realignment we will have to use push with the Force option to correct the linkage back to a single chain.

Submitting our work to the main project on GitHub.

Projects on GitHub are stored as reference repositories. Most projects are write protected so we cannot directly save changes to the main project. To overcome this we need our own reference repository where we can save our changes using the command push.

Within GitHub, we would use the GitHub command Fork to obtain our own copy of the reference repository. We would push our changes to our GitHub repository. We would then create a Pull Request directed to the branch we are working on, which in most cases is the master branch.

Note: If we have created a Pull Request, then have found a problem with it, we can either:

1. push the fix to our Git repository with the open pull request
2. (preferred) Combine our work containing the fix, then push our fixed version with force to our Git repository.

We could also create our own reference on our local machine as a backup.

Creating our own local reference

1. Create a separate folder on our machine with a .git extension
   • example: c:\mmex.git
2. Selecting this folder within 'Windows File Explorer' use the command: Git Create repository here...
   • This will add all the reference files required for a bare repository
   • Once we have attached our working repository to this reference, we can then push our changes to it.

Setting up multiple references

1. Selecting our project, use the TortoiseGit command: Settings
2. Selecting the Git/Remote page we can see the original link that the project was obtained.
   • Now we can create a link to our local reference repository.
3. Add our new folder path as the URL and giving our Remote a unique name. Example:
   • Remote = mmex_local
   • URL = c:/mmex.git
4. We also need a link to our project on GitHub that will give us write access to the main project
   • We could use our GitHub user name as our remote name to our GitHub copy or use the standard naming convention as upstream for the main project and origin for our GitHub copy.

Synchronising our work to other repositories

1. With multiple repositories it is good to use the TortoiseGit command: Revision Graph
   • This gives us a graphical representation and linkage of the various repositories.
2. Selecting our project, use the TortoiseGit command: Git Sync...
   • This provides us with a variety of options
3. Using the Manage button we can select the name and branch of our required remote repository.
   • If we have set up our references, we should have upstream, origin and mmex_local
   • origin and mmex_local will have write access, and upstream will not.
   • We can also view any other repository from another user if we have added it.
4. When we just want to update the remote in order to start making changes
   • Use the Git command: Pull
   • This will get all the changes to date and incorporate them into our working repository.
5. When we want to update all remote repositories
   • Use the command: Remote Update
   • This gets all the Git reference points of the other repositories.
6. When we have saved changes, we need to ensure our changes are up to date.
   • Use the command: Fetch and Rebase
   • This will synchronise our changes to the remote and put our change at the top of the chain.
7. When we have write access, we use the command push to synchronise our changes to the remote.
   • Example: we select our remote as mmex_local and push our commits.
8. When we don't have write access, we use GitHub to create a pull request.
9. When we want to check a repository of another user
   • Use the command: Switch/Checkout
   • Create a branch that identifies this version
   • The working area of our repository will be replaced with the code of the remote user
10. Use the Revision Graph to:

• Quickly switch our working area to this branch.
• Examine the relationship of all the branches.
• Compare differences between the branches

Using the Revision Graph will quickly show us if our changes do not align with the remote branch. To realign ourselves with the remote, it is best that we perform a Fetch and Rebase against the remote repository we want to push our changes to. This way, we ensure that our changes are fully compatible with the remote branch.

Fetch and Rebase collects all the changes that we have made and places them at the front/top of the link chain forming a single link chain. It also allows us to fix any conflicts that may occur between the branches.

When the branches become out of line, that is, the push does not work after performing a Fetch/Rebase, the option Force must be used. This will reconfigure the linkage on our Git repository. For this reason it is good to have a local repository that we can test our changes before sending them upstream to GitHub.

Within GitHub, because we generally do not have push access to the main project, we create a pull request from our forked repository to the master project repository. This will then be evaluated and processed accordingly.

Keeping Repositories Synchronised

To update all repositories of the project, it is best to perform a Remote Update, followed by a Pull against the upstream branch. This will then possibly require a push or push with force against our repositories. A push with force is only required if the repository/branch becomes misaligned with the master branch. This keeps everything in order.

When creating a patch or adding new functionality to an existing project, it is possibly a good idea to add these to a separate branch and using the commit/fetch-rebase options to maintain the changes. This in time becomes a personal choice.

When things get messed up that synchronisation with master cannot be achieved.

1. Use the TortoiseGit command: Git Show Log
2. Select the commit point before our problem started.
3. Use the TortoiseGit command: Reset "BRANCH" to this...
   • Where BRANCH represents the name of the branch being used.
4. Use the Hard option
   • This will remove all the commit points above this point in Git AND
   • The working files will be reset back to the condition at that point of the project.
5. Perform a pull against the master repository/branch

WARNING: The Reset Hard option is a last resort option and should be used with caution. It has the potential of destroying any changes that we have made unless we have used other methods to save our work such as patches.

End of Document.