Icon 200x124.png

Road Git Manual

www.roadgit.com

Road Git Manual

Icon 200x124.png

Version: 5 May 2018

Contact: 


Table of Contents

Foreword

Installing Git

Setting up your Repository

Set Working Copy

Clone Repository

Create Repository

File Status Window

Refresh

Pull

Push

Reset

History

Terminal

Settings

Commit Button

History Window

Commit History

Branches

FAQ

Can I start using Road Git if I’m already using Git with another client?

How you undo your last commit(s)?

How to delete a Git branch both locally and remotely?

How to modify existing, unpushed commits?

How do I rename a local Git branch?

How to revert Git repository to a previous commit?

How to remove local (untracked) files from the current Git working tree?

How to check out a remote Git branch?

How to resolve merge conflicts in Git?

How to clone all remote branches in Git?


Foreword

We appreciate your recent purchase of Road Git. We want to make sure that Road Git helps you in your day to day tasks. In this guide you will find support to setting things up and reference for common scenarios. Feel free to skip it if you are an advanced user.

Thank you again, and if you need assistance please don’t hesitate to contact us:


Installing Git

After installing Road Git a new menu item will appear under Window menu. The plugin will automatically detect Git if it is already installed.

ss+(2017-07-01+at+10.57.19).jpg

Road Git is a Git client. Git needs to be installed and needs to be accessible from the command line in order to work properly.

When Git is not found from the command line Road Git will ask to install it before continue:

ba2b90ddd3.png

Click on the “Install Git…” button, you will be directed to the official web page where you can download the latest version of Git.

Please accept the Git License and follow the instructions to download it.

During the installation, please check the following options:

  • Use Git from the Windows Command Prompt
  • Git Credential Manager
  • Git LFS (recommended if your Git server supports Git LFS)

As reference, screenshots of the recommended settings during the installation are shown next:

96d6da176f.png

fd9add6e02.png

1cf87df982.png

8d4bb60095.png

9a393982e1.png

f683cc5242.png


After Git gets installed you’ll need to restart Unity

Now after the installation succeeds, you need to restart the Unity Editor, so that now the plugin finds the recently installed Git. Now when you open the Road Git settings window you should see something like this:

094e2d672d.png

Congratulations! Now Git is working in your system!


Setting up your Repository

There are 3 different ways to start using Road Git with your repository.

Set Working Copy

You have an existing repository in your disk and you just want to start using Road Git instead of the command line or another Git client.

Clone Repository

You have a Git repository hosted in the cloud and you want to have it locally to start synchronizing with it (e.g., pushing your changes).

Create Repository

You don’t have repository at all and want to create one from scratch to start versioning your files.

Set Working Copy

Use the “Browse…” button to find the folder where your repository is located. Road Git will perform some sanity checks in the folder to see if everything looks fine. In case it finds something wrong, you will see a notification about the issue and a suggestion to fix it.

Clone Repository

When cloning a remote repository you will need the url of the repository. Ask for the url to the project admin or find it in the project page with your Git hosting provider. The url will typically be something like:

https://github.com/your_user/your_project.git

You need to provide also the destination path where you want to clone the remote repository. This must be an empty folder. You can use the “Browse…” button to find the folder.


Create Repository

You can create a new repository from scratch. Below you’ll find the description for each option.

Destination Path: Where the root of the git repository will be located. For example, if you want to version your Unity project, you should choose the Unity Project folder (the one that contains subfolders Assets and ProjectSettings). That’s the default folder. You can however choose another folder if, for instance, your project contains multiple Unity projects or other elements that you want to version within the same repository.

Add .gitignore file: When selected will add a .gitignore file to the root of the new repository. Gitignore files are special files in Git (with an empty name and gitignore as extension) can be edited as plain text and contains patterns of files or folders that would be ignored. The default .gitignore file created contains common patterns to ignore for Unity projects. If the destination path is set to another folder, you may want to manually review the .gitignore file. See the official documentation for more details on .gitignore: https://git-scm.com/docs/gitignore

Add .gitattributes: When selected will add the .gitattributes into the repository root. This file contains definitions about the project hierarchy, based on patterns. The default file that Road Git generates contains common files that will be versioned using LFS. If your remote supports LFS it is recommended to let it checked. Find more on https://git-scm.com/docs/gitattributes

1ae05da194.png

After creating the repository you can see the state of the repository on the File Status window, explained below.

File Status Window

The File Status Window is the Window where you can see the current status of the repository. Files that are tracked under version control with no changes won’t be shown, but new, modified or deleted files are shown, so you can decide what to do with them.

f2b3bb9167.png

Refresh

Rescans the disk in search for changes. Refresh may happen automatically after certain operations, but sometimes you may want to force Road Git to refresh its file status.

Pull

Incorporates changes from a remote repository into the current branch. This will effectively merge the work of other team mates in your local repository.

Push

Updates remote with the changes committed to your local repository. This makes available your changes to your team mates.

Reset

Reset will discard all your local, uncommitted, changes.

History

Opens the history Window.


Terminal

Opens a terminal window based on the root of the Git repository.

Settingssettings.png

Opens the settings window.

Commit Button

Commits your staged changes. That is, a new commit will be created in your local repository containing the changes you have in the stage section. A comment should be added for every commit briefly explaining the changes done to help you track your file history in the future.

Amend Last Commit: If checked, will amend the last commit instead of create a new one. Can be useful if you forgot to stage a file, or to improve the comment.

History Window

The History Window shows the commits from the past and information about branches. You can see who committed what, and you can also inspect the files changes for every commit, among other details.

From the same window, there’s a branches section where you can create and delete branches, switch from one branch to another and start tracking remote branches.

faa18e2644.png

Commit History

Shows a sorted list of all commits. You can right click on a commit and a contextual menu will pop out. From there you can do one of the following actions:

  • Merge: Will merge the commit selected and all its history into your current branch.
  • Revert: Creates a new commit that undoes the changes done in the commit selected.
  • Reset: Will reset your current branch into the selected commit. Reset comes in 3  different modes, extracted from the official git documentation:
  • --soft Does not touch the index file or the working tree at all (but resets the head to <commit>, just like all modes do). This leaves all your changed files "Changes to be committed", as git status would put it.
  • --mixed Resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated. This is the default action.
  • --hard Resets the index and working tree. Any changes to tracked files in the working tree since <commit> are discarded.
  • Show in full graph: Opens the external graph view if Gitk is installed. Gitk is a native part of git and it should be  available in most of the git installations.

Branches

From the branches view you can see the local and remote branches in the repository. Your current branch is shown in bold font. Right click any branch to see the options available in the contextual menu. The options shown are:

  • Checkout.  For a local branch will switch your current branch to the one selected. Checking out a remote branch will create a local branch with the same name and will track that remote.
  • Merge. Merges the selected branch into the current one. You can both merge local or remote branches.
  • Delete. Will delete the branch. If the branch is not completely merged it will ask for double confirmation to force the deletion of the branch.

To create a local branch click on the [+] button at the bottom and give a branch name, then click “Create”.

b3033373c6.png


FAQ

Can I start using Road Git if I’m already using Git with another client?

Yes, totally. The transition is transparent. Indeed you can use several clients if you prefer. Git guarantees the consistency of your repository, even when multiple clients are connected.

How you undo your last commit(s)?

If you did not pushed your commits see How to modify existing, unpushed commits?

For pushed changes unfortunately is more difficult to change the history, because it may be already part of other people’s local repositories. You can however revert what was wrong by finding the commit you want to revert in the history view, right click and choosing Revert in  the contextual menu.

How to delete a Git branch both locally and remotely?

Simply right click on the local branch and click delete. Please note that you can’t delete your current branch. If you want to delete your current branch, you can checkout another branch (or even create a new one) and then delete your branch.

To delete the remote branch right click and delete.

How to modify existing, unpushed commits?

If you want to fix your last commit and you haven’t pushed it yet, you can just check the “Amend” checkbox, then commit again. The old commit message will be overwritten by the new one, and changes made in files will be part of the amended commit.

Another way to undo your commits is using the history window. Right click a previous commit and reset your branch there. You can completely get rid of your lasts commits depending on the reset mode that you use.

How do I rename a local Git branch?

Checkout the branch you want to rename, then create another branch from there with the new name. Notice that both branches now point to the same commit. Delete the old branch.

For remote branches just push your local branch after you’re done with the process above.

How to revert Git repository to a previous commit?

Find the commit in the history window, then use right click and reset to put the working copy is the state the repository had at that commit. See Commit History for more details.

How to remove local (untracked) files from the current Git working tree?

New files will appear with a question mark symbol. Just select them and right click / delete them. You may want to learn about .gitignore file if you regularly find untracked files showing up in your unstaged area.

How to check out a remote Git branch?

Open the remotes foldout in the branches view, right click the remote branch you want to check out. Click checkout. A new local branch with the remote name will appear in the list. The new branch will track the remote, meaning pulls and pushes will synchronize the local and the remote branches.

How to resolve merge conflicts in Git?

When there is a conflict, usually after a merge or a pull, the file or files with conflicts will show a warning symbol. You can right click a file with a warning and solve the conflict with yours version or theirs version, using the context menu. Yours version means the version in the current branch. For instance, if you were on branch experiment and had a conflict after merge branch master, solving with yours will let intact changes from experiment. If the conflict was resolved with theirs version, the file preserved would be the one from master. For code files, usually the best option is to edit the conflict manually and fix it, in order to preserve changes from both branches.

How to clone all remote branches in Git?

When you clone a remote repository, the entire remote repository is replicated into your local repository. This means you will have all the repository history in your local folder, including all the branches. However is also true that your working copy (e.g., the files you see), will depend on you current local branch. You may need to checkout a different branch to see the repository in the status you want.