Bytesize: Working with GitHub using VSCode and Github CLI

Edit

0:01 (host) Hello, everyone, welcome to today’s bytesize talk. If anyone is interested to ever give a bytesize talk, please contact me on Slack. We are always happy for new speakers. And of today’s topic, we’re looking at using CLI client for GitHub and VScode when working with Git with Phil.

0:25 Thank you very much, everybody, and thanks for the intro, Fran. Please do jump in if you have any ideas for nf-core talks or would like to talk about a pipeline you’re working on or just anything you’re interested in, really, please do give us a shout on the nf-core Slack. We’ve got the bytesize channel, and we’re always looking for people, new speakers and new topics. And even just ideas for topics is great to have. We keep a big list of things and we try and rotate through them, but we’ve got a bit low on ideas lately, which is why you’ve got me talking to you today with another slightly last minute topic. But it’s a bit fun, and this is one that has been bouncing around for a little while.

1:10 The topic today is using Git and GitHub and different ways of interacting with that and managing your workflow. It’s a topic I’ve been quietly ignoring for as long as I possibly could, because I think it’s a bit of a Pandora’s box. The way that you interact with Git and the way that you have these workflows is a very personal thing. Everyone tends to have their own preferred way of doing things, their own setup. It depends on what your preferences are, whether you like graphical tools or command line tools. It depends on how long you’ve been using these tools, how familiar you are with them. It depends what order you learned things in and what tools were available when. This is by no means an authoritative guide whatsoever. I don’t expect anyone else to end up with the same workflow as me, but it’s just to give you a taste of some of the different tools which are available, talk through a little bit of when you might find them useful and why. Maybe we can have a lively discussion at the end where you guys chime in and say, there’s a much better way to do that! Don’t ever do it that way because that’s terrible! And hopefully we might even have another talk or two queued up after this where people go into other workflows and maybe talk about other ways to do things. I know that Edmund had some fancy ideas with tools that I’m not familiar with.

2:30 Okay, sorry, I’m rambling. Let’s get on with it. There are not really any slides for this talk. It’s just me freestyling it. We’ll crack on and I’m going to start off by, okay, there’s like two slides. I dug out these old slides from a talk in 2010, an in-person hackathon, just to do a quick recap of what is Git and what does the terminology mean? Just for any of you who are watching, you might be fairly new to this. Git is a source version control software or source code software version handling user, whatever set of words in different order. When you’re writing code, you can keep control of the history of the files of the code you’re working and you can collaborate with others using this tool.

3:19 With Git, you have a repository, which is your project, and then you have all the code within it. Each time you do some work, you hit a checkpoint and you can make a commit, which is like a bundle of work and you keep working and you make another commit and another commit. Each of those commits is like a point in time and a history. With Git, you can also branch at any point where you go off and work on two different things side by side and you can also then merge those branches back in together. This is typically used if you’re multiple people working on one repository or if you’re working on different features in parallel, and it’s always good practice to work on a branch. But you don’t end up - especially if you’re waiting for other people to review a certain bit of code or something - you can work on things asynchronously.

4:11 Repositories can also be forked, which means you make a copy of a repository from one account to another one on GitHub, for example. Here I’ve made a fork of an nf-core repository to my own personal account and that duplicates everything, but GitHub also knows that my fork came from that one. When I’m using Git locally, the Git client can interact with the different remote repositories, which are sat on GitHub rather than on my computer. I can then do development on my own fork and a bit like working on a different branch, I can then make a pull request to merge those changes back into the original repository, which I came from, which is usually called the upstream repository. Okay, that was Git, the quickest intro you’ve ever seen. Hopefully everyone that’s watching is fairly familiar with Git already.

5:06 To do today’s talk, I thought I would just do some work with you guys,let’s just live demo it. I’m going to start off using VScode and then afterwards I’m going to introduce you to the GitHub command line interface with the CLI tool and touch on a couple of different ways that I personally use it. All of the stuff with VScode, there’s this documentation page, which I found. I’m just going to pop the link into the bytesize channel in Slack because it talks in more detail about the stuff I’m going to talk about now and how to use Git within VScode, because there’s a lot of stuff you can do. If in doubt, go and check that out and don’t listen to me.

5:47 The first thing I’m going to do is, I found this bytesize talk from a couple of weeks ago, where Chris gave a really nice talk about using custom scripts in Nextflow. And I noticed that Fran does an amazing job of bytesize maintenance, but she hasn’t yet added the YouTube URL to the webpage. I found something to do. The video is on YouTube, but it’s not linked into that page. Nice simple thing for us to do, you can just jump in and add this URL. I’m going to copy that YouTube URL and then on the nf-core website, you can always just scroll down to the bottom to find the URL of the source file, which the web page is generated from. Or you can click the edit button, I’m going to click the edit button. This takes us to github.com and I’m now looking at the markdown file here.

6:33 I could actually just edit this directly in GitHub, but that’s not very much fun. I’m going to do this first bit using Gitpod, which I previously gave a couple of talks about using Gitpod. And it’s actually the main reason that I started using VScode to manage Git rather than the command line, because when you’re running in a Gitpod environment, you’re in VScode by default, basically. And everything is there for you. I’ve just spun up a new environment. If you’re not familiar with, with VS, with Gitpod, it’s running on Gitpod servers now and I’m in VScode and it’s just putting on a code for me here.

7:12 It was “markdown”, “events”, “2023”… no, “2022”, sorry. And what was the file called? bytesize_custom_scripts. Okay. And you can see up here, I think the other ones will have, yeah, YouTube embed. That’s the change I’m going to make and just paste the YouTube URL. Maybe it should be the proper one that was not a short one. Okay. That’s my change. It’s pretty simple.

7:50 What next? So I actually have a terminal down here, but I’m going to ignore that for now. at the moment I’m working on just the main master branch of of the repository. That was what’s selected here. When I launched Gitpod, I could equally be running on a on a local client of a repository that I cloned manually, but anyway, I’m on the master branch. In fact, you can see it down here in Gitpod in VScode. The main thing I’m going to be using here is this button on the left-hand side of VScode called “source control”. If I click on here, this is where I manage all the changes I’m doing and interact with Git. And this is the same if you’re working locally or Gitpod, forget about the Gitpod thing for now.

8:33 The first thing I want to do is I want to make this on a feature branch. Like I said, I don’t want to do it directly on master. And so you can either click this (you can see it came up with this option there) “create new branch”, and you can also do it through this dropdown menu. “branch” and I’m going to do create branch, I’m going to do “bytesize add YouTube”, okay. Now you can see that has changed down here now, and now I’m running on a different branch, which is just local.

9:04 When you’re using Git, you have different phases of using files. And the first thing is when you’ve made a change to a file, it’s called unstaged and I need to first stage that file. It’s ready to be committed and then I do the commit. You can see down here, it says there’s some changes here, but nothing is actually staged for a commit yet. First things first, I can double click on this and it shows loads up a diff here so I can see what’s changed in that file, which is really, really nice to be able to just quickly double check what’s changed and make sure that it looks as I expect.

9:40 That looks good. And then I’m going to hit this plus button, it says stage changes and it pops from “changes” up to “stage changes”. You can imagine I could have lots and lots of files here under “changes”, and then I just stage the ones I want to. And I can unstage it again and I have a feeling you can either be clever about staging parts of the file and stuff within VScode if you want to.

10:03 I’m going to stage that and then I’m going to type up here a commit message, “added YouTube log to bytesize”, and when I hit commit… great. That has now done git add to add the files and it’s done git commit to make a commit, but it’s still on the local copy of the repository, which I have on Gitpod. And GitHub doesn’t yet know about it.

10:30 The next thing to do is I’m going to click publish branch, which is going to push this new branch that I created back to GitHub. Okay, that’s gone and it’s even come up with a little thing saying, do I want to create a pull request? First, I’m just going to show you on the nf-core repository here. Look, it’s saying I’ve created a new branch here. That’s correctly gone to GitHub. Oh, I was too slow, I could have clicked “create GitHub”. That’s the end of the Git source control part of VSCode. The source control bit is pretty blunt. It works with GitLab or BitBucky or anything, it’s not specific to GitHub. The next part then is specific to just GitHub within VSCode and that comes down to this next one here.

11:16 I can’t actually remember if this is a plugin for VSCode or if it just comes with a vanilla install, because it’s always been there since I first started using VSCode and so I’m not sure, I have a feeling it’s part of a vanilla VSCode. I’m going to click GitHub and it gives me a whole bunch of stuff to head to here. I can navigate the pull requests for this repository and the issues and look at all of these as if I was browsing the website itself. I don’t do this very often, you can tell. I can open up the description as if I was browsing GitHub without going off to the website, but right now what I want to do is I want to create a new pull request and I’m going to do that by clicking up here.

12:00 I could, of course, do all this through the GitHub web interface, which is what I usually do. I usually go in and hit compare and pull request and do it through GitHub, but this is about VSCode, so I’m going to do it in VSCode. The interface looks pretty similar to the web, I’m saying, where is it coming from? It’s coming from this repository from this branch I just created and I want it to go into the master branch. I’m going to add a title for the pull request and a description. And you can see, we’ve got the changes down here and I can double click and look at those changes and again, see the diff. That is done.

12:38 What do I do now? I’ve forgotten. Where’s the button? Create. I’m blind. You can see I could create it as a draft if I want to, but I’m just going to hit create and off it goes and it’s created a pull request. It’s now opened up pull request also within VSCode and you can say there’s like a similar thing where I can leave comments and assign reviews and everything. And of course it looks just like the native GitHub interface here. That’s it. Without leaving VSCode, I’ve just made changes up here. I added them to source control, made a new branch, committed them, pushed that branch and then in the GitHub interface, I then created a new pull request and it’s ready for someone else to review and merge. Pretty cool.

13:25 You can also then see that I can do reviewing of other people’s pull requests and that’s going to be what I come on to next. It’s what a big part of being part of a community is about, not just doing your own work and pushing it to other people, but also looking at other people’s code, reviewing it and merging it in. You can see within the GitHub tab here, again, I can also see all these pull requests and look through them. And it’s the same as looking at the list within GitHub, but it also have some different views such as waiting for my review and assigned to me and stuff. I can also look at Fran’s pull request here, see the changes that she made and see whether I agree with her pull request and stuff.

14:12 What was I going to do with this next? I think this might be where… Yeah. Okay. I was going to update this to the local branch. One more thing about this on VScode before I go on, which is within VScode, you also have a terminal browser, “terminal”, “new terminal”. If you want to, you can still do the Git stuff that you might be more used to in the terminal down here within VScode, which is good if you’re limited to using VScode on Git or whatever. I can still do git status and git checkout master, because you can see I’m still on this feature branch down here. What’s that? So you have both of those options when you’re working within VScode.

15:06 The next thing. This is as far as I’m going to go with VScode, you can do lots more stuff in VScode. There’s also a lot of really cool plugins, which I’m not really going to talk about. One of the ones which is very commonly used is called git lens, which is really powerful. And you can just do tons of stuff with it. It has lots of core analysis. One of the things I quite like is if you have it installed, this is on Gitpod. I open up VScode for, this is my local VScode now running with a local repository. If I look at a file and if I hover over a line long enough, Git lens should… it’s not going to do it. Okay. And maybe I’ve disabled it or something. I think I have a feeling I might have disabled it the other day, but it will show up a history of that line of code, which is pretty cool. Something else I can do. Sorry, I keep thinking of things as I go along.

16:07 These buttons up here, these will actually walk you through the history of a file as well. I can click that button. That’s why it’s because there’s no history. Okay. I’m not quite sure what’s going on in this live demo, but it’s clearly not working. But usually if you click these buttons, you can walk through the history of that file through the different commits and see what changes each time, which is pretty cool. Yeah, I don’t quite know what I’ve done to Git lens, but it’s really unhappy. Apologies.

16:38 Next up, GitHub command line. I’m a bit of a command line junkie, so I quite like this. And this has been a real game changer for me, this command line tool. Usually when you’re working with Git on the command line, you’ll be used to doing things like… I’m just going to switch to my fork here. You’ll be used to doing things like git clone, you know, to clone a repository, you’ll do git clone, blah, blah, blah. And you’ll do git add, git commit, and all these commands with git. That’s not what I’m talking about. The git command line is obviously central to working on the command line.

17:26 This is the GitHub command line, which is gh. And this is specifically for interacting with GitHub. First thing is that differentiation. You can just do brew install if you’re on a Mac, but it’s pretty easy installation. And if I do gh --help, it tells you about how to use it. I think one of the first things you have to do is you have to do gh auth, which just opens up a window to log into GitHub. Once you have the GitHub command line installed, you can do some stuff really, really nicely. One of my favorite things is you can clone repositories using a gh command instead of a git. And it’s just as git clone, but it’s a little bit more clever. It’s especially useful when you’re working on a fork. this is my personal fork of the nf-core website here. Now, if I’m in a blank directory here, if I do copy that command I just pasted, it’s going to clone that repo for me, exactly the same as if I did git clone. Sorry, I should have used a smaller repository, there we go. And then if I go into that directory, it looks exactly the same as if I’d done git clone. But one of the clever things it’s done is it has already set up two remotes for me. It knows about my fork’s origin remote, which is what git would have done if I just cloned it normally, but it’s also, because it was a GitHub client, knows that I forked this from the main nf-core repository, so it’s already created a separate remote called upstream, which is just really helpful because it’s just one fewer step and it’s just there and it’s just easier. that’s one of the simplest things you can do with GitHub.

19:03 What else can you do? You can do everything you would do on the web through a command line with the GitHub command line. You can do gh repo and it knows, that the current directory is in a cloned GitHub repository, so it knows which repository I’m talking about. And I can do gh repo view, it asks me “which is the one?”, it does that once… And now I’m looking at the readme for this, that’s cool. I can do --web and it always just opens a tab in your browser. It’s a really quick way to get there from the command line.

19:38 Now one of the most powerful things you can do with the GitHub command line is work with pull requests. I’m finally, after lots of waffling, going to get onto reviewing a pull request by Fran here. Now I’ve looked at her pull request, she’s added some nice stuff, there’s a nice transcript for another bytesize talk. She’s added in the URL for YouTube. This all looks great and good to go. However, one thing I’ve noticed is that this pull request has got out of date with the main branch. A lot of things have been merged in and the header branch is now behind the head. It’s probably fine to merge as it is, but let’s just update it quickly. What I’m going to do is I’m going to use gh and I can do gh prs list, if I wanted to… ups, gh pr list, and I can see all the pull requests listed. If I wasn’t sure about the name, I could do it through the command line and I can also do gh pr view, the number of Fran’s pull request, and it shows me this on the command line as well. A bit like VScode, you can do all the web stuff that you’re maybe used to doing through github.com and the terminal, if you want to do on the terminal, but the one I’m going to use is I’m going to do gh pr checkout and the name of this pull request.

20:57 Now what this does is, it takes Fran’s code and it checks out into a new branch locally. And now in my working directory, I have all the files with her changes. What I could do is I can, if I open up VScode now, I can actually make changes to the things she’s done. Let’s see if I can do anything, which is pretty non-destructive. What can I do, which doesn’t matter, “markdown”, “events”, add two dots here. git status, git diff, I’ve added a minor change here, minor change as if I was working myself, but remember I’ve got her pull request checked out. Now, if I do git push, GitHub CLI set up all the remotes and everything properly to track this pull request, and I’ve now pushed to Fran’s fork of this repository. And because of that, it’s updated her pull request with my file, my change, which is in this case, a bit irritating, but this workflow is brilliant when you’re reviewing other people’s code. Cause if you’ve got lots and lots of minor changes, like wording things, instead of making loads and loads of comments on the GitHub interface or whatever, if there are things you’re confident about, you can just go in and you can just edit them and commit them and just push them to the pull request yourself directly, which saves everybody loads of time. Because you don’t need to wait for the other person to respond. They don’t, you know, they don’t need to apply all the things you’ve suggested. You can just do minor changes directly. And this is of course, really good if there’s multiple people working on the same pull request as well. And the GitHub command line client just takes out all the thinking, all the configuration to be able to do that. You just do gh pr, check out the number, do your work, commit push.

22:42 There are some cases where this won’t work, but for majority of times this works super, super cool. I’m going to quickly just make sure that my master branch is up to date with the bad fork, which it wasn’t, gh pr checkout, go back to Fran’s pull request, and I’m going to update it now by git merge master. I’m bringing in my master fork, which will update her branch and I’m going to do git push again, and it will push in the updates here. Now that, if I refresh, that should be gone. Now her pull request is up to date. This is also really useful when there are merge conflicts, because if I’d done git merge master and there’d been merge conflicts, even really complicated ones, I could then resolve them locally in VScode or however, take as long as I want, commit that and push it to the pull request. That’s usually how I resolve merge conflicts, by doing GitHub command line, check out the pull request, fix it, push it.

23:53 That’s good to go. Now I can actually go a bit for the next step. I just check out master. I can now merge her pull request and just give it a thumbs up. I bet I could do this, just to see if I can do this from the command line, I bet I shouldn’t be able to do it through VScode or on the command line if I wanted to, you know, review it when I’m going to do gh pr merge, see what happens, merge conflicts, done, all through the command line, pretty cool.

24:36 Final final thing, I’m running a bit late. That’s a GitHub command line. You can do loads of stuff. Look, this is all just with pull requests. You can also do gh pr view --web and stuff like that with GitHub command line client, there’s loads of stuff. Check it out and see if it can streamline your workflow. One of the things I also use it for is I have a couple of helpers. You might’ve actually seen me use one just then, I have one called a gupdate master. For example, you can see this in my dot files over here. This is a little function. All it does is it takes this argument and it pulls my local changes from my fork. And then it pulls the changes from the upstream fork, assuming that there’s an upstream. Then it pushes those changes back to my fork again. And then it cleans up any dead branches, which have been merged. That’s like a little helper function, which I find really helpful. And you can see… um, maybe it doesn’t… I was thinking it used to get up command line client. This one does ghprs actually uses the GitHub command line client here and exports json. And then it uses jq to do cool stuff.

25:44 Because the GitHub command line client knows your authentication, does clever stuff with json, you can do really powerful little bash snippets using a GitHub client line client if you want to get fancy. Check out these, if that’d be helpful for you, gs I use all the time, gupdate and gclean I use all the time, uh, just little shortcuts that your fingers get used to. Right. I’ve been talking too long and I’m waffling on and on and on. Let’s go on and see if we have any questions or any discussion and any things that I’ve done badly, which you think you could do better yourself.

26:19 (host) Thank you, Phil. Now I know what it takes to get my code reviewed and merged. Um, so are there any questions in the audience? I think everyone is just amazed. If there are questions coming, you can always go to Slack and in the bytesize channel, or you can ask Phil directly. If there are no questions otherwise, then I would like to thank Phil for yet another impromptu bytesize talk. And of course, as usual, the Chan Zuckerberg Initiative for funding the talks and all of you for listening. (speaker) If we’ve got any volunteers to show me how to use git lens properly, that’d be a good follow on talk. (host) Thanks.