|
|
|
# Finding your way with Git
|
|
|
|
|
|
|
|
This document outlines some basic elements of Git, especially in the context of
|
|
|
|
our workflow in the Optimisation Group. In this project we will continue to add
|
|
|
|
folders with specific examples. You are always welcome to check out this project,
|
|
|
|
create a new branch, contribute to it, and send [me](@jwjoubert) a merge request...
|
|
|
|
don't know what _that_ is (yet)? Read on.
|
|
|
|
|
|
|
|
## Contents
|
|
|
|
|
|
|
|
* **[First you need Git](#first-you-need-git)**
|
|
|
|
|
|
|
|
* **[Windows](#windows)**
|
|
|
|
* **[Mac OS](#mac-os)**
|
|
|
|
* **[Linux](#linux)**
|
|
|
|
|
|
|
|
* **[The typical Git workflow](#the-typical-git-workflow)**
|
|
|
|
|
|
|
|
* **[Integrating Git with your documents](#integrating-git-with-your-documents)**
|
|
|
|
|
|
|
|
* **[A quick and dirty way to getting started with Git](#a-quick-and-dirty-way-to-getting-started-with-git)**
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
## First you need Git
|
|
|
|
|
|
|
|
To be able to work with Git, you will need Git itself and also (for ease of use)
|
|
|
|
a _Git client_. The following subsections highlights the main steps for the
|
|
|
|
different platforms:
|
|
|
|
|
|
|
|
### Windows
|
|
|
|
|
|
|
|
Because we always feel sorry for the poor Windows users we will start with them.
|
|
|
|
The first step would be to download Git itself, and you can get it
|
|
|
|
[here](https://git-scm.com/download/win), just choose the right version (32- or
|
|
|
|
64-bit).
|
|
|
|
|
|
|
|
Once installed, I suggest you get a _Graphical User Interface_ (GUI) that will
|
|
|
|
allow you to deal with Git without having to work on the command line. For
|
|
|
|
Windows I recommend [TortoiseGit](https://tortoisegit.org), although there are
|
|
|
|
[others](https://git-scm.com/downloads/guis).
|
|
|
|
|
|
|
|
You should now be ready to _git_ going.
|
|
|
|
|
|
|
|
### Mac OS
|
|
|
|
|
|
|
|
For Mac I suggest you use [macports](https://www.macports.org) to install
|
|
|
|
Git. The version of Git that ships with Mac OS is quite old. Once you have
|
|
|
|
macports installed, it is simply
|
|
|
|
|
|
|
|
```shell
|
|
|
|
sudo port install git
|
|
|
|
```
|
|
|
|
|
|
|
|
To check what version of Git you are running, type the following command in the
|
|
|
|
Terminal.
|
|
|
|
```shell
|
|
|
|
git --version
|
|
|
|
```
|
|
|
|
If it is not the version you want, check which version it is actually using.
|
|
|
|
```shell
|
|
|
|
which git
|
|
|
|
```
|
|
|
|
The default is usually `/usr/bin/git` while `macports` would have installed the
|
|
|
|
newer version in `/opt/local/bin`. To point to the newer Git version, you may
|
|
|
|
have to create/update your `~/.bash_profile`. If you don't have one, create it
|
|
|
|
with
|
|
|
|
```shell
|
|
|
|
touch ~/.bash_profile
|
|
|
|
```
|
|
|
|
and then add the following to the `PATH` variable. In a new file, this would
|
|
|
|
be the first few lines.
|
|
|
|
```shell
|
|
|
|
PATH=/opt/local/bin:$PATH
|
|
|
|
export PATH
|
|
|
|
```
|
|
|
|
I found that is required that you add the `/opt/local/bin` _before_ the original
|
|
|
|
`$PATH` variable.
|
|
|
|
|
|
|
|
A great Git client for Mac OS is [Tower](https://www.git-tower.com). It is not
|
|
|
|
free but offers academic and student discounts. There are also brilliant
|
|
|
|
training material on using Git. Although the material is free online content, it
|
|
|
|
is structured around Tower, so users of other [Git GUI clients](https://git-scm.com/download/gui/linux)
|
|
|
|
may have to adapt the training material to their GUI of choice.
|
|
|
|
|
|
|
|
### Linux
|
|
|
|
|
|
|
|
Getting git may be distribution specific, but the following should work on the
|
|
|
|
command line/Terminal of Ubuntu.
|
|
|
|
```shell
|
|
|
|
sudo apt-get install git
|
|
|
|
```
|
|
|
|
|
|
|
|
As a GUI Git client you may want to look at Axosoft's [GitKraken](https://www.gitkraken.com).
|
|
|
|
It actually has Windows and Mac versions too.
|
|
|
|
|
|
|
|
***
|
|
|
|
|
|
|
|
## The typical Git workflow
|
|
|
|
|
|
|
|
The following image shows a typical Git workflow.
|
|
|
|
|
|
|
|
<br /><br /><center>
|
|
|
|
<img src="graphics/gitWorkflow.png" alt="Example of a typical Git workflow" width="800" />
|
|
|
|
</center><br /><br />
|
|
|
|
|
|
|
|
There is a good document discussing the different workflow types available on
|
|
|
|
the [Atlassian](https://www.atlassian.com/git/tutorials/comparing-workflows/)
|
|
|
|
website (I can strongly recommend their tutorials and documentation). We follow
|
|
|
|
a _centralised workflow_.
|
|
|
|
|
|
|
|
1. The main (central) repository resides here on _GitLab_. The first step is to
|
|
|
|
_get_ a copy of the repository onto your local machine. When you're on the
|
|
|
|
landing page of a project you should see the project's URL as highlighted in
|
|
|
|
the image below.<br />
|
|
|
|
<center>
|
|
|
|
<img src="graphics/gitURL.png" alt="Project's Git URL" width="800" />
|
|
|
|
</center><br />
|
|
|
|
Please use the `HTTPS` protocol and not `SSH` (the latter, I think, is
|
|
|
|
usually the default). I prefer working on the command line/terminal, so the
|
|
|
|
command to clone a local copy of this repository would then be (on Mac or Linux)
|
|
|
|
```shell
|
|
|
|
git clone https://ie-repo.up.ac.za/howto/git.git ./howToGit
|
|
|
|
```
|
|
|
|
You have now created a clone of the remote repository on your machine in the location __./howToGit__. This is your local repository.
|
|
|
|
|
|
|
|
Some users may experience, at this point, a warning about an SSL certificate
|
|
|
|
problem. This can be overcome, at least on a Mac, by executing the following
|
|
|
|
command (only once) on the terminal.
|
|
|
|
```shell
|
|
|
|
git config --global http.sslVerify false
|
|
|
|
```
|
|
|
|
|
|
|
|
2. Now you can do your magic, add folders and files, and edit them as you please.
|
|
|
|
This would typically be what you do on your own project. If you want to edit
|
|
|
|
this document, you will have to create a branch; make your edits; and send me a
|
|
|
|
pull request, but more about that later.
|
|
|
|
|
|
|
|
3. As you progress on your project, you will add files to a local _staging area_
|
|
|
|
that acts as a container for the work you want to be put under version control.
|
|
|
|
This includes both new files, and edited files. For example, say you have edited
|
|
|
|
this `README.md` file, you will add it with the following command
|
|
|
|
```shell
|
|
|
|
git add README.md
|
|
|
|
```
|
|
|
|
(NB: You must be _in_ your local repository when using the git commands)
|
|
|
|
|
|
|
|
4. After you've added all the files you want to include in the current
|
|
|
|
_snapshot_, you commit it. But unlike `subversion` where a commit sends it to
|
|
|
|
the remote repository, in git it only gets committed locally. Also, we add a
|
|
|
|
nice and descriptive message of what we're committing. This will help others to
|
|
|
|
know what changed in that particular commit.
|
|
|
|
```shell
|
|
|
|
git commit -m "Fixed some typos"
|
|
|
|
```
|
|
|
|
You can, and should, commit frequently. This allows you to revert back to earlier commits if you realise that you made a blunder, and actually want to _undo_ a bunch of stuff. It's much easier to just `revert` to an earlier commit.
|
|
|
|
|
|
|
|
5. Before you send all your local changes, i.e. commits, back to the central repository, others may have already made changes too and sent it to the central repository. To ensure their changes are reflected, you first need to update your local repository to be in line with the central repository. The command you will use is
|
|
|
|
```shell
|
|
|
|
git pull --rebase
|
|
|
|
```
|
|
|
|
The `--rebase` argument simply tells git to bring the remote repository's changes, merge them with the current local copy, and then put your newly committed changes _after_ the changes that came in.
|
|
|
|
|
|
|
|
6. Now you are ready to send your local changes to the remote repository.
|
|
|
|
```
|
|
|
|
git push origin master
|
|
|
|
```
|
|
|
|
where `origin` indicates the remote, central repository, and `master` the branch on which you are working. You will mainly work on the master branch, but more on that later.
|
|
|
|
|
|
|
|
If you want more info on Markdown documents, look [here](https://github.com/gitlabhq/gitlabhq/blob/master/doc/markdown/markdown.md).
|
|
|
|
|
|
|
|
|
|
|
|
## Integrating Git with your documents
|
|
|
|
|
|
|
|
A neat feature working in LaTeX is that you can add a watermark to the footer of
|
|
|
|
your document, for example, which shows who the last person is to commit to the
|
|
|
|
document and what the specific revision is. More information on setting that up
|
|
|
|
and getting it done [here](https://ie-repo.up.ac.za/howto/latex/tree/master/git).
|
|
|
|
|
|
|
|
## A quick and dirty way to getting started with Git
|
|
|
|
|
|
|
|
If you've made it this far the [following video](https://youtu.be/FwyX0Q_ibTY) shows a quick and dirty way of getting up and running with git using the [SourceTree](https://www.sourcetreeapp.com) GUI. |
|
|
|
\ No newline at end of file |