Join us for our weekly series of short talks: nf-core/bytesize.
Just 15 minutes + questions, we focus on topics about using and developing nf-core
pipelines. These are recorded and made available at https://nf-co.re
, helping to build an archive of training material. Got an idea for a talk? Let us know on the #bytesize
Slack channel!
Join us for this weeks bytesize with Phil Ewels (@ewels). You will get information about how to use the GitHub CLI and VSCode to make your work more efficient and less annoying!
Video transcription
Note
The content has been edited to make it reader-friendly
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
(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.