Basics

Context

You want to write an article (in $\LaTeX$ obviously) on the new results you found. Because you do want to save every step of your work, you are going to use git. Right now, you have to prepare the file and the skeleton of the file, your colleagues will then be able to join the project when you push it on the server.

Initialisation

Create a folder for your article and then enter it:

❯ mkdir paper
❯ cd paper

Now, make this folder a git repository:

❯ git init

This creates a (hidden) .git folder which contains information for git. If you delete it, then every git information of this repository is lost (mainly the history).

Configuration

A commit meta data contains some user informations such as name and email. These meta data are useful to, e.g., find a the author of a commit and question him/her about the choice that have been made. In multi users project, blame can also be assigned commiter… Among every options that can be set, only the name and email are required (but not required to be true!).

❯ git config --global user.name "John Doe"
❯ git config --global user.email johndoe@example.com

These command line set up the git configuration globally, that is for every repository on your computer. If a local configuration has been set, it will override the global ones. If you want to set it only for a directory, change global by local.

Git Commit

First commit

Create an empty file paper.tex in your folder:

❯ touch paper.tex

Let us now ask git about the status of the folder:

❯ git status
On branch master

No commits yet

Untracked files:
  (use "git add <file❯..." to include in what will be committed)
	paper.tex

nothing added to commit but untracked files present (use "git add" to track)

git says there is an untracked file (paper.tex) and also provides you with the command to track it (git add). Let’s do it!

❯ git add paper.tex
❯ git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file❯..." to unstage)
	new file:   paper.tex

The file paper.tex is in the staging area. We want to save this first version of the file, or, in the git language, do a commit (kind of a “screenshot”):

❯ git commit -m "First commit"
[master (root-commit) 1f87abd] First commit
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 paper.tex
❯ git status
On branch master
nothing added to commit but untracked files present (use "git add" to track)

You can check the history of the commits with the git log commands (the SHA commit number will be different:

❯ git log
commit 40499594e41859ca2c6e57017f0a173be84f1984 (HEAD -❯ master)
Author: Your Name <you@you.com❯
Date:   Mon Nov 18 12:43:18 2019 +0100

    First commit

The SHA number (404995...) is the unique identifier of your commit, used e.g. to come back to a previous version of your file.

Second commit

Fill the paper.tex file with a minimalist $\LaTeX$ code (and save!)

\documentclass{article}
\title{My Paper}
\begin{document}
\maketitle
\end{document}

Again, let us ask git what’s up:

❯ git status
On branch master
Changes not staged for commit:
  (use "git add <file❯..." to update what will be committed)
  (use "git restore <file❯..." to discard changes in working directory)
	modified:   paper.tex

no changes added to commit (use "git add" and/or "git commit -a")

You can check what have been changed in the file

❯ git diff paper.tex
diff --git a/paper.tex b/paper.tex
index e69de29..7db26de 100644
--- a/paper.tex
+++ b/paper.tex
@@ -0,0 +1,5 @@
+\documentclass{article}
+\title{My Paper}
+\begin{document}
+\maketitle
+\end{document}
\ No newline at end of file

And now, you can save this new version of the file by typing either

❯ git add paper.tex
❯ git commit -m "Minimalist tex"

or use the shortcut option -a (a=all):

❯ git commit -m "Minimalist tex" -a

to commit a new version of the file.

Git ignore

If you compile paper.tex, $\LaTeX$ will produce a consequent number of files (.aux, .toc, …) and a .pdf file. These files are re-generated at every compilation: it is pointless (and even confusing!) to track them! However, it can be annoying that git ask you if you want to track them, that is why you can specify to git rules about files that must not be tracked.

❯ pdflatex paper.tex
...
❯ git status
On branch master
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	paper.aux
	paper.log
	paper.pdf

nothing added to commit but untracked files present (use "git add" to track)

A good idea is to create a hidden file .gitignore (the last line is for emacs users):

*.aux
*.log
*.toc
*.pdf
*~

Now, when asking git what’s up, it only proposes the .gitignore file, that you should track and commit!

❯ git status
On branch master
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.gitignore

nothing added to commit but untracked files present (use "git add" to track)
❯ git add .gitignore
❯ git commit -m "git ignore"

Exercise

Modify the file paper.tex by adding text, save and commit.