This repository has been archived by the owner on Oct 6, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 2
/
git.html
805 lines (706 loc) · 32.6 KB
/
git.html
1
2
3
4
5
6
7
8
9
10
11
12
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />
<title>Git</title>
<script src="site_libs/jquery-3.6.0/jquery-3.6.0.min.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="site_libs/bootstrap-3.3.5/css/bootstrap.min.css" rel="stylesheet" />
<script src="site_libs/bootstrap-3.3.5/js/bootstrap.min.js"></script>
<script src="site_libs/bootstrap-3.3.5/shim/html5shiv.min.js"></script>
<script src="site_libs/bootstrap-3.3.5/shim/respond.min.js"></script>
<style>h1 {font-size: 34px;}
h1.title {font-size: 38px;}
h2 {font-size: 30px;}
h3 {font-size: 24px;}
h4 {font-size: 18px;}
h5 {font-size: 16px;}
h6 {font-size: 12px;}
code {color: inherit; background-color: rgba(0, 0, 0, 0.04);}
pre:not([class]) { background-color: white }</style>
<script src="site_libs/jqueryui-1.11.4/jquery-ui.min.js"></script>
<link href="site_libs/tocify-1.9.1/jquery.tocify.css" rel="stylesheet" />
<script src="site_libs/tocify-1.9.1/jquery.tocify.js"></script>
<script src="site_libs/navigation-1.1/tabsets.js"></script>
<link href="site_libs/highlightjs-9.12.0/default.css" rel="stylesheet" />
<script src="site_libs/highlightjs-9.12.0/highlight.js"></script>
<link href="site_libs/font-awesome-5.1.0/css/all.css" rel="stylesheet" />
<link href="site_libs/font-awesome-5.1.0/css/v4-shims.css" rel="stylesheet" />
<link rel="shortcut icon" href="images/duck_guidance.png"/>
<script>
// Define dataLayer and the gtag function.
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
// Default ad_storage to 'denied' as a placeholder
// Determine actual values based on your own requirements
gtag('consent', 'default', {
'ad_storage': 'denied',
'analytics_storage': 'granted'
});
</script>
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-KBJCBD114T"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
/*
The tracking number below MUST be replaced with a unique number, contact the statistics development team to set this up.
*/
gtag('config', 'G-KBJCBD114T');
</script>
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>
<style type="text/css">code{white-space: pre;}</style>
<script type="text/javascript">
if (window.hljs) {
hljs.configure({languages: []});
hljs.initHighlightingOnLoad();
if (document.readyState && document.readyState === "complete") {
window.setTimeout(function() { hljs.initHighlighting(); }, 0);
}
}
</script>
<link rel="stylesheet" href="images/acalat_theme.css" type="text/css" />
<style type = "text/css">
.main-container {
max-width: 940px;
margin-left: auto;
margin-right: auto;
}
img {
max-width:100%;
}
.tabbed-pane {
padding-top: 12px;
}
.html-widget {
margin-bottom: 20px;
}
button.code-folding-btn:focus {
outline: none;
}
summary {
display: list-item;
}
details > summary > p:only-child {
display: inline;
}
pre code {
padding: 0;
}
</style>
<style type="text/css">
.dropdown-submenu {
position: relative;
}
.dropdown-submenu>.dropdown-menu {
top: 0;
left: 100%;
margin-top: -6px;
margin-left: -1px;
border-radius: 0 6px 6px 6px;
}
.dropdown-submenu:hover>.dropdown-menu {
display: block;
}
.dropdown-submenu>a:after {
display: block;
content: " ";
float: right;
width: 0;
height: 0;
border-color: transparent;
border-style: solid;
border-width: 5px 0 5px 5px;
border-left-color: #cccccc;
margin-top: 5px;
margin-right: -10px;
}
.dropdown-submenu:hover>a:after {
border-left-color: #adb5bd;
}
.dropdown-submenu.pull-left {
float: none;
}
.dropdown-submenu.pull-left>.dropdown-menu {
left: -100%;
margin-left: 10px;
border-radius: 6px 0 6px 6px;
}
</style>
<script type="text/javascript">
// manage active state of menu based on current page
$(document).ready(function () {
// active menu anchor
href = window.location.pathname
href = href.substr(href.lastIndexOf('/') + 1)
if (href === "")
href = "index.html";
var menuAnchor = $('a[href="' + href + '"]');
// mark the anchor link active (and if it's in a dropdown, also mark that active)
var dropdown = menuAnchor.closest('li.dropdown');
if (window.bootstrap) { // Bootstrap 4+
menuAnchor.addClass('active');
dropdown.find('> .dropdown-toggle').addClass('active');
} else { // Bootstrap 3
menuAnchor.parent().addClass('active');
dropdown.addClass('active');
}
// Navbar adjustments
var navHeight = $(".navbar").first().height() + 15;
var style = document.createElement('style');
var pt = "padding-top: " + navHeight + "px; ";
var mt = "margin-top: -" + navHeight + "px; ";
var css = "";
// offset scroll position for anchor links (for fixed navbar)
for (var i = 1; i <= 6; i++) {
css += ".section h" + i + "{ " + pt + mt + "}\n";
}
style.innerHTML = "body {" + pt + "padding-bottom: 40px; }\n" + css;
document.head.appendChild(style);
});
</script>
<!-- tabsets -->
<style type="text/css">
.tabset-dropdown > .nav-tabs {
display: inline-table;
max-height: 500px;
min-height: 44px;
overflow-y: auto;
border: 1px solid #ddd;
border-radius: 4px;
}
.tabset-dropdown > .nav-tabs > li.active:before {
content: "";
font-family: 'Glyphicons Halflings';
display: inline-block;
padding: 10px;
border-right: 1px solid #ddd;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open > li.active:before {
content: "";
border: none;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open:before {
content: "";
font-family: 'Glyphicons Halflings';
display: inline-block;
padding: 10px;
border-right: 1px solid #ddd;
}
.tabset-dropdown > .nav-tabs > li.active {
display: block;
}
.tabset-dropdown > .nav-tabs > li > a,
.tabset-dropdown > .nav-tabs > li > a:focus,
.tabset-dropdown > .nav-tabs > li > a:hover {
border: none;
display: inline-block;
border-radius: 4px;
background-color: transparent;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open > li {
display: block;
float: none;
}
.tabset-dropdown > .nav-tabs > li {
display: none;
}
</style>
<!-- code folding -->
<style type="text/css">
#TOC {
margin: 25px 0px 20px 0px;
}
@media (max-width: 768px) {
#TOC {
position: relative;
width: 100%;
}
}
@media print {
.toc-content {
/* see https://github.com/w3c/csswg-drafts/issues/4434 */
float: right;
}
}
.toc-content {
padding-left: 30px;
padding-right: 40px;
}
div.main-container {
max-width: 1200px;
}
div.tocify {
width: 20%;
max-width: 260px;
max-height: 85%;
}
@media (min-width: 768px) and (max-width: 991px) {
div.tocify {
width: 25%;
}
}
@media (max-width: 767px) {
div.tocify {
width: 100%;
max-width: none;
}
}
.tocify ul, .tocify li {
line-height: 20px;
}
.tocify-subheader .tocify-item {
font-size: 0.90em;
}
.tocify .list-group-item {
border-radius: 0px;
}
</style>
</head>
<body>
<div class="container-fluid main-container">
<!-- setup 3col/9col grid for toc_float and main content -->
<div class="row">
<div class="col-xs-12 col-sm-4 col-md-3">
<div id="TOC" class="tocify">
</div>
</div>
<div class="toc-content col-xs-12 col-sm-8 col-md-9">
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-bs-toggle="collapse" data-target="#navbar" data-bs-target="#navbar">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">Statistics Production Guidance</a>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Learning and development
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="l+d.html">General resources</a>
</li>
<li>
<a href="sql.html">SQL</a>
</li>
<li>
<a href="r.html">R</a>
</li>
<li>
<a href="git.html">Git</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Creating statistics
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="rap.html">Processes and RAP</a>
</li>
<li>
<a href="rap_managers.html">RAP for managers</a>
</li>
<li>
<a href="ud.html">Open data standards</a>
</li>
<li>
<a href="cd.html">Writing and visualising</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Publishing statistics
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="pub.html">How to publish</a>
</li>
<li>
<a href="ees.html">Using EES</a>
</li>
<li>
<a href="examples.html">EES examples</a>
</li>
<li>
<a href="dashboards.html">Dashboards</a>
</li>
<li>
<a href="embedded-charts.html">Embedded R-Shiny charts</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Understanding users
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="user_eng.html">User engagement</a>
</li>
<li>
<a href="user_an.html">EES analytics</a>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li>
<a href="mailto:statistics.development@education.gov.uk">
<span class="fa fa-envelope"></span>
</a>
</li>
</ul>
</div><!--/.nav-collapse -->
</div><!--/.container -->
</div><!--/.navbar -->
<div id="header">
<h1 class="title toc-ignore">Git</h1>
</div>
<p class="text-muted">
Guidance and tips for version control with Git
</p>
<hr />
<div id="what-is-it" class="section level2">
<h2>What is it</h2>
<hr />
<p>It is a version control software. It is by far the best of its kind and is widely used by software developers and data scientists.</p>
<hr />
</div>
<div id="what-is-it-for" class="section level2">
<h2>What is it for</h2>
<hr />
<p>Git is a version control software that tracks changes to files within a folder that you assign Git to track. It works best with plain text files such as flat data files, code scripts and markdown documents. These folders are known as repositories and can be held and managed securely in a central online place such as GitHub (best for public), GitLab (can be good for either public or private) and Azure DevOps (best for private). We can easily mirror our Azure DevOps repositories in the DfE Analytical Services area on <a href="https://github.com/dfe-analytical-services" target="_blank" rel="noopener noreferrer">GitHub</a>.</p>
<p>It is widely used across DfE and integrates neatly with our use of Azure DevOps, as well as being the current leading version control software in the world of coding with over <a href="https://insights.stackoverflow.com/survey/2018#work-_-version-control" target="_blank" rel="noopener noreferrer">87% of 74,298 stack overflow users using it</a>.</p>
<hr />
</div>
<div id="how-to-get-it" class="section level2">
<h2>How to get it</h2>
<hr />
<p>Download it from the <a href="https://git-scm.com/downloads" target="_blank" rel="noopener noreferrer">Git website</a>.</p>
<p>Git doesn’t have an IDE, instead it will either integrate with your current IDE such as RStudio or Visual Studio Code, or run in the command line.</p>
<p>When you first try to use Git you may be prompted for a GitHub username and password, if this happens you should generate a <a href="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token">Personal Access Token (PAT)</a> and use this as your password.</p>
<hr />
</div>
<div id="best-places-to-start" class="section level2">
<h2>Best places to start</h2>
<hr />
<!-- worth us linking to how to create a git repo for azure and for github once our dashboard guidance is out? -->
<ul>
<li><p>If you’re new to Git and are unsure of what it does, then take a look through these <a href="https://speakerdeck.com/alicebartlett/git-for-humans" target="_blank" rel="noopener noreferrer">Git for humans slides</a></p></li>
<li><p>David Sands’ guide to <a href="https://web.microsoftstream.com/video/cc21863d-a6f8-4b53-b66c-1dfd012b8d79?list=studio" target="_blank" rel="noopener noreferrer">getting started with Git</a> is a helpful place to start.</p></li>
<li><p><a href="https://educationgovuk.sharepoint.com/sites/sarpi/g/WorkplaceDocuments/Forms/AllItems.aspx?id=%2Fsites%2Fsarpi%2Fg%2FWorkplaceDocuments%2FInducation%20learning%20and%20career%20development%2FCoffee%20and%20Coding%2F190220%5Fdavid%5Fgoeeygit%2Fgooey%5Fgit%2Ehtml&parent=%2Fsites%2Fsarpi%2Fg%2FWorkplaceDocuments%2FInducation%20learning%20and%20career%20development%2FCoffee%20and%20Coding%2F190220%5Fdavid%5Fgoeeygit" target="_blank" rel="noopener noreferrer">Gooey Git</a> by David Sands, provides a very neat overview of using git with R.</p></li>
</ul>
<hr />
</div>
<div id="how-to-work-with-git" class="section level2">
<h2>How to work with git</h2>
<hr />
<div id="git-bash" class="section level3">
<h3>Git Bash</h3>
<hr />
<p>Git Bash allows you to run git commands without opening another IDE. You’d often need to use Git Bash to set your user settings, amend your proxy settings and clone repositories.</p>
<hr />
</div>
<div id="git-with-rstudio" class="section level3">
<h3>Git with RStudio</h3>
<hr />
<p>Git with R studio is a neat user interface for git. You don’t need to use any git bash commands, and everything is done using point and click. This is useful for day-to-day version control, but does not support the full functionality of git.</p>
<p>However, you can still run the full suite of git commands by simply typing them in the “Terminal” of RStudio.</p>
<hr />
</div>
</div>
<div id="quick-reference-lookup" class="section level2">
<h2>Quick reference lookup</h2>
<hr />
<ul>
<li>GitHub have created a <a href="https://education.github.com/git-cheat-sheet-education.pdf" target="_blank" rel="noopener noreferrer">cheat sheet for git commands</a>.</li>
</ul>
<hr />
</div>
<div id="other-resources" class="section level2">
<h2>Other resources</h2>
<hr />
<ul>
<li><p>Avison Ho and Linda Bennett gave this coffee and coding presentation on <a href="https://github.com/avisionh/SQL-Titbits/wiki/User-Guide:-SQL-x-Git-Version-Control" target="_blank" rel="noopener noreferrer">version controlling SQL with Git</a>.</p></li>
<li><p><a href="https://happygitwithr.com/big-picture.html" target="_blank" rel="noopener noreferrer">Happy Git</a> is a useful (though detailed) guide to setting up and using git.</p></li>
<li><p>Adam Robinson and Zach Waller have produced <a href="https://dfe-analytical-services.github.io/vsts-for-analysis/" target="_blank" rel="noopener noreferrer">guidance for how to use git in Azure DevOps (formally VSTS)</a>, which gives a detailed guide on how to use version control software in DfE analysis.</p></li>
<li><p>While also mentioned above as a resource for learning R, chapter 6 of ESFA’s <a href="https://rsconnect/rsc/esfa-r-training/git-building-intuition.html" target="_blank" rel="noopener noreferrer">guide to R and Git</a> is also worth looking at for Git alone.</p></li>
<li><p>Microsoft have produced documentation on <a href="https://docs.microsoft.com/en-us/azure/devops/user-guide/code-with-git?view=azure-devops" target="_blank" rel="noopener noreferrer">using Git</a> within <a href="https://docs.microsoft.com/en-us/azure/devops/user-guide/what-is-azure-devops?view=azure-devops" target="_blank" rel="noopener noreferrer">AzureDevOps</a>.</p></li>
<li><p>For those wanting to go deeper into understand the variety of git commands and what they do, there is a great <a href="https://dev.to/lydiahallie/cs-visualized-useful-git-commands-37p1" target="_blank" rel="noopener noreferrer">online visual resource</a>.</p></li>
<li><p>We also have a number of helpful sections on using git in practice at the end of our <a href="rap.html#Build_capability_within_the_team" target="_blank" rel="noopener noreferrer">RAP page</a>.</p></li>
</ul>
<hr />
</div>
<div id="tips-for-using-git" class="section level2">
<h2>Tips for using Git</h2>
<hr />
<div id="branches" class="section level3">
<h3>Branches</h3>
<hr />
<p>David Sands has produced a very helpful video on how to use branches in git, which also covers how to tackle merge conflicts if and when they arise:</p>
<div align="center">
<iframe width="640" height="360" src="https://web.microsoftstream.com/embed/video/6b56e063-294c-4103-b8b7-aacc4f1c9169?autoplay=false&showinfo=true" allowfullscreen style="border:none;">
</iframe>
</div>
<p>When you create a git project, it will automatically create a “main” (sometimes “master”) branch for you. This is where code that has been QA’d and you are happy with should sit.</p>
<ul>
<li>It is good practice to have at least one other branch, we tend to call it “development”. This is the branch where you will be doing most of your work. To open a new branch, navigate to “branches” and click on the blue box highlighted below</li>
</ul>
<p><img src="images/new_branch_git.png" /><!-- --></p>
<ul>
<li><p>Having two separate branches means that if anything goes wrong in the “development” branch, the “main” or “master” branch is still unaffected and runs without issue. This lets you test and QA the code more thoroughly before merging into your main branch.</p></li>
<li><p>When working on your project, make sure that you are in the right branch. You can check this by navigating to the “Git” tab in RStudio as demonstrated below.</p></li>
</ul>
<p><img src="images/select_branch.png" /><!-- --></p>
<hr />
</div>
<div id="commits" class="section level3">
<h3>Commits</h3>
<hr />
<p>Once you are happy with changes and want them to be in the latest version of your branch for all of your team to see, you can push “commits” up.</p>
<ul>
<li>When you make a change to a file, this will pop up in the “Git” window of your R console. Select the files you want to commit by ticking the “staged” box next to them.</li>
</ul>
<p><img src="images/git_stage.png" /><!-- --></p>
<ul>
<li>This will bring up a new window. Add a comment describing your additions/changes, and click commit. You will see all the staged files disappear. Then click “Push” to push the committed files up to the online repository for all to use.</li>
</ul>
<p><img src="images/git_push.png" /><!-- --></p>
<ul>
<li>When another member of your team makes a commit and you want to pull this into your local area to check and work off the latest version, click on the blue “pull” button.</li>
</ul>
<p><img src="images/pull_git.png" /><!-- --></p>
<p>Committing regularly is strongly recommended as each commit is a saved point in time that you can easily roll back to if needed. If you want to know more about how to do this, see the <a href="#reverting-a-commit">reverting a commit</a> section below.</p>
<hr />
</div>
<div id="pull-requests" class="section level3">
<h3>Pull requests</h3>
<hr />
<p>When you have got to a place with the code and your committed changes where you are happy for it to be QA’d, you can open a pull request. This gives your team a chance to QA your changes before merging the branches together.</p>
<ul>
<li><p>Navigate to “Pull Requests” in the “Repos” tab of Azure DevOps and click the blue “New pull request” button.</p></li>
<li><p>This will take you to a new window. Here, you can add:</p>
<ul>
<li>Title, tell your team what has changed</li>
<li>Description, tell your reviewer what they should check</li>
<li>Reviewers, add multiple if needed.</li>
</ul></li>
<li><p>As a reviewer, to approve a pull request, follow the link in your email and click “approve” in the blue box. When all reviewers are happy for this to be the new master branch, click “complete”.</p></li>
</ul>
<p>Creating pull requests in GitHub follows a broadly similar process and should be intuitive from the above steps for Azure DevOps.</p>
<hr />
</div>
<div id="merging-a-branch-into-another-one" class="section level3">
<h3>Merging a branch into another one</h3>
<hr />
<p>If you want to merge a branch into another without doing a full pull request, you can do this using a terminal.</p>
<p>This may happen if you are working on a feature branch, and want to merge the latest changes to the master branch back into your feature branch before opening a PR to master with your own changes. Often this can let you deal with nasty conflicts up front, or allow you to keep working on your feature but update to have something new that’s on master.</p>
<p>Start off by checking out your desired target branch - <code>git checkout mybranch</code>. Then merge in the branch you want (e.g. master) - <code>git merge master</code>.</p>
<hr />
</div>
<div id="cherry-picking" class="section level3">
<h3>Cherry picking</h3>
<hr />
<p>If you want to cherry pick specific commits for PR, you can do this by cherry picking the commits you want to use, and creating a new branch that has only those new commits that you want.</p>
<p>To start off you’ll need to identify the commits you want. In the terminal, run <code>git log --oneline</code> to get a log of commits for your current branch, use <code>git log --online BRANCHNAME</code> to specific the branch for the log. This gives a list of commit hashes and messages (<a href="https://stackoverflow.com/questions/43763896/whats-the-difference-between-commit-id-and-sha1-hash-in-git" target="_blank" rel="noopener noreferrer">stackoverflow response defining git hashes and commmit ID’s</a>). You can press enter to get more commits, or q to quit</p>
<p>Then go to the branch you want the commit to appear on and cherry pick your commits. Often, if this is to hop around something on a development to master pr, you would create a second development branch, cherry pick commits to there, and then PR that to master and delete the branch after merging.</p>
<p>On the branch you want to PR (i.e. your copy of a development branch purely for merging only cherry picked commits) run <code>git cherry-pick COMMITHASH</code> to add the specified commit, or <code>git cherry-pick HASH1^..HASH4</code> for a specified list of commits (inclusive).</p>
<p>Happy days!</p>
<hr />
</div>
<div id="visualising-your-tree" class="section level3">
<h3>Visualising your tree</h3>
<hr />
<p>You can use <code>gitk --all</code> to visualise a tree of all previous commits up to this point.</p>
<p><img src="images/gitk.png" /><!-- --></p>
<hr />
</div>
<div id="getting-commit-ids" class="section level3">
<h3>Getting commit IDs</h3>
<hr />
<p>Commit IDs are the way Git identifies unique commits. They’re really helpful if you ever need to revert back to a previous commit if you’ve made a mistake.</p>
<p>There are lots of different ways to find out commit IDs:</p>
<ul>
<li><p>Visit the repo in Azure Devops and go to the commit of interest. At the top of the page there is a commit ID you can copy.</p></li>
<li><p>Navigate to the repo in your file explorer, then open up Git Bash and type</p></li>
</ul>
<p><code>git log --pretty=format:"%h - %an, %ar : %</code></p>
<p>OR</p>
<p><code>git log --pretty=oneline</code></p>
<p>There are a number of customisable versions of this, more information is available on the <a href="https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History" target="_blank" rel="noopener noreferrer">Git website</a>.</p>
<hr />
</div>
<div id="reverting-a-commit" class="section level3">
<h3>Reverting a commit</h3>
<hr />
<p>Made a mistake and need to revert? No problem! Reverting commits in git creates a new commit reversing your accidental commits, bringing you back to an earlier point in your branch.</p>
<p>For rolling back on a branch, you should revert any changes so that you’re not erasing history others might have pulled/cloned. E.g. If you want to revert the last 3 commits on master:</p>
<p><code>git revert --no-commit master~3..master</code></p>
<p>The no commit argument means that it just makes the reverts locally, and you can then commit them all as a single revert commit. If you don’t use <code>--no-commit</code> then it will start doing individual revert commits for you for each commit you’re reverting.</p>
<p>You can also revert back to a particular commit ID:</p>
<ol style="list-style-type: decimal">
<li>Navigate to the repo in your file explorer, then open up Git Bash and type :</li>
</ol>
<p><code>git revert [PASTE COMMIT ID HERE]</code></p>
<ol start="2" style="list-style-type: decimal">
<li><p>This opens up a window that asks you to write a commit message. You can skip this step as it automatically writes a revert message for you. Enter <code>:wq</code> which quits the writer window.</p></li>
<li><p>You can now push these changes to Azure Devops by entering <code>git push</code> into the git window</p></li>
</ol>
<hr />
</div>
<div id="tagging-release-versions" class="section level3">
<h3>Tagging release versions</h3>
<hr />
<!-- future best practice?! -->
<p>It can be useful to tag specific commits or releases at key points in time. For us a common example will be each publication cycle, to tag the version of the code used to process data for a particular release or amendment.</p>
<p>Guidance on how to tag releases using git can be found on the draft version of the <a href="https://best-practice-and-impact.github.io/qa-of-code-guidance/version_control.html#releases-tagging" target="_blank" rel="noopener noreferrer">BPI code guidance</a></p>
<hr />
</div>
<div id="fix-cannot-resolve-proxy" class="section level3">
<h3>Fix: cannot resolve proxy</h3>
<hr />
<p>If you get this error when trying to pull / push to a repository from a DfE laptop:</p>
<p><code>fatal: unable to access 'https://dfe-gov-uk.visualstudio.com/stats-development/_git/ees-analytics-new/': Could not resolve proxy: mwg.proxy.ad.hq.dept</code></p>
<p>Then try running the following git command to clear the proxy settings in your git config file:</p>
<p><code>git config --global --unset http.proxy</code></p>
<hr />
</div>
<div id="cleaning-up-local-branches" class="section level3">
<h3>Cleaning up local branches</h3>
<hr />
<p>Essentially this finds all merged (old) branches, makes sure to not include master or development (can rename or add more if appropriate) and then runs those branches through the delete command. To be safe, run the first two thirds first, to print out the list of what you’ll be deleting:</p>
<p><code>git branch --merged | egrep -v "(^\*|master|development)"</code></p>
<p>Then if you’re happy, run the whole line:</p>
<p><code>git branch --merged | egrep -v "(^\*|master|development)" | xargs git branch -d</code></p>
<p>That should be all local branches tidied up. Now to complete the job you can prune the tracking branches you have set up, usually this will just be:</p>
<p><code>git remote prune origin</code></p>
<p>Though you can use <code>git remote -v</code> to find other remotes if you have them.</p>
<hr />
</div>
<div id="creating-pats" class="section level3">
<h3>Creating PATs</h3>
<hr />
<p>PATs or Personal access tokens, are a preferred way to authenticate into repositories through code. <a href="https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token#creating-a-token" target="_blank" rel="noopener noreferrer">Creating a PAT in GitHub</a> is relatively intuitive.</p>
<p>In Azure DevOps, you can do this by following <a href="https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page#create-personal-access-tokens-to-authenticate-access" target="_blank" rel="noopener noreferrer">Microsoft’s documentation on creating a PAT in Azure DevOps</a>.</p>
<hr />
</div>
<div id="storing-secure-variables" class="section level3">
<h3>Storing secure variables</h3>
<hr />
<div id="azure-devops" class="section level4">
<h4>Azure DevOps</h4>
<hr />
<p>In Azure DevOps you can securely store variables that are then used by your pipelines by making use of variable groups.</p>
<p>First create a variable group by navigating to <code>Pipelines > Library</code>. Enter any variables you want to store here and make sure to change the variable type to secret if appropriate (i.e. login credentials or PATs).</p>
<p><img src="images/createVariableGroup.png" /><!-- --></p>
<p>Then, in the pipeline you want to use the variables in, go to <code>Variables > Variable groups</code> and link the variable group as shown below. You can then call upon the variables as needed in your pipeline.</p>
<p><img src="images/linkVariableGroup.png" /><!-- --></p>
<hr />
</div>
<div id="github" class="section level4">
<h4>GitHub</h4>
<hr />
<p>In GitHub you can store sensitive variables as <a href="https://docs.github.com/en/actions/security-guides/encrypted-secrets">encrypted secrets</a>.</p>
<hr />
</div>
</div>
<div id="mirroring-a-repository" class="section level3">
<h3>Mirroring a repository</h3>
<hr />
<p>There may be times when you have a repository in one place, such as Azure DevOps, but want to mirror the code and any changes to it in another place, such as GitHub. This can be for many different reasons, though commonly for us it will be to open up our code across government. Azure DevOps doesn’t provide us with easily publicly visible code repositories, however GitHub does.</p>
<p>To mirror a code repository from Azure DevOps, use the <a href="https://github.com/swellaby/vsts-mirror-git-repository" target="_blank" rel="noopener noreferrer">mirror git repository extension</a> (already installed on dfe-gov-uk instance), make use of the PAT and secure variables sections above and then add a job to your pipeline and enter your parameters in the fields as per the example below:</p>
<p><img src="images/mirroringGit.png" /><!-- --></p>
<hr />
</div>
<div id="fixing-the-json-token-4-error" class="section level3">
<h3>Fixing the “JSON token 4” error</h3>
<hr />
<p>This error can appear when you are trying to push changes to Azure DevOps.</p>
<p>If it appears and you have not changed your password recently, try locking your laptop and seeing if on re-login it prompts you for a password change.</p>
<p>If you have changed changed your password recently, try signing out of Azure and then back in again.</p>
<hr />
</div>
</div>
</div>
</div>
</div>
<script>
// add bootstrap table styles to pandoc tables
function bootstrapStylePandocTables() {
$('tr.odd').parent('tbody').parent('table').addClass('table table-condensed');
}
$(document).ready(function () {
bootstrapStylePandocTables();
});
</script>
<!-- tabsets -->
<script>
$(document).ready(function () {
window.buildTabsets("TOC");
});
$(document).ready(function () {
$('.tabset-dropdown > .nav-tabs > li').click(function () {
$(this).parent().toggleClass('nav-tabs-open');
});
});
</script>
<!-- code folding -->
<script>
$(document).ready(function () {
// temporarily add toc-ignore selector to headers for the consistency with Pandoc
$('.unlisted.unnumbered').addClass('toc-ignore')
// move toc-ignore selectors from section div to header
$('div.section.toc-ignore')
.removeClass('toc-ignore')
.children('h1,h2,h3,h4,h5').addClass('toc-ignore');
// establish options
var options = {
selectors: "h1,h2,h3",
theme: "bootstrap3",
context: '.toc-content',
hashGenerator: function (text) {
return text.replace(/[.\\/?&!#<>]/g, '').replace(/\s/g, '_');
},
ignoreSelector: ".toc-ignore",
scrollTo: 0
};
options.showAndHide = true;
options.smoothScroll = true;
// tocify
var toc = $("#TOC").tocify(options).data("toc-tocify");
});
</script>
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
document.getElementsByTagName("head")[0].appendChild(script);
})();
</script>
</body>
</html>