Tutorial.tex 12.7 KB
Newer Older
LotteR93's avatar
LotteR93 committed
1
2
3
4
5
6
7
8
9
10
11
\documentclass[12pt,a4paper,reqno]{article}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{amsthm}
\usepackage[square, comma, numbers]{natbib}
\usepackage{enumitem}
\usepackage{tikz}
\usepackage{url}
\newcommand{\HRule}{\rule{\linewidth}{0.5mm}}
\usepackage{bm}
\usepackage[caption=false]{subfig}
12
\usepackage{hyperref}
LotteR93's avatar
LotteR93 committed
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

\usepackage{booktabs}
\usepackage{amsfonts}

\setcounter{secnumdepth}{3}
\setcounter{tocdepth}{3}


\newsavebox{\largestimage}

\usepackage{pdflscape}
\usepackage{afterpage}
\usepackage{caption}
\usepackage{longtable}

\setlength\parindent{0pt}
\renewcommand{\figurename}{\footnotesize \textsc{Figure}}

\usepackage{authblk}
\usepackage[top=2.5cm, bottom=2.5cm, left=2cm, right=2cm]{geometry}
\usepackage{fancyhdr}
%
\pagestyle{fancy}
%
\renewenvironment{abstract}{%
38
39
	\hfill\begin{minipage}{0.95\textwidth}
	\rule{\textwidth}{1pt}}
LotteR93's avatar
LotteR93 committed
40
41
42
43
{\par\noindent\rule{\textwidth}{1pt}\end{minipage}}
%
\makeatletter
\renewcommand\@maketitle{%
44
45
46
47
48
49
50
51
52
	\hfill
	\begin{minipage}{0.95\textwidth}
		\vskip 2em
		\let\footnote\thanks
		{\large \@title \par }
		\vskip 1.5em
		{\large \@author \par}
	\end{minipage}
	\vskip 1em \par
LotteR93's avatar
LotteR93 committed
53
54
55
56
57
58
59
60
61
62
63
64
65
66
}
\makeatother
%
\pagenumbering{gobble}

\renewcommand\Authfont{\fontsize{12}{14.4}\selectfont}
\renewcommand\Affilfont{\fontsize{12}{10.8}}

\renewcommand{\refname}{\fontsize{12}{15} \textbf{References}}

\usepackage{comment}

\usepackage[sc]{titlesec}
\titleformat{\section}
67
{\large\scshape\centering}{\thesection}{1em}{}
LotteR93's avatar
LotteR93 committed
68
\titleformat{\subsection}
69
{\normalfont\scshape}{\thesubsection}{1em}{}
LotteR93's avatar
LotteR93 committed
70
\titleformat{\subsubsection}
71
{\normalfont\scshape\itshape \centering}{\thesubsubsection}{1em}{}
72

LotteR93's avatar
LotteR93 committed
73
74
75
76
77
\pagestyle{empty}


\begin{document}

78
79
To start with:
\hbadness=10000
LotteR93's avatar
LotteR93 committed
80
\begin{itemize}
81
	\item Refresher colloquium + SmartGit installation.
82
83
84
85
86
87
	\item Tell everyone to find a partner.
\end{itemize}

Walkthrough 1:
\hbadness=10000
\begin{itemize}
Jens Wehner's avatar
Jens Wehner committed
88
	\item Log in on GitLab \url{https://GitLab.tue.nl/}.\\
89
90
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/loginGitLab.png}

91
92
	\item Download and install SmartGit from \url{https://www.syntevo.com/smartgit/download/}.

93
	\item Set up SmartGit.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
94
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/setup1.PNG}\\
95
		Start SmartGit and tick the terms of agreement (after reading them, of course) and select ''Non-commercial use only (most features, no support).\\
Jens Wehner's avatar
Jens Wehner committed
96
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/setup2.PNG}\\
97
		Wait for the 10 seconds and tick both of the boxes.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
98
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/setup3.PNG}\\
99
100
101
		Enter a suitable user name and email.
		\clearpage

Jens Wehner's avatar
Jens Wehner committed
102
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/setup4.PNG}\\
103
		Keep ''Use SmartGit as SSH client'' selected (unless you know what you're doing).\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
104
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/setup5.PNG}\\
105
106
107
		Select ''Log History'' (unless you prefer the former).
		\clearpage

Jens Wehner's avatar
Jens Wehner committed
108
	\item \textit{Initialise} a new project on GitLab \url{https://GitLab.tue.nl/}.\\[5pt]
109
110
111
112
113
114
115
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/makeProjectGitLab1.png}\\
		Click on ''New project''.\\[5pt]
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/makeProjectGitLab2.png}\\
		Make sure that ''Blank project'' is highlighted, then enter a suitable name and make sure to select ''Initialize repository with a README''.\clearpage

	\item \textit{Clone} the project using SmartGit.\\[3pt]
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/firstStart.PNG}\\
116
		Select ''Clone existing repository'' (if the window does not pop up got go ''Repository'' $\rightarrow$ ''Clone'').\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
117
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/configRemote0.png}\\
118
		Go back to \url{https://gitlab.tue.nl/} and click on the project and the blue clone button. Copy the HTTPS URL.
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
		\clearpage

		\includegraphics[width=\linewidth]{Figs/tutorialPart1/configRemote1.PNG}\\
		Paste it in the Clone window.\\[5pt]
		\includegraphics[scale=1]{Figs/tutorialPart1/configRemote2.PNG}\\
		Enter a master password for storing the authentication credentials (in principal one is not needed, but strongly recommended).\\
		\clearpage

		\includegraphics[scale=1]{Figs/tutorialPart1/configRemote3.PNG}\\
		Enter your TU/e credentials (and optionally store the password).\\[5pt]
		\includegraphics[width=0.85\linewidth]{Figs/tutorialPart1/configRemote4.PNG}\\
		Keep everything ticked.\\[5pt]
		\includegraphics[width=0.85\linewidth]{Figs/tutorialPart1/configRemote5.PNG}\\
		Select a suitable directory and hit ''clone''.
		\clearpage

	\item Add a text file to the \textit{root folder} of the repository.\\
136
137
		Platform specific - anything will do and you can create a new one with some text in it.\\
		Note that Microsoft files are binary files, and as such they are not suitable for git! (i.e.\ no Word documents, PowerPoint presentations, etc)
138
139
140
141
142
143
144
145

	\item \textit{Stage} the new file.\\
		\includegraphics[width=0.8\linewidth]{Figs/tutorialPart1/stageButton.PNG}%
		\includegraphics[width=0.2\linewidth]{Figs/tutorialPart1/stageContext.PNG}\\
		Click on the ''Stage'' button in the toolbar or use the context menu entry.\\
		The former will stage \textit{all} of the local changes, whilst the latter lets you be more gradual - in this case the effect will of course be the same.

	\item Check if the file is on GitLab.\\
Jens Wehner's avatar
Jens Wehner committed
146
		Go to \url{https://GitLab.tue.nl/} and click on the project.\\
147
148
149
		The file is not there.

	\item \textit{Commit} the file with a commit message.\\
150
		Go back to SmartGit.\\[5pt]
151
152
153
154
155
156
157
158
159
160
161
		\includegraphics[width=0.8\linewidth]{Figs/tutorialPart1/commitButton.PNG}%
		\includegraphics[width=0.2\linewidth]{Figs/tutorialPart1/commitContext.PNG}\\
		Click on the ''Commit'' button in the toolbar or use the context menu entry.\\
		\includegraphics[width=0.8\linewidth]{Figs/tutorialPart1/commit2.PNG}\\
		Enter a suitable commit message.\\[5pt]

		\includegraphics[width=\linewidth]{Figs/tutorialPart1/commit3.PNG}\\
		Now we can see the new commit that we just made.\\
		Note that the ''Modification'' value changed from ''Untracked'' to ''Added''.

	\item Check if file is on GitLab.\\
Jens Wehner's avatar
Jens Wehner committed
162
		Go to \url{https://GitLab.tue.nl/} and click on the project.\\
163
164
165
166
167
		The file is not there.

	\item \textit{Push} the staged commits to the \textit{remote repository}.\\
		Go back to SmartGit.\\[5pt]
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/firstPush1.PNG}\\
168
		Click the upwards facing arrow which says ''Push'', and note that the green icon which says ''master'' fits snugly into the yellow ''origin/master'' one - this indicates parity between the \textit{remote} (origin/master) and \textit{local} (master) \textit{repositories}.\\
169
170
171
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/firstPush3.PNG}

	\item Check GitLab once again.\\
Jens Wehner's avatar
Jens Wehner committed
172
		Go to \url{https://GitLab.tue.nl/} and click on the project.\\
173
		This time the text file is indeed available.
Kronberg, V.C.E.'s avatar
Kronberg, V.C.E. committed
174
		\clearpage
Jens Wehner's avatar
Jens Wehner committed
175

Kronberg, V.C.E.'s avatar
Kronberg, V.C.E. committed
176
177
		\item \textit{Ignoring} files. Quite often you will be in a situation where you have temporary files (e.g.\ when typesetting \LaTeX documents), which need not be synced to the remote repository.
		You can tell Git to simply ignore these files by marking them and choosing ignore.
Jens Wehner's avatar
Jens Wehner committed
178
\\[5pt]
Kronberg, V.C.E.'s avatar
Kronberg, V.C.E. committed
179
		\includegraphics[width=\linewidth]{Figs/tutorialPart1/ignore.png}\\
180
181
182
183
184
\end{itemize}

This ends the first walkthrough.
Before the break, you should all try to
\begin{itemize}
185
186
187
188
189
	\item Create one or several new text files.
	\item Perform a couple of \textit{commits}.
	\item \textit{Stage} multiple files and several changes at once.
	\item \textit{Push} a few times to the remote repository.
	\item \textit{Revert} an old commit.
190
191
192
193
194
195
196
\end{itemize}

For those who want a challenge, try to
\begin{itemize}
	\item \textit{Unstage} a staged commit, change some things then re-stage the new changes and commit.
	\item \textit{Checkout} an old commit.
	\item \textit{Reset} the repository to an older commit.
LotteR93's avatar
LotteR93 committed
197
198
\end{itemize}

199
200
\vfill
\textbf{BREAK}
LotteR93's avatar
LotteR93 committed
201

202
\clearpage
LotteR93's avatar
LotteR93 committed
203
Tutorial part 2:
Jens Wehner's avatar
Jens Wehner committed
204
Branches are very useful if you want to try out different approaches. Although they are most useful when working with others, even alone it is good if you want to explore a new idea. 
205
\hbadness=10000
LotteR93's avatar
LotteR93 committed
206
\begin{itemize}
Jens Wehner's avatar
Jens Wehner committed
207
208
209
210
211
212
213
214
215
\item First use your repo or make a new one and make 3-4 commits on the master branch. \\[5pt]
	\includegraphics[width=\linewidth]{Figs/tutorialPart2/before.png}\\
\item Create branch (Branch$\rightarrow$Add Branch). Depending on what you clicked after naming the branch, you are either still on master or are already on the new branch. 
With (Branch$\rightarrow$Check out$\rightarrow$)or you simply click on the branch name in the bottom left corner. Make sure you are on your new branch. \\[5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/checkoutbranch.png}\\
\item Edit a file and create a new commit on the new branch. Maybe 1-2 commits.\\[5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/addtofeaturebranch.png}\\
\item Checkout the master branch again. All the changes from before are now gone (i.e. they are on the other branch). Click on the tickmark next to the branchname in the bottom left to make it visible. \\[5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/checkout_master.png}\\
Jens Wehner's avatar
Jens Wehner committed
216
\item Make 1 or 2 commits on the master branch. 
Jens Wehner's avatar
Jens Wehner committed
217
218
219
220
\item Your branches should look like this now.\\[5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/branchbeforemerge.png}\\
\item Right click on your branch and select merge.  \\[5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/duringmerge.png}\\
Jens Wehner's avatar
Jens Wehner committed
221
222
223
224
225
226
227
\item You have a merge conflict between the two branches, because you modfied the same part of the file in both branches. You can use your text editor to choose the lines you want. But there is a better way..
\item Double click on the file which has the conflict.  \\[5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/conflict_resolve2.png}\\
\item A new window opens which displays three times the same file. You have the two branches on the sides and the result in the middle.  \\[5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/conflict_resolve3.png}\\
\item Use the "Take Left","Take right" or any of the other options to select what should be taken. You can also just write into the file in the middle. Click "save" afterwards.
\item Stage your changes and commit. Your branches should look like this now.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
228
\includegraphics[width=\linewidth]{Figs/tutorialPart2/merged.png}\\
LotteR93's avatar
LotteR93 committed
229
\end{itemize}
230

Jens Wehner's avatar
Jens Wehner committed
231
Collaborative development. Now your partner becomes very useful, finally. You will learn now how to synchronize development with others. This builds heavily on branches and merging.
232
\hbadness=10000
LotteR93's avatar
LotteR93 committed
233
\begin{itemize}
Jens Wehner's avatar
Jens Wehner committed
234
\item \textit{Create} a new group on GitLab \url{https://GitLab.tue.nl/}.Groups$\rightarrow$your Groups\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
235
236
237
	\includegraphics[width=\linewidth]{Figs/tutorialPart2/createGroup.png}\\
	Click on ''New group''.\\[5pt]
Groups are not necessary to work on a shared project. So you can also skip this step and add people directly to the project. 
Jens Wehner's avatar
Jens Wehner committed
238
\item \textit{Add} yourself and your partner to the group \url{https://GitLab.tue.nl/}.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
239
	\includegraphics[width=\linewidth]{Figs/tutorialPart2/addpeopletogroup.png}\\
Jens Wehner's avatar
Jens Wehner committed
240
	Click on ''New group''.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
241
\item \textit{Create} a new repo on GitLab \url{https://GitLab.tue.nl/}.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
242
243
244
	\includegraphics[width=\linewidth]{Figs/tutorialPart2/createproject.png}\\
	Click on ''New project''.\\[5pt]
You can also use an old repository from earlier. 
Jens Wehner's avatar
Jens Wehner committed
245
\item \textit{Create} a new repo on GitLab \url{https://GitLab.tue.nl/}.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
246
\item If you did not create a group you can add people to the project now.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
247
248
249
	\includegraphics[width=\linewidth]{Figs/tutorialPart2/addpeopletoproject.png}\\
	Click on ''New project''.\\[5pt]
\item Both clone the repository and make changes to the same file on your computer. Push the changes and see what happens.
Jens Wehner's avatar
Jens Wehner committed
250
\item One of you will not be able to push your changes. Pull the up to date version from the server and merge locally then push the changes to the server.
Jens Wehner's avatar
Jens Wehner committed
251
\item Instead you can also create your own branches push them to GitLab and then merge them into the main branch via a Merge Request. So you do not always have to merge before pushing to GitLab.
Jens Wehner's avatar
Jens Wehner committed
252
253
254
255
 \\[5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/merge_request_start.png}\\ [5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/merge_request_2.png}\\ [5pt]
\includegraphics[width=\linewidth]{Figs/tutorialPart2/submit_merge_request.png}\\ [5pt]
Jens Wehner's avatar
Jens Wehner committed
256
\item If you are bored create an issue for the project and assign your colleague.\\[5pt]
Jens Wehner's avatar
Jens Wehner committed
257
\includegraphics[width=\linewidth]{Figs/tutorialPart2/createIssue.png}\\ 
LotteR93's avatar
LotteR93 committed
258
259
260
\end{itemize}

Tips on good practices
simokron's avatar
simokron committed
261
262
\begin{itemize}
	\item Always use instructive commit messages!
Jens Wehner's avatar
Jens Wehner committed
263
\item Only put source files under version control, i.e. the .tex and .bib files not the .aux .log and certainly not the .pdf
simokron's avatar
simokron committed
264
	\item Make many small commits instead of one large one!
Jens Wehner's avatar
Jens Wehner committed
265
\item Do not push or commit to master, make a separate branch and make a merge request. It is much kinder to others you work with. 
simokron's avatar
simokron committed
266
\end{itemize}
LotteR93's avatar
LotteR93 committed
267
268
269
270
271




\end{document}