Intro to git
(for Torque users)
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Questions that will be answered
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Sadly,
This is not a complete reference. Read it alongside other, more comprehensive tutorials! There is plenty of information about git out there, once you understand the basics.
This guide should give you an overview of common tasks you'll do when working with Torque using git. For other guides and references, try one of these:
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Do I have to use the command line?
No, but it's a very good way to use git. It gives you more control, and after you've got the hang of a few basic commands, it's very quick to use!
Alternatives:
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
1. What is git?
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Git is a
Distributed
Version
Control
System
DVCS for short
}
There's no single authoritative server
Tracks revisions of your source code
Kind of redundant
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Version control, you say?
Git remembers all the changes you make to your code, like this one:
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
three lines added
Each change (commit) has a random* string associated with it, and all the commits in a repository form a tree**. Like this simple one:
Or this complex one:
ab865f First commit
9f2240 Second commit
c905ed Third commit
*They're not actually random, they just look like it. But don't worry about that for now.
**It's actually a graph, but whatever.
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
2. Getting the source
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Forking and cloning
Forking the repository makes a complete remote copy of the source code. Cloning it makes a local copy of the code. As a diagram, that looks like:
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
GarageGames/
Torque3D
myself/
Torque3D
C:/Torque3D
fork
clone
the GitHub cloud
my computer
The first thing you'll need to have is a GitHub account. Got one? Good. Now you can fork a copy of the Torque engine.
Visit the page for the engine you're looking for (2D or 3D), and click this button:
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Refer to your git program's documentation on cloning for the next step. Using the command-line, you would type:
git clone https://github.com/myself/Torque3D.git
Once you've done that, you'll have a copy of the whole repository. You don't just have a working copy (like a Subversion checkout), you have the entire history of the code right there on your computer.
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
The upstream repository
Your git repository has links to other repositories called remotes. The default remote, called origin, is where you cloned your code from (i.e. your GitHub account).
Now is a good time to add another remote called upstream, and link it to GarageGames' repository. That way, you can get updates from GarageGames when a new version of the code is released.
In the command-line, this looks like:
git remote add upstream https://github.com/GarageGames/Torque3D.git
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
So the situation is now:
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
GarageGames/
Torque3D
myself/
Torque3D
C:/Torque3D
origin
upstream
You can add as many different remotes as you like, to any repositories (even local ones on your hard drive, or ones hosted elsewhere than GitHub).
We'll work with remotes later on. For now, I just want you to know what they are!
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Default branches
Git repositories are organised into branches, which are just a fancy way of referring to a single commit. By default, Torque repositories have two branches: master (which every git repository has) and development.
You can check out a branch to see the state of the code on that branch, like so:
git checkout master
or
git checkout development
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
Branches in a git repository are just names that refer to specific commits. So, when I talk about a branch called jison, I'm referring to all the commits that are ancestors of the commit named jison:
So, all those green commits are in the jison branch. Note that some black commits are part of multiple branches, since they have several named descendents.
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
The convention in the Torque repositories is to make all changes to the development branch. The master branch is reserved for releases: a release is defined as merging the development branch into the master branch, like this:
git checkout master
git merge development
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
old master
development
new master
merge commit
All the commits made in the development branch are now present in the master branch because they are now ancestors of the commit named master.
3. Making changes
1. What is git? 2. Getting the source 3. Making changes 4. Contributing
1. What is git? 2. Getting the source 3. Making changes 4. Contributing