 Now, now, excellent. Hello and welcome to Eismacomp 2023 and this workshop on slightly more advanced GitHub. This workshop is being live streamed to YouTube and we also have a group of participants taking place live, so very warm welcome to all of you. If you have any questions for us, you can ask them by the ES Hackathon Twitter account by commenting on the tweet about this workshop. You can ask your question in the Q&A facility here on Zoom if you're joining us in that manner. And you can also comment and chat with other participants in our Slack channel that was sent along with your registration information. We will endeavour to answer all questions as soon as possible but I'm going to caveat with the fact that I'm presenting and trying to look at questions at the same time and that might go horribly wrong. So I will see, but we will get to your questions and we would also like to take the time to draw your attention to our code of conduct available on the Eismacomp website at www.eismacomp.org. With me in this workshop, so there's me, I'm Chris Fritchard. I am a senior lecturer in paramedic practice and emergency care at Michigan Trent University. But I also happened to have spent some time doing a master's in computer science and have some experience with coding. There's also Liz Felton who will introduce herself. Hi, I'm Liz. I'm a lecturer in computer science at the University of Nottingham. I'm Matthew. Hi, I'm Mike Ranger. I'm a researcher at NENA, the Norwegian Institute for Nature Research based in Toronto. Excellent. So it's really great to have everyone here. So with this workshop, we're going to go through a little bit more of some of the more advanced features of Git, particularly focusing on using the command line to do some of the tasks that you might be familiar with, but also to get familiar with the fact that it's maybe not necessarily that scary once you get used to it, and then it will allow you to maybe take some next steps and do some really cool things with Git. So with that in mind, by the end of the workshop, we should know a bit more about some terminology relating to Git, some stuff about the structure of the Git repository, some basic commands, the use of CINCD, using the command line to undertake basic repository tasks, using GitHub, Git hooks and GitHub actions to run actions at various stages in the Git workflow, and sign commit using something called GPG. So I'm going to start with everyone's favourite task, a quiz. So you can scan the QR code or visit the website, vvox.app, on your phone, and that will sort of kind of load up. You can visit on your phone or PC, enter the code, and it will at the moment just show a welcome screen, but hopefully once you sort of join, you'll be able to see some questions once people are all on. So I'll give you a couple of minutes, and I know the YouTube stream is delayed by about 15 seconds, so I'm just going to hold it here for a couple of minutes while we wait, and then I'll switch the screen sharing to the quiz. I think we've got a few people on now, so I'm just going to switch the screen sharing over to that one. So you should be able to see the vvox screen now. So I'm going to open the quiz, and some of this might be testing some knowledge that you gained during the last introduction to GitHub workshop. Some of this might be new to you. That's okay. We'll go through the answers as we go. So this is hopefully just a bit of fun to make this sort of interactive. First question is, what's the command used to download an existing repository from GitHub? Sorry, 30 seconds to do that. Some of you on YouTube, there might be a slight time delay, so go off the timer that's actually on your phone or your website. So we had quite a lot of people got the correct answer, it's Git clone. We did put some sort of trick-trick-trick questions in there in that Git download or Git in it or Git checkout might be quite easy to mistake for that, but it's Git clone. So on the command line, in order to download a repository off Git, you just type Git, space clone, space, and the URL that GitHub or whichever platform you're using displays, and it will download that repository into a new folder for you. Excellent. So what command is used to initialize a new repository? So I'm going to close the question in a bit. So again, most of you got that right, it's Git in it. So that stands for sort of initialize. So Git in a folder containing files will create a new Git repository in that folder, which you can then push up to GitHub as we discussed. So the next one is command used to change to an existing branch. So say you've got a branch that already exists that's on, say, the GitHub, it's on GitHub and you've downloaded the repository and you want to change to it. Which command would you use to change to that branch? So again, a lot of you got this right, but there's a bit of variation in the answers there, but it is Git checkout. So Git branch is used to create new branches and to list branches and various other things, but you have to actually do what's called it. You have to check out the branch that you want to change to. I don't believe Git switch does anything. So that was just one that we put in there as a bit of a trick. So talking about Git branch, what does the command Git branch do if you don't type anything else after it? So it would be Git branch, and then the name of a branch would be what you want to type. So with no flag, what we call flags, which we'll talk about a bit later. So Git branch, then a branch name, what does that do? One second, I've just lost the thing. So Git branch should just create a new branch unless you've changed your Git default. So it should just create the new branch. So you have to use Git checkout to switch to an existing branch. And normally on the command line, if you type Git branch, then you have to check out the branch. Although in a lot of GUI tools, when you create a new branch, it automatically switches it for you. Next, what is the correct definition for the terms branch and fork? I've just lost that page. There we go. Sorry, there's a lot of reading for this one. So there's a difference between a branch and a fork. So a branch is a new copy of the project within that repository. So you're in your repository, you're on one branch. If you create a new branch, it's exactly the same as the old one, but it's still within that repository. So if you push your changes back up to Git Hub or whatever, it'll all be in the same repository. Whereas a fork is a copy of the entire repository that can be hosted elsewhere and modified by someone who perhaps doesn't have permission to modify the original project. Next question, what is a pull request? So a pull request is a feature of platforms such as GitHub or GitLab or whatever else you want to use a bit bucket that tells you as a contributor to submit new or changed code from your own fork into a repository following approval from the repository owner. So you could basically say, hey, I've made this change. I want you to bring it into the project. You're happy to do that. And a pull request is basically you asking someone nicely to contribute to their project. And last question, you'll be pleased to know, the correct sequence of commands to upload your code is to a remote repository that's owned by you. That's assuming the remote repository hasn't had any changes to it. So yeah, you first you add your file that does what we call staging. So that stages the files, then you commit them and then you push that commit up to the cloud or up to that remote repository. So it's git add, git commit, git push are the files that you as the sequence of commands are used. So I hope that was a nice little warm up activity for your get your brains get your brains working. So that was that was quite handy. Let me just share the slide. Now, hopefully you should be able to see the slide and Matt's hopefully pointed out there is a get switch command. It's a relatively new one. So it's still experimental. Basically, it allows you to switch to a branch but also keep all your changes. Whereas get checkout requires you to have done what we call state stage to track or stash your changes so that you're in what we call a clean index and working tree. So get switches kind of an experimental way of switching branches without losing your your changes. So there we go learn something new every day. So let me just put this. So we have created a GitHub classroom environment. I've posted the link on on stash stash. Yeah, not on it's not on Twitter yet. I'll do that in a second when Liz is going through the repository structure and I've also posted into the chat. So we'll talk through GitHub classroom in a second. Basically, if you follow the link invite link, you will get a thing asking you to create a new repository. You can create the repository clone it as per the previous workshop or true get clone and it will allow you basically to follow along with some of the tasks. So add a new file or folder to the get ignore file create a citation.cff file create a license file create a new branch and sign your commit. These are stuff that will cover in the workshop and you can follow along and it'll even auto grade you as to it when you've done it. So it'll use GitHub actions in order to grade your grade your work. So no one except Liz and I will be able to see your repository unless you make it explicitly make it public. But it's just your chance to kind of follow along and get some some automatic feedback as you go. So hopefully that's really helpful. So over to you, Liz. Okay, so what I'm going to be doing is going through some of the, excuse me, theory behind get and how it how it works and why it works like it does as well as talking a little bit about GitHub specifically. So, so that's what we're going to talk about a repository structure so you've seen a repository before hopefully I mean if you were in the previous workshop you will have seen a repository. When you create an empty repository. If you were to do get in it inside a folder, you'd have nothing in there, except a dog get folder which we'll talk about in a little bit. So we have some like our specific stuff, but also a good starting point in it and any get folder is you have a folder for your code and a folder for all of your resources which could be things like images or data files. So people's get structures you'll probably see SRC for source and res for resources that's common in a lot of other languages. But as you can see in an R package, there is a folder called our which contains the source code and an inst for additional files. Then there are special files within get, which will get will create for you. And most of them are out of the scope of this session, but we will be talking about get ignore so the special files start with a full stop, which means they are usually hidden. And there are instructions on the next slide about unhiding, but they're hidden because we don't usually need to go into them too much. So maybe it's and get my modules are kind of beyond the scope of what we're doing, but we will be looking at a get ignore file, which tells get files you don't want to upload to the repository. There are other language specific special files, including dot our build ignore. And you can easily Google kind of lists of special files that exists for different languages. And we've sort of got them. And the repository that I hope for you creating is sort of like a default our project that has those in it. GitHub specific folders. Sorry, GitHub specific files can be placed inside a folder called dot get hub. GitHub knows to look there. If it can't find things like you'll read me file. Do I have slide control. Hey, thank you. You don't you don't have to do it. I do. Don't I. Oh, right. So you can see at the bottom you might need to make hidden files visible. So on a Windows machine. In any file Explorer window, if you click view, you'll need to check the box for hidden items and then you'll be able to seal all of those files and folders that begin with the full stop. So get ignore tells get which file type should not be uploaded to the repository. Mostly we would use get ignore for things like temporary files which change a lot and are very machine specific. And by telling it to not upload those it helps you to avoid a lot of big issues of merge conflicts. There is a link on the slides. I don't know if we can put a link to that in the chat. Which is an auto generation tool for get ignore. So you can give it the language that you're working in and it will auto generate you a get ignore file that you just sort of copy and paste them. The dot get folder contains all of the information that's necessary for get to work. So that is what tracks the changes you make in the files contains things like your commit history and the branch structure. And is what enables kind of the remote get so on GitHub to communicate back to your local machine and figure out what changes have happened. Next slide. Okay, so this is an example get ignore file. There's also one in your repository that you can have a little closer look at. So this is a part of it. It's not the whole get ignore. It's part of a get ignore file for our. So you can see line starting with a hash mark. Or just comments. They're just telling us kind of what the following bit means. So we can see a glance what's not included. So anything that starts with a dot is a file type. So we're telling get that we don't want to upload any files of the type our history. Or any files of the type our data because those are history and session files that are going to change based on the machine what commands you from and things like that so we don't need to upload them to get. We can also tell it that we don't want to upload. Entire folders. So we've got it anything in vignette slash star dot HTML and vignette slash star dot PDF. So it's saying anything in vignette folder that has an ending dot HTML or an ending dot PDF don't upload that star just means that it could have any file name it represents any file name. Next one. So GitHub specifically has two more special files that it's worth being aware of. There's others that you'll see like we're going to ask you to create a citation file. But the two that really need to be there in any instance are read me. Which can be a file type md which is kind of GitHub specific. Read me should include you know what your your project is about how people can use it how people can contribute if that's something that you want. And GitHub will display that file on the repository's main page so it's the first thing that people will see. And then the other file is license which provides licensing licensing details for your package. So you can use a site to review different software licenses and choose the one that you think best aligns with your project. And you can put that information again it's a copy and paste situation put that stuff into the license file. If you are forking from other people's projects and using other people's code. It's worth checking what license their code is under. Because if their code has a more restrictive license than your code does you'll need to take that into account when choosing a license. Or indeed deciding if you want to use a code at all. Excellent. So I'll come into these ones. So the other two special files that are coming or the next few special files that are kind of useful. And we'll talk about citation.cff. So this is a file that you put in the root of your project. So in the main directory not under any folder. And it lets people know how you'd like them to cite your work. So for us academics this is really useful because actually GitHub and I'll show you a bit later when I walk you through a repository. But GitHub actually displays it in a how to cite this box. So it's really useful for us academics out there. It's both human and machine readable so actually looking at citation.cff file it's pretty self explanatory. Despite that you can write one by hand if you want. But there is actually an online tool. The citation file format tool that actually lets you generate one. And I'll put those links in the chat on Zoom and we'll get round to putting them in Slack and Twitter at some point. But you can actually use the CFF initialiser to generate a citation file for you with your project. If you're trying to build a package to submit to CRAN we'll shout at you. If you have a citation.cff file in the root of your directory unless it's in your rbuildignore file. So remember to pop it in your rbuildignore file. The other one that's quite useful is because we all need money to put food on the table and stuff. Especially if you're contributing to open source projects and maintaining an open source project. You can add funding details to the .github.yml file. And you can for example include links to an open collective site or your own Buy Me a Coffee or Coffee page. That people can donate to your project. So it doesn't necessarily bring in loads of money. But if people are willing to donate to your project it can be quite an unobtrusive way of highlighting that you are willing to accept donations. And it can be a way of kind of continuing the cycle of maintaining open source packages because it's not always easy. Other useful files are ones within the issue underscore template folder under .github. You can put in whatever custom markdown files you want to provide templates for issues within github. So when people create a new issue and again I'll show you this bit later. When people create a new issue they can actually have a template with questions and headers for the things that you care about in order to reproduce their bug. Or for you to prioritize new feature requests. And we'll also talk a bit about the github actions workflows file. So that's within the .github slash workflows and ends with the YML extension. It lets you define commands or sets of commands to be run when you for example commit a change to the main branch or similar. So that's those. Next up we'll talk a bit about signing commits. So it's important in some cases to sign your commits because it lets people know that it's you that's made these changes not someone pretending to be you. Because anyone can just on git you can set your username and the email address associated with any of your commits. You can set it to whatever you want. So I could if I was being really mean I could set my name to Liz Felton. And my email address to not to give me my address and commit some malicious code. And everyone would think that it was Liz doing it. And that would be very unfortunate. So what you can do is you can set up this thing called GPG to actually sign your commits so that you can verify that it's you. Because you have logs into your GitHub and you've associated your sign in key with your GitHub account. So anyone that is committing with that signature is basically saying I have access to that private key. So it uses a tool called GNU Privacy Guard, which implements a standard called OpenPGP. So GPG and PGP just to just to make things very confusing. PGP stands for pretty good privacy for those of you who were wondering. It's a public private key encryption, which basically means that you have a key that you keep private. And you don't let anyone else see that. And you generally protect it with a password, among other things. And you also have a public key and you let everyone see that. You let everyone know, hey, this is my public key. This is this is me. And you share your public key with the world and GitHub and keep your private key secret. So hopefully if you signed up to this workshop, I hope that you've already installed GPG. But if not, there's some links on the webinar sign up page and I will dig them out and put them in the chat as well. But hopefully once you've installed GPG, you'll have the GPG command available be that on Windows, Mac, Linux, whatever operating system you're using. In order to generate a new key, you just type the command GPG space hyphen hyphen full hyphen generate hyphen key. And then it just talks you through what you do. The GitHub documentation actually has a more detailed walkthrough. But I was just going to quickly show you the just going to quickly show you the the wizard. So bear with me while I just change my screen share. So I'm on I'm on Windows here and I've got GPG for win installed. And if I just type the GPG command by itself, you just get this and it doesn't really do much. If you type it just it just does nothing. So what you need to do is GPG dash dash full generate key. Can you see my? Yeah, and it comes up with a wizard. So you got RSA and RSA, DSA and Algamel, DSA sign only, RSA sign only, ECC sign and encrypt, ECC sign only. RSA and DSA. So that's choice one is kind of for older software tools that don't support ECC. So it's an older encryption standard that uses much larger keys. So you can use that and it's more widely compatible. But nowadays near enough everything GitHub supports it. Most things I've seen tend to support ECC so you can use just the default option number nine. So if you just press enter it or do it or you can choose option number nine and it will go through it. And again, default options, curve 25519 is plenty secure and supported most places nowadays. Anywhere that is not supported, you probably be wanting to make an RSA and DSA key pair. So again, choice number one, you tend to want an expiry date. You can extend it at any time or you can do what I do and just forget until your computer shouts at you that your keys expired. But you can actually then re extend your key anyway. So I would tend to say, you know, one or two years is probably a good length of time, maybe five years. If you're feeling brave, so you just type five Y and it will tell you when it expires. So it expires to about half eight British summertime on the 27th of March 2028. So yes, that's correct. And then you just type in your details. So type mine in, type in my email address. Don't need a comment and press O. And then it asks you to move your keyboard around and you can't see this. But Windows just popped up asking for a pass phrase. I just typed one in and that key is now being generated. So that is all there is to creating your new PGP key, which you need to do in order to sign your commits. So if I just go back to my slide, you then need to share your public key. So if you type those commands in, so GPG hyphen hyphen list hyphen secret hyphen keys space space hyphen hyphen key ID hyphen format equals long because on the command line, we we like. We like really long commands, obviously. I'll pop these in the chat. So what GPG list secret keys hyphen key ID format long does is it basically lists all the keys that GPG is aware of that you have a corresponding secret key to because you can add keys to your key ring to say I trust this person. This person sent me something I can decrypt that that stuff from them. But yeah, you can. But what the list secret keys does is it lists any key for which you have a private key. And then what the GPG hyphen hyphen armor hyphen hyphen export, and then the key ID. So the bit where it says sec, and then it says ED 25519 or RSA 4096 slash the bit off the slash is like a unique ID for the key. So you paste that in. And you get this like block of random text. You paste that into your GitHub under your settings SSH and GPG keys. Add new GPG key. You paste that block into there. Give it a title, whatever you want. And then from then on any commit that signed with that key is verified on GitHub. So you would in your repository type the command git config commit dot GPG sign space true. Or if you do git config hyphen hyphen global commit GPG sign true that will apply to all your repositories without the global it just applies to that one that you're in. You get a window pop up asking for your password. And you will need to enter that password whenever you're generating whenever you're making a commit that signed. So one of the common problems is that GPG isn't in your path. You need to make sure that you've got it installed. But it should happen by default nowadays on most installers on Windows Linux and Mac should put GPG in your path now. So does anyone have any questions on that? Because that was a bit of a lengthy lengthy one. But hopefully everyone's been able to follow along to check on the YouTube. I don't think anyone's post anything on YouTube. So we've not had. Oh, can you leave password empty? Can. But that then runs the risk of someone running off with your secret key. And the issue with that is then anyone can pretend to be you. So yes, you can. Oh, have I typed key? Have I typed? Have I done my command? Yeah. Key ID. Sorry. Key ID format. Yeah. Yes. Yes. So yes, you can leave your password empty, but it's not recommended. And yeah, it's key ID, hyphen format or key ID key ID hyphen format will tell it to print out in long form that you can then paste into your export. So I was it. Yeah. Sorry. That's my bad. Yes, I will fix that in the chat for you. There we go. Thank you. Right. Brilliant. And someone's just asked if the presentation will be available for future use. And I actually have a copy of the presentation available on Zenodo. So yes, I have just put the link in there. So, excellent. Where are we? Over to Liz for commit to merge conflicts. Yeah. So merge conflicts was something we we promised to talk about more if we if you were in the early get workshop. So first of all, we just want to talk about the process of committing. So the commit stage is where you actually move your code from your local machine up to the remote repository up to GitHub. So commit messages help others know what code changes you've made. So when you type in the command and get commit, you have the option to present a message. Which gives what gives other coders the chance to see what you've done. But it also can serve as a helpful reminder to yourself what you were doing previously in the project. When you make commit, you may get a merge conflict. So this also merge conflicts also happen as we were discussing in the previous workshop when you are pulling code down from get. So a merge conflict means the remote has a different copy of the starting code than you do. So if someone has pushed a new commit while you're working and you've not done a get pull before you've tried to add your changes. So the most direct solution is to edit the file that is causing the problem. So we go to the next slide. So these are sections of solving a merge conflict. So get will usually figure out how to fix a merge conflict and it'll ask you if what it has done is okay. And you can just okay it. But if it can't figure out what to do, it'll ask you to fix the merge conflict manually. The link at the bottom, you can see this is from Atlassian. Atlassian are the people who own Bitbucket, which is another very popular version control site that is also compatible with get and has a free tier. And they have a lot of very useful tutorials as well that you can look at. So we've tried to merge a branch in part number one. So we've typed get merge new branch to merge later. Auto merging is the response from get conflict merge conflict in merge up text automatic merge failed. And it's asking you fix conflicts, then commit result. So it's saying I, I as get can't fix this because I don't know which version of the code is the right one. So if you then type get status. It will tell you the status of the get branch that you're in. So it's telling you that you're on the main branch and you have unmerged things. Fix conflicts and run get commit. Or you can abort the merge if, if you really don't know. We're not quite a deleting our whole repo yet. No. So it's asking you. So it gives you a couple of options of things that you can do. And it wants you to add the file back to the stage when you've made the resolution, both a modified merge.txt. So in this example, we've used the command cat merge txt. Now cat is a Linux command that'll give you the text file in the in the terminal. You could also just go and open merge.txt in notepad. And what you would see in that file is the start where there's a whole bunch of left facing arrows where it says head. So that's what the remote repository has. So that's what the remote repository thinks this file should look like. Then you've got a row of equal signs. So that separates the two versions of the file and then the one underneath. So the content is what's in black and then it's telling you that that content is in the new branch to fix that merge conflict. I would decide what content I wanted to keep. And then you would need to get rid of the text that's been highlighted in green, the sort of get specific file information. So that head comment, the equal signs and then the name of the branch you're merging. You would then just recommit that file once you've made manually made the changes to it that you needed to. And hopefully it will stop complaining at that point about a merge conflict. If it doesn't, you do have a link in the chat and eventually elsewhere to dangitgit.com. Which is a bunch of scenarios you might find yourself in with Git. And then how you get out of those scenarios using various command line arguments. So if you get to the point where you don't know what's going on with the repository, it's good to check that one before you just kind of delete everything and try and start again. Next slide. So I also want to talk just a little bit about Git's branching structure. So we've talked a lot about branches, but I think it's helpful to kind of have a look at them visually. So at the very top, this is an older diagram. So it's calling the sort of the original branch master GitHub and a lot of other Git services now call that branch main. So the main branch is the kind of accepted global version of the code that everyone should be working from. Branches can be worked on concurrently. So you could have one branch checked out. Someone could have a different branch checked out. You could be working on different sets of changes and then push both back to the main branch. On this graph, you've got hot fixes and release branches, which are sort of more kind of higher level software engineering, but release is basically the code that end users would want. So say if you're developing an R package and you have a working version of the code, say version one that has like a minimum feature set, you could put that under a release branch and people would know that that code is stable and ready to use. Then you have your working branches, your development branches and feature branches. So when we say feature, we just mean a new thing that's being developed in the code. So you would create a branch off of the main branch, work on whatever feature you are working on. And then when it's it's working and it's ready to be pushed back, you would push it back up. And then this graph is kind of moving forward through time as those changes are happening. Next slide. Yep. So back to me to talk a bit about Git hooks. So Git hooks are a nice feature of Git. They're actually not a GitHub feature. They're built into Git itself and the command line tool itself. They allow for commands to be run before a commit or other stages in the Git pipeline. So that can be really useful if, for example, you've got a big project and you want all your commits to follow the style guide. So you can use either linter or styler to automatically run every time you commit something. And it won't let you commit until you've fixed all the things, which can be very handy. But you can have it check that you've rendered your RMD files into markdown. So it might will throw an error at you if you've forgotten to render your RMD files. And also you can even get it to run rocks and ice to update your documentation every time you commit a change. So Git hooks can be really handy. You can write them yourself. They're just simple scripts that run on your computer. But that's a pain in the backside. So I would suggest using a package. So the pre-commit package available on CRAN is actually quite a handy one. It pulls itself into a bigger sort of framework of packages. So there are some dependencies outside of R that need to be installed to get the pre-commit package to work, but relatively straightforward to install and has loads of different ones available by default. So that can be quite useful. But if not, you can also have a look at various examples of Git hooks to really enforce your project style on others and make sure that everything that is committed is kind of a working with up-to-date documentation. I can't count the number of times that I've committed my changes and then gone, oh, no, I need to go back and run rocks and ice and commit another bit again. It's quite handy to build that in as a sort of pre-commit hook. And the reason they're called hooks is because they kind of hook into the command and run before or after various stages of the project. So they are just simple scripts in the .git slash hooks folder if you want to create them manually. But that's about the only time you'll ever need to open the .git folder. That's sort of a hereby-dragons area of your Git repository. So we're trying not to go delving in there too much. The next thing I was going to talk about was continuous integration and continuous deployment or delivery. So this allows you to automate code building, testing and deployment. I use GitHub Actions because it can be very easily integrated with existing public repositories on GitHub. But other CI CD tools do exist and people use them. So there's Azure Pipelines, other self-hosted ones. Jenkins was a very old-school one that used to be used for other projects. But there's lots of them. I think GitHub Actions is very straightforward to integrate into your existing GitHub project. And the great thing about it is loads of things that can be kind of accessed. So there's pipelines that will install R for you, that will install your package dependencies, etc. And what I was going to do was just do a bit of a quick walkthrough of one of my repositories. But Liz was going to show you some of the Git commands first. And once she's done that, I can give you a walkthrough of one of my repositories and talk through some of the CI CD stuff that I've got going on. So just a reminder that the GitHub Classroom tasks do exist. So we should have talked you through everything that you need to do, be that through the quiz, telling you about what commands do what, or be that through the presentation. So hopefully you should be able to do everything on the GitHub Classroom that I've mentioned there. And then just to check that you've done it all right, you make a commit, which you'll obviously sign using PGP signature. And then when you push it up to GitHub, so that's the command git push. When you push it up to GitHub, it will automatically mark it and tell you whether or not you've done everything on that list. So I'll hand over to Liz to just talk you through some of the command line stuff so Liz can share her screen to do that. And then I'll show you one of my repositories there. Okay, so hopefully you should be able to see my whole screen. First thing that I just wanted to go through in the workshop earlier, we had some issues signing in to get through the command line. And the way that git does sign-ins has changed. So I need to go to my profile. So what you need to do is if you haven't created an access token, you'll need to do these steps and then sign in to the command line with it. So hang on. It's under settings. How do I get to settings? Click your face up the top right. Click my face. Settings at the bottom there, sorry, settings. Go to settings, come all the way down to the bottom. Developer settings, personal access tokens. Create a classic token. So you can see I already have a token here that I've used to sign in to Git. So I won't get the sign-in steps, but I'll explain to you what happens. So what you have to do, create a new token, create a classic token. Just ask me to re-sign in to my GitHub. So you would give it a name. So I call my previous token Esmerconf because I'm using it to access that repository. You can set an expiry date for it, which again is pretty much personal choice. When the token expires, it will just ask you to create a new one and re-sign in. You only need to tick this first box. All you need is repo access. So when you've done that, click generate token. I won't do that because one, it won't work because they didn't give it a name. But if you type a name in here and then click generate, it will give you a token. And you have to keep that token secret because it's essentially like a password. So when you open your command line... Sorry, Liz, just on the tick boxes. If you are going to use the CI and CD stuff, you also need to tick the workflow box. So if you can use GitHub Actions, you also need to tick workflow. Otherwise it won't let you commit changes to your GitHub workflows with that access token. Right, OK. So then after you've done that, create generate token. It gives you a token to keep secret. And you can only see that token once. So it's a good idea to put it somewhere safe. Otherwise you'll have to create a new token. Then we go to our command line. So on Windows, you can just search for CMD to give you a command prompt. On Mac and Linux, you're looking for your terminal. And it's opening me in the directory, C drive, users, Liz. I want to go to this place. Document slash Esmerconf. So to change directories in the command line CD, which stands for change directory. And then I copied that directory address. And I'm just going to right-click once. And that'll copy into the command. And it's taken me to that directory. So if I now go back to my repositories. Nope, that doesn't help me. Oh, sorry. Yeah, you'll get a classroom once they're actually in there in a separate organization. So it'll be in the organization. It's here, yeah. Nope. Hang on. I have a repository under me. Where is it? There it is. So you would go to your repository. And then this green code button. If you click that, it will give you instructions on how to get this code onto your local machine. So we're going to stick with HTTPS and click that button to copy it. Go back to our terminal. And then the command is git clone. And then one right-click again to paste in. So you can see it said that it was cloning it into this folder. It's named the folder the same thing as the repository. And then it's just going through all of the steps. So it's downloaded a total of 24 objects. And if I go to my local folder, it's created that and I can open it and it has the same things in it as it does on GitHub. So this is somewhat a standard R project. We have an R project here. We have R folders and manual folders. You can see the .github file, which is where you would be putting your hooks and you have, I'll note sorry, git is where hooks go. Again, you don't really need to look at anything that's in .gith. It has this readme.md file here. So at the moment, the readme is just at the bottom underneath the repository. So git will find that file automatically and display whatever's in it. And at the moment you just have a link to Open Visual Studio Code. What I'm going to do is I'm going to edit this file locally on my machine. I'm going to give it a heading. Make sure you save it locally. And now I can go back to my command line. So if I type git status, excuse me. Oh, sorry. I'm not actually in that repository. Just in, I'm in the, in this folder, the ESMACON folder, not this one. So copy CD again. Now if I type git status. So it tells me I'm on branch main. And my branch is currently up to date with origin main. If it told me I wasn't up to date, if I had an older version of code than what was an origin main, I would have to do a git pull. Then it's telling me changes not staged for commit. A modified version of this readme file. And then no changes added to the commit. So if I want to just add all of my changes, it's git commit minus A for all. And then to supply a message minus M. And then in quotations, you can just give it a message. Oh. You've, you've set your git to use GPG, but you haven't got a key. Great. You can do the command to unset a GPG. If you don't have your key is a git config. A git space config. Sorry. Git config. Space commit.gpgspar sign. Space false. False. I'll just undo that for the minute. Because I've got my screen up. I don't want to be getting my keys out. Right. Git commit minus A minus M. Whoops. Put the message inside the quotations. So on branch main, this number. Well, number and letters is the ID of the commit. One file changed. And three things have been inserted into that file. Three lines. So if I type git status again, it tells me that my branch is ahead of origin main by one commit. So I've made one change that's not on origin commit. Sorry, origin main. And then nothing to commit. Working tree clean. I've already committed all of my changes. So I've committed my changes locally. They then have to go to GitHub. So you type git push. It goes through all of its stages figuring out which files have been changed and what it needs to update. And it should now tell me that my branch is again up to date with origin main. So if we come back here. Open my read me file. Oh, I didn't get the mark down right on that. That's fine. But you can see the changes I've the changes I made have been inserted into the top of that file. And GitHub has updated it here. So we talked about creating a new branch. So you can do it with a git branch and then give it a name. She might not need quotations. Get branch new branch. So it should have switched me. No, it hasn't switched me. Sorry. I've created that branch. So if I type git branch with just nothing after it tells me the branches that are available for this project. So in green with the asterisk is the branch I'm on. And new branch is available. So I can check out my new branch. Switched to new branch. So I now want to make some more changes. I'm just going to go back into this read me file. And you can change any number of files per commit. You don't have to commit them one at a time. But just to show you the process. So the other way that you can stage files is get add. And you can do get add minus capital a to add them all or you can add files specifically. So if I stage that file and then think, oh, actually, there's something else I need to add to it. You can unstage it and get it back, make those changes. And then restage. Once it's staged, get commit message. So that minus M says a message is following and then quotations. Second commit one file changed to insertions and then get commit push. Current branch has no upstream. Right. Okay. Yep. Sorry. So I've created a new branch locally on my computer. But GitHub doesn't have that branch on the remote version. So just to make sure we create that branch get push. Set upstream origin new branch. I created that branch within my GitHub. So new branch has recent pushes less than a minute ago. From here, I can do a comparison, form a pull request. But we can also do that from the command line. We can merge this branch back in to the origin. What are the arguments for get merge, Chris? You just give it the branch you want to. I think you do it hyphen hyphen into name. Then the branch, so... Merge branch into current... Hang on. No. Go the other way. Get checkout. Yeah. And I think you just do get merge and then the branch name. Yep. So you see, I have to switch back to the main branch and then merge that branch, the new branch in. So get merge new branch. So I've merged the branches on my machine. And it's now saying that I'm ahead of the GitHub version by one commit. So get push. And it's now saying that we're up to date with the origin because we've pushed the merge change up to GitHub. So I think that covers everything we were going to cover on the command line very briefly. I think it does. So we are now going to let you guys loose on your own repositories. If you haven't been already to try out some of the command line stuff. And yeah. So Chris, do you want to put the slides back up so they've got what they want to do? What I'll do is instead of that, I will post what they've got to do in the chat so that they can see that. But the slides, I've also posted the slides on Slack. And I will post it on Twitter for people. So let me just grab Twitter. And in the meantime, I was going to talk through some of the stuff on the CI CD stuff. Just looking at the time. We might struggle to fit it in otherwise. So let me just... Oh, no, it's too big. Bye. There we go. So I was going to also just while you guys let loose, the classroom will remain open. So hopefully that will mean that you can play around with however long you want for it. I was just going to talk through some of the features that we've talked about look like in general origin. So origin in the Git commands actually means your remote repository. It sounds a bit weird, but your local stuff doesn't have a prefix. And origin is like the remote repository. So origin is just another term for the remote place that it's tracking. So to be that, I'll GitHub, Bitbucket, another Git repository on a remote machine that you're connecting over SSH, whatever. Origin refers to the remote computer or the remote branch and nothing is the local machine. And you can sometimes, I think you can, because Git's what we call decentralized, it does allow you to have more than one kind of remote tracking branch called other things. But that's kind of a bit more tricky to kind of explain and you have to delve into the instruction manual and tends to be not a very widely used use case. So just I'll show you on the Prisma 2020 repository. Just some of the GitHub features that we use and hopefully that will help you with things like GitHub actions and stuff. So hopefully you can see the GitHub repository there. So first thing is the citation.cff file. So if you look here, I've got a message. We've got the authors of the product and the citation file. And then we've also got what we call a preferred citation. So that links us to the article that we've published about this app. So what that means is you've got the citation for the actual app itself and then you've got the preferred citation. So when you go on to cite this repository, which appears when you have a citation.cff file, it will generate a nice APA formatted thing to our journal article and it also lets you export into a Bibtech file for importing into something that uses Bibtech. So that's citation.cff, so very handy if you are doing something that you want people to cite. When you create a license.md file, it will tell you it will try and auto-pick up the licenses. If you look, we've got a license.md and a license file. Our packages tend to have license files like that. So GitHub gets a bit confused, but because we've got a separate license.md file, it's telling us it's found the MIT license here, which is what the project is released under. The other thing is the funding.yml file. So that's as simple as GitHub has a list of supported funding model platforms. So I've got a link to Open Collective and Coffey, and they just now appear down the side under sponsor this project. So very handy if you just want something to kind of say, you know, hey, I'm doing this for free. That's kind of useful. So for those of you who contribute to big projects and who maintain stuff that's quite popular, that can be a way of kind of still contributing to the community but also paying the bills. Although I wouldn't use it as the only method of paying the bills. You've got your releases. So Mac talked about them, but I'll talk about them in a little bit with the automation that we've got. And you can also see the markdown rendered into readme.md. There. So the other thing I was going to talk about was issue templates. So if we have a look at the issue templates that I've got. So I've got two, I've got bug report and feature request. So if I have a look at the bug report markdown, this is basically you give it a name about anything else there. You can automatically give it labels or assignees or title. And then the bit underneath it, that is what a user sees as when they go to file an issue. So you go on to issue, you click new issue, and actually I want to create a bug report. All of that stuff is pre-filled in ready for information. So the really handy thing about this is you can really drill down and get people to give you the things that you need them to give you in order to fix their problem or to kind of prioritize issues. So that is kind of a really handy one. The other one I was going to talk about was the GitHub workflows. So I've got a few workflows. I've also got an R workflows package where I've created some that are a bit more reusable. But if we look at the ArcCMD check file, so what this is a YML file is a relatively straightforward syntax, and the GitHub documentation is absolutely great for using these files. But pretty much the on bit tells it when to run. So this will run when it's called. So that means that this doesn't run when there's any action on this repository. Other repositories can use this file to do something that's reusable. So this will run our command check on four different operating systems. So Windows, Mac, and two versions of Ubuntu. It will use the latest version of R, and on one of the Ubuntu versions it will use the development, so the next version of R in development to run it. So the great thing is here is, so for every one of those operating systems, it will check out your repository. It will install all the dependencies, and then it will actually run our command check as CRAN, and make sure that it works. So the great thing here is you can basically check your package will at the very minimum build on all of those different versions that are on those different operating systems. That can be really handy. So what we'll see what it looks like is when we commit something to the Prisma 2020 package, sorry, it will actually run that R command check on the four different versions, and it won't carry on unless they all succeed. Then it runs this thing called package down, which is to build, it basically runs a different workflow, the package down workflow to build a GitHub site. So the same as Matt was showing in his previous workshop, where he's got that website. This will actually use package down to generate basically an instruction manual for the package. It then will, for a commit to our main or master branch, it will actually deploy it to our shinyapps.io account. So what this means is I've got what's called continuous delivery or continuous deployment. So every time I make a change, it will run its automatic checks, and as long as they pass, the latest version can be pushed to the Prisma Flow Diagram latest app on our shinyapps account. And then if I create a release, a different workflow is triggered. So on my R workflows, actually if I create a new tag, using the git tag command, it will actually go, hang on a second, that's a tag that's like a version. So what it will do is it will actually run your R command check. It will run R command build first of all to actually build a package ready for submission to CRAN. It will run R command check as CRAN on the latest version of R. And it will actually run it on the package that's built. So this workflow will actually do all of the automatic testing that is required for submission to CRAN and upload the log file to the release. So it will actually create a new release on GitHub. And you're all welcome to browse this repository to see exactly how I've done this on the workflow. But it will actually create a new release and deploy it to, and deploy that release as well on our Shiny apps account to the main app there. So the release will include a variety of files. So I've used, I've told it which files to include. And actually if we look now at the releases for this package, it has the R command check log. It has the instruction manual it's generated. It has the package that was ready to be uploaded to CRAN. It has also the source code archive from Git. So you can see that that can be very powerful as a way of making your life infinitely easier. Because you no longer have to do all the boring stuff of updating your package. So if we look here at the latest Prisma flow diagram, for example, you can see that if I were to make a change and push it, it would just within about half an hour, I'd have the latest version up there. I say within about half an hour, because within my workflows, what I have done is built in some protections to the deployments and I can't remember exactly where they were. But yes, so there's some protection rules to our latest and release. So if I look at this release environment, you can see that actually someone needs to approve it and we need to wait at least 30 minutes before it will be deployed. That gives me time to go, oh no, I didn't mean to do that and undo everything before it gets deployed to a live environment. So that hopefully we don't break things. So it is possible to protect things using the GitHub Actions and actually everything I like to think relatively straightforward. So you have some branch protection rules under your environments and then on your GitHub Actions you run them in that environment. The best way to kind of, I think the best way to learn with GitHub Actions is to just practice because they can be really, they can be quite straightforward but you just need to be mindful that they can be a bit idly as well. So does anyone have any other questions? I think there's a few people still around. So if anyone's got any questions, that's great and I'll stop my sharing. Hopefully we covered what you wanted to cover. I'll just check there's nothing on. And to just submit to GitHub Classroom, all you need to do is push your commit. So you commit once you've done all of that, you push that commit to GitHub Classroom and it will automatically mark your work. Isn't that clever? Right, I think we might be sort of seven minutes early but I think we're about wrapped up if no one's got any questions. We're going to go with no because there's nothing on, Slack, nothing on Twitter and nothing on YouTube. So that's brilliant. Okay.