Version Control, Part I - Git on a Single Machine€¦ · Version Control, Part I - Git on a Single...

Version Control, Part I - Git on a Single Machine

Hans-Martin von Gaudecker

Going back in time

• How often in the research process does one believe a paper to be finished?• And when you think it is done, enter ...

– ... supervisor,– ... co-authors,– ... conference participants,– ... referees

Going back in time

• Often long lags in between changes in beliefs• Project changes in the meantime

– Suddenly you’re not able to reproduce the results you had at the timeyou submitted {paper, thesis}

• Need to keep track of older versions

Going back in time

1

Ad-hoc solutions

• Back up stuff regularly:

my_projectmy_project_v0my_project_v1my_project_v2

• You are certain to miss the important version

• Spend energy on research rather than mindless stuff

Recurring message

• Computers are much better at solving repetitive tasks than humans are• So let the machines do the work

Math interlude: Graphs

• 𝐺 = (𝑁, 𝐸)• Examples:

– 𝑁 = {𝑥0, 𝑥1, 𝑥2, 𝑥3}, 𝐸 = {{𝑥0, 𝑥2}, {𝑥2, 𝑥1}}– 𝑁 = {𝑥0, 𝑥1, 𝑥2, 𝑥3}, 𝐸 = {(𝑥0, 𝑥2), (𝑥2, 𝑥1), (𝑥1, 𝑥2)}

Math interlude: Graphs

Edges Nodes GraphsUndirected Adjacent DirectedDirected Connected Paths

Disconnected Directed pathsParents Directed acyclicChildren TreeRoot ChainSink Connected

2

Project Setup

• Say I was working on the design of this course• Begin with the outline• Start from my LaTeX template for papers

Project Setup

\documentclass[11pt, a4paper, leqno]{article}\usepackage{a4wide}\usepackage[T1]{fontenc}\usepackage[utf8]{inputenc}\usepackage{float, afterpage, rotating, graphicx}\usepackage{epstopdf}\usepackage{longtable, booktabs, tabularx}\usepackage{fancyvrb, moreverb, relsize}\usepackage{eurosym, calc, chngcntr}\usepackage{amsmath, amssymb, amsfonts, amsthm, bm}\usepackage{caption}\usepackage{mdwlist}\usepackage{xfrac}% \usepackage[top=1.5in, bottom=1.5in, left=1.0in, right=1.0in]{geometry}% \usepackage{pdf14} % enable for manuscriptcentral -- can't handle pdf 1.5% \usepackage{endfloat}

% \usepackage[backend=biber, natbib=true, bibencoding=inputenc,% bibstyle=authoryear-ibid, citestyle=authoryear-comp, maxcitenames=3,% maxbibnames=10]{biblatex}% \setlength{\bibitemsep}{1.5ex}% \addbibresource{bib/hmg.bib}

\usepackage[unicode=true]{hyperref}\hypersetup{colorlinks=true, linkcolor=black, anchorcolor=black,

citecolor=black, filecolor=black, menucolor=black, runcolor=black,urlcolor=black

}

\setlength{\parskip}{.5ex}

\begin{document}

\title{Title here\thanks{Von Gaudecker: Universität Bonn, Department of Economics,

3

Adenauerallee 24-42, 53012 Bonn, Germany.}% subtitle:% \\[1ex]% \large Subtitle here}

\author{Hans-Martin von Gaudecker% others:% \\[1ex]% next author}

\date{{\bf Preliminary -- please do not quote}\\[1ex]\today}

\maketitle

\begin{abstract}Some abstract here.

\end{abstract}\clearpage

\section{Introduction} % (fold)\label{sec:introduction}

Some text here. Example for a formula inclusion:

% \input{formulas/some_formula}

% A typical table inclusion.% \input{../../out/final/tables/xxx}

% A typical figure inclusion.% \includegraphics[width=.5\textwidth]{../../out/final/figures/xxx}

% section introduction (end)

% Include bibliography if desired% \printbibliography

4

%\appendix%\counterwithin{table}{section}%\counterwithin{figure}{section}

\end{document}

DAG of the project

5

Using Git Bash on Windows

• Navigate to your project’s folder• Right-click on the project folder and select ”Git Bash”

Git on a Mac/Linux terminal

• Simply open a terminal in /Applications/Utilities and get started• Navigate to your project’s folder• Right-click on the project folder and select ”Git Bash”

6

Set up your git credentials

• Eventually, a large benefit of Git will be that it tracks who did what andwhen

• So first tell Git who you are and how you may be reached

$ git config --global user.name "First Last"$ git config --global user.email "first.last@example.com"

Creating a local repository

• Assume you changed to the directory of your project in a shell

$ git init

Initialized empty Git repository in /home/me/tex-project/.git/

Creating a local repository

• Check the status of the repository

$ git status

On branch master

Initial commit

Untracked files:(use "add <file>..." to include in what will be committed)

outline.tex

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

7

The index or staging area

• Add outline.tex to the index (=all files to be included in the next com-mit to the repository)

$ git add outline.tex

$ git status

On branch master

Initial commit

Changes to be committed:(use "reset HEAD <file>..." to unstage)

new file: outline.tex

• Extra step is overkill now, but worth it in complex projects

First commit

• Commit to the local repository with a meaningful message

$ git commit -m "Initial commit with the project template."

[master (root-commit) 39a7cb5]Initial commit with the paper template

1 file changed, 91 insertions(+)create mode 100644 outline.tex

$ git status

On branch masternothing to commit, working directory clean

8

Second commit

• Adjust template file outline.tex

[edit outline.tex]

$ git status

On branch master

Changes not staged for commit:

(use "add <file>..." to update what will be committed)(use "checkout -- <file>..." to discardchanges in working directory)

modified: outline.tex

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

Second commit

• Add the modified file to the index and commit again

$ git add outline.tex

$ git commit -m "Minimal adjustments to template."

[master b5cd396] Minimal adjustments to template.1 file changed, 11 insertions(+), 50 deletions(-)

$ git status

On branch master

nothing to commit, working directory clean

9

Third commit

• Add abstract and document structure to the paper template

[edit outline.tex]

$ git status

On branch master

Changes not staged for commit:

(use "add <file>..." to update what will be committed)(use "checkout -- <file>..." to discardchanges in working directory)

modified: outline.tex

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

Third commit

• Add the modified file to the index and commit again

$ git add outline.tex

$ git commit -m "Added abstract and document structure."

[master 8c676ec] Added abstract and document structure.1 file changed, 31 insertions(+), 11 deletions(-)

10

Fourth commit

• Include a file introduction.tex in the paper template

[create introduction.tex]

[edit outline.tex]

$ git status

On branch masterChanges not staged for commit:(use "add <file>..." to update what will be committed)(use "checkout -- <file>..." to discard

changes in working directory)

modified: outline.tex

Untracked files:(use "add <file>..." to include in what will be committed)

introduction.texno changes added to commit (use "add" and/or "commit -a")

Fourth commit

• Now commit these changes to the local repository

$ git commit -a -m "Added first item to microstructure."

[master df4e469] Added first item to microstructure.1 file changed, 6 insertions(+)

$ git status

On branch masterUntracked files:(use "add <file>..." to include in what will be committed)

introduction.texnothing added to commit but untracked files present(use "add" to track)

11

Fourth commit

• Add also new file introduction.tex to index and amend last commit.(-a does not include new files)

$ git add introduction.tex

$ git status

On branch masterChanges to be committed:(use "reset HEAD <file>..." to unstage)

new file: introduction.tex

$ git commit -a -m "Added first item to microstructure." --amend

[master 1f2b5f0] Added first item to microstructure.2 files changed, 36 insertions(+)create mode 100644 introduction.tex

View log of commits

$ git log

commit 1f2b5f0a6dc79d3481aaafa044843e419457194dAuthor: Hans-Martin v. Gaudecker <x@y.de>Date: Wed Oct 2 14:31:30 2013 +0200

Added first item to microstructure.

commit 8c676ec01851ad9811336b22f7fad517bc9c308eAuthor: Hans-Martin v. Gaudecker <x@y.de>Date: Wed Oct 2 14:21:11 2013 +0200

Added abstract and document structure.

commit b5cd3969801682951cc3e852f51cbb14b5e3275aAuthor: Hans-Martin v. Gaudecker <x@y.de>Date: Wed Oct 2 14:14:24 2013 +0200

Minimal adjustments to template.

Type q if you don’t see a command prompt (long output)

12

Compile the LaTeX document, check status

$ git status

On branch masterUntracked files:(use "add <file>..." to include in what will be committed)

outline.auxoutline.bcfoutline.blgoutline.fdb_latexmkoutline.logoutline.outoutline.pdfoutline.run.xmloutline.synctex.gz

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

Keep only source code under version control

• A version of outline.pdf contained

/Author()/Title()/Subject()/Creator(LaTeX with hyperref package)``/CreationDate (D:20130412083319+02'00')``/ModDate (D:20130412083319+02'00')``

• Will change every time you re-create the pdf - even if there are no sub-stantive changes - and thus ...

– there will be many fake changes of the repository– the repository size will explode

• ∑ Keep only sources under VC

– Original data and source code from statistics programs, LaTeXsources, etc.

13

Ignoring output and nuisance files

• Manually pick the tex file among the pdf’s and compilation garbage foreach commit?

• Won’t be able to see the forest for the trees, miss things in more compli-cated situations

• Specify patterns to be ignored in a file called .gitignore, lives in projectroot

• Patterns:– ∗ Match 0 or more characters of any type– ? Match exactly one character of any type

• Still possible to manually add files that are ignored

Add a file called .gitignore to the main folder

.**.aux*.bbl*.bcf*.blg*.pdf*.log*.out*.run.xml*latexmk*synctex.gz

• Check Git’s status after including the .gitignore file in your projectfolder

$ git status

On branch masternothing to commit, working directory clean

14

Add .gitignore-file to the repository

• Add file .gitignore to the index of your project folder

$ git add .gitignore

The following paths are ignored by one of your .gitignore files:.gitignoreUse -f if you really want to add them.fatal: no files added

$ git add .gitignore -f

Add .gitignore-file to the repository

• Commit .gitignore file to the local repository

$ git status

On branch masterChanges to be committed:(use "reset HEAD <file>..." to unstage)

new file: .gitignore

$ git commit -m "Added .gitignore."

[master 2d9309f] Added gitignore.1 file changed, 11 insertions(+)create mode 100644 .gitignore

15

DAG of the project, early 2013

16

DAG of the project, early 2013

Creating a new branch

• Assume you are in the master branch

$ git branch bonn_ss_2013

$ git status

On branch masternothing to commit, working directory clean

$ git branch

* masterbonn_ss_2013

Switching the branch: Git checkout again

• Use checkout to switch the branch

$ git checkout bonn_ss_2013

Switched to branch 'bonn_ss_2013'

$ git branch

master* bonn_ss_2013

17

DAG of the project, early 2013

Commits go to branch you are currently on

• Focus on one file: version_control.tex

[remove all SVN references from version_control.tex and add Sink book]}

$ git status

# On branch bonn_ss_2013# Changes not staged for commit:# (use "git add <file>..." to update what will be committed)# (use "git checkout -- <file>..." to discard changes in working directory)## modified: version_control.tex#no changes added to commit (use "add" and/or "commit -a")

18

Commits go to branch you’re currently on

$ git add version_control.tex

$ git status

On branch bonn_ss_2013Changes to be committed:(use "reset HEAD <file>..." to unstage)

new file: version_control.tex

$ git commit -m "Sink book as the only VC reference."

[bonn_ss_2013 ad3fffa] Sink book as the only VC reference.1 file changed, 2 insertions(+), 4 deletions(-)

19

DAG of the project, early 2013

Editing files in another branch: Switch back andcontinue with the usual workflow

• Switch back to master branch, and add the Sink book to the list of SVNreferences in version\_control.tex

$ git checkout master

Switched to branch 'master'

[edit version_control.tex, add Sink book to references]

$ git add version_control.tex

$ git commit -m "Added Sink book to SVN references."

[master 4da7639] Added Sink book to SVN references.1 file changed, 1 insertion(+)

20

Renaming files

• Go back to new branch• Use Git to rename a file*Why?*

$ git checkout bonn_ss_2013

$ git mv version_control.tex git_single_machine.tex

$ git status

On branch masterChanges to be committed:(use "reset HEAD <file>..." to unstage)

Add the second file, edits

• Copy some content to new file

[create git_collaboration.tex]

[edit git_single_machine.tex and git_collaboration.tex]

$ git status# On branch bonn_ss_2013# Changes to be committed:# (use "git reset HEAD <file>..." to unstage)## renamed: version_control.tex -> git_single_machine.tex## Changes not staged for commit:# (use "git add <file>..." to update what will be committed)# (use "git checkout -- <file>..." to discard changes in working directory)## modified: git_single_machine.tex## Untracked files:# (use "git add <file>..." to include in what will be committed)## git_collaboration.tex

21

Commit everything

• Add both files to the index, commit changes.

$ git add git_single_machine.tex git_collaboration.tex

$ git commit -m "Split up VC lecture in two parts."

[bonn_ss_2013 2fa686e] Split up VC lecture in two parts.}3 files changed, 10 insertions(+), 5 deletions(-)}create mode 100644 git_collaboration.tex}create mode 100644 git_single_machine.tex}delete mode 100644 version_control.tex}

Undo changes: Git checkout once more

[edit git_single_machine.tex]}

$ git status

On branch bonn_ss_2013Changes not staged for commit:(use "add <file>..." to update what will be committed)(use "checkout -- <file>..." to discard

changes in working directory)

modified: git_single_machine.tex

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

$ git checkout git_single_machine.tex

$ git status

On branch bonn_ss_2013nothing to commit, working directory clean

22

DAG of the project, early 2013

Merging

• Will continue to use Git: Merge it into master branch.

$ git checkout master

Switched to branch 'master'

$ git merge bonn_ss_2013

CONFLICT (modify/delete):version_control.tex deleted in bonn_ss_2013 and modified in HEAD.Version HEAD of version_control.tex left in tree.Automatic merge failed; fix conflicts and then commit the result.

• Message tells you exactly what you need to do!

23

Merging

$ git status

# On branch master# You have unmerged paths.# (fix conflicts and run "git commit")## Changes to be committed:## new file: git_collaboration.tex# new file: git_single_machine.tex## Unmerged paths:# (use "git add/rm <file>..." as appropriate to mark resolution)## deleted by them: version_control.tex#

Merging

$ git rm version_control.tex

version_control.tex: needs mergerm 'version_control.tex'

$ git status# On branch master# All conflicts fixed but you are still merging.# (use "git commit" to conclude merge)## Changes to be committed:## new file: git_collaboration.tex# new file: git_single_machine.tex# deleted: version_control.tex#

$ git commit -m "Merge bonn_ss_2013 into master."

[master d7f6692] Merge bonn_ss_2013 into master.

24

Making it easy to find specific versions

• Maybe I will have to teach some students old technology again?• Will need to go back to the commit where I replaced Subversion by Git• Dig through hundreds of commits?• Tags to the rescue

DAG of the project, early 2013

Tagging in Action

• Check out a specific version using the hash (git log is your friend)

$ git checkout 4da7639Note: checking out '4da7639'.

You are in 'detached HEAD' state. You can look around,make experimental changes and commit them, and you candiscard any commits you make in this state withoutimpacting any branches by performing another checkout.

If you want to create a new branch to retain commitsyou create, you may do so (now or later) by using -bwith the checkout command again. Example:

git checkout -b new_branch_name

HEAD is now at 4da7639... Added Sink book to SVN references.

25

Tagging in Action

• Tag the commit, find it easily via git tag

$ git tag last_version_svn -m "Last version with SVN as the VC system."

$ git checkout master

Previous HEAD position was 4da7639...Added Sink book to SVN references.

Switched to branch 'master'

$ git tag

last_version_svn

Tagging in Action

Checking out a tag is just an alias for the hash...

$ git checkout last_version_svn

You are in 'detached HEAD' state. You can look around,make experimental changes and commit them, and you candiscard any commits you make in this state withoutimpacting any branches by performing another checkout.

If you want to create a new branch to retain commitsyou create, you may do so (now or later) by using -bwith the checkout command again. Example:

git checkout -b new_branch_name

HEAD is now at 4da7639... Added Sink book to SVN references.

$ git checkout master

26

Frontends vs. backends

• Frontend = the program you interact with• Backend = the program doing the work under the hood• The command line / Git Bash is only one of many frontends (user inter-

faces) for the underlying program Git• See example of TortoiseGit (integrates in Windows Explorer), Google will

show you a myriad of other options

Using another Git frontend: TortoiseGit

Navigate to your project’s folder

Using another Git frontend: TortoiseGit

Right-click on the folder and select ”Git-commit...”

27

Using another Git frontend: TortoiseGit

Type the commit message, and click ”OK”

When everything stops working ...

• Don’t panic!!!– Situation from the last commit is always in the repository– So be sure to commit frequently– Always solve problems immediately so that you won’t loose much

information should you have to go back• Won’t happen much now -- but things become a bit tricky once we use

Git for collaboration

28

Vocabulary (recap)

• DAG• Working copy• Repository• Index / staging area• Commit• Branch• Tag

Vocabulary (recap)

• Merge• Head• Frontend / backend• Checkout (file)• Checkout (branch, tag, commit)

Avoid this

29

Reminder: How to get out of vim and otherrecipes

How to get out of vim

• Some commands (e.g. git commit without a message) will trigger a de-fault editor if user input is required. This happens to be vim in mostcases

• It is helpful to remember two things– If you just want to leave: Press Esc, followed by :q (a colon followed

by q for quit)– If you want to make changes to the opened file: Press i for insert

mode and make your changes. Then press Esc followed by :wq (forwrite & quit)

Using Sublime as default text editor

• Enter the following commands to make Sublime Text your default editor

$ export EDITOR='subl -w '

$ export TEXEDIT='subl'

$ alias subl="subl --new-window"

• Those settings will only be active for the current session.

• If you want to make them persistent, you can copy those terms into your.bash_profile / .bashrc in your home directory.

.bashrc and Git bash

• When using Git bash on Windows you can also use a .bashrc file• Create a .bashrc file under ~/.bashrc, where ~ denotes your home direc-

tory• ~ is usually your C:\Users\<your user name> folder. Typing echo ~ in

the git bash terminal will tell you what that folder is

30

License for the course material

• [Links to the full legal text and the source text for this page.] You arefree:

– to Share to copy, distribute and transmit the work– to Remix to adapt the work

Under the following conditions:

• Attribution You must attribute the work in the manner speci-fied by the author or licensor (but not in any way that suggeststhat they endorse you or your use of the work).

With the understanding that:

• Waiver Any of the above condition scan be waived if you getpermission from the copyright holder.

• Public Domain Where the work or any of its elements in thepublic domain under applicable law, that status is in no wayaffected by the license.

• Other Rights In no way are any of the following rights affectedby the license:

– Your fair dealing or fair use rights, or other applicable copy-right exceptions and limitations;

– The author’s moral rights;– Rights other persons may have either in the work itself or

in how the work is used, such as publicity or privacy rights.

Notice For any reuse or distribution, you must make clear to others the licenseterms of this work. The best way to do this is with a link to this web page.

31