10Collaborative working

I need two GitHub user accounts to demonstrate this, and fortunately I have them, I have the practicalseries-lab account and I also have a michaelgledhill account.

I’m going to logon to the michaelgledhill account and copy the lab-01-website repository into a new repository in that account; this is a process that is referred to as forking in GitHub terminology.

This is the michaelgledhill home page, you can tell, it’s got my picture at the top:

Figure 10.1   The michaelgledhill newsfeed page

I can search for any repository in GitHub by typing all or part of its name into the search github box at the top.

If I type lab-01-website I get this:

Figure 10.2   Search for lab-01-website

If I click practicalseries-lab/lab-01-website link it takes me to the repository home page:

Figure 10.3   The lab-01-website website viewed from another user profile

Now this looks just the same as it did when we were logged in as practicalseries-lab; the only difference can be seen at the top, it’s got my picture instead of the practical series logo.

There is a difference if you try to modify a file, if I click the README.md file and then try to edit it, I get the following message:

Figure 10.4   Editing a file in another users repository

It tells me “I’m trying to edit a file I don’t have write access to”. It also says it’s “created a fork for this project”. And indeed it has done so, this is one way of forking a repository—but this is not the usual way of doing it.

Go back to the repository practicalseries-lab/lab-01-website repository home page (Figure 10.3).

The easiest way to fork (create a copy of the project in a different profile) is to just click the fork button at the top. If you hover the mouse over the button you get this:

Figure 10.5   Fork a repository

It tells me it will make a copy of the repository in my account (the michaelgledhill account).

If I click the fork button, point 1 in Figure 10.3 I get this:

Figure 10.6   Forking in progress

This screen hangs around for a few seconds^†1.

It then takes me to the home page for the repository, but in the michaelgledhill account (not practicalseries-lab). I.e. it is the home page of the copy, not the original.

Figure 10.7   The forked repository

The clue to this being a copy is at the top, it says:

It is in the michaelgledhill account, not the practicalseries-lab account, indeed the next line tells me it’s been forked from that account.

So there we are, I’ve forked (copied) a repository from one GitHub profile to another.

Let’s have a quick look from the practicalseries-lab side of things. If I sign in to the practicalseries-lab account and go to the lab-01-website repository home page I have this:

Figure 10.8   The original repository

I can see that someone has forked the repository (the 1 highlighted).

I can even find out who, if I click the number next to the fork button, it takes me to a network diagram of the repository:

Figure 10.9   The original repository network

It shows a kind of network of the repository, it shows where branches have been created and commits made—it’s a poor man’s version of the London Underground diagrams I use in my examples. It’s not particularly useful.

Click the members tab (highlighted):

Figure 10.10   The original repository members

This shows who has made a fork of the repository, just me in this case.

†1		I think this is a false delay screen, it implies it’s copying the repository and it takes a few seconds; when I tried to edit the file, it forked the repository instantly.

Just look at that title, creating a pull request on a forked repository—It’s gibberish—it would mean absolutely nothing to a normal person.

Back to the forked repository in the michaelgledhill profile, it looks like Figure 10.7.

This forked repository is for all intents and purposes just a repository in the michaelgledhill profile, it could be cloned to a local repository (just like we did in § 5.3) and managed through Brackets. The difference here is that GitHub knows it was copied from some other repository.

If we modify our copy of the repository, we can send our changes back to the original in the form of a pull request that the owner of the original repository can merge back into the original (or reject by closing the pull request). This is exactly the same process we went through with pull requests when merging branches.

I’ll run through it, I’m going to modify the README.md file in the forked repository; I’m just going to put a new line in at the top:

Figure 10.11   Modifying a forked repository

Add the commit message and click commit changes.

Go back to the forked repository home page (the change will be visible at the bottom):

Figure 10.12   Forked repository after the modification

Now I’ve modified my forked copy of the repository, I can send this change back to the original repository by creating a pull request (highlighted above), this is the same process as merging two branches (§ 9.5.3). Click the new pull request button:

Figure 10.13   Forked repository create a pull request

The important bit here is the section I’ve highlighted; it shows that the pull request has a base (receiving) repository set to the original practicalseries-lab/lab-01-website master branch; the other side is the forked repository. It also says the files can be merged without conflict.

I’ll create the pull request by clicking the create pull request button.

Figure 10.14   Forked repository open the pull request

This time I’ve added a comment in the box. I click the green button to create the pull request.

Now I get this:

Figure 10.15   Forked repository pull request

There are a couple of things here, the first is that I can’t merge the pull request, the line in the middle says “only those with write access to the repository can merge pull requests” and I don’t have write access to the original.

There are two things that I can do from here; I can close the pull request myself by clicking the close pull request button (highlighted). By closing it (if say, I’d made a mistake) I would stop the pull request bothering the owner of the original repository.

I can also send further comments if I want to.

Let’s look at it from the practicalseries-lab side (the owner of lab-01-website):

Figure 10.16   Viewing the pull request from the original repository

I can see that there is 1 pull request. If I click the tab I can view all the pull requests:

Figure 10.17   The pull request list

Clicking on the pull request itself, opens the full details of the request:

Figure 10.18   The pull request page

This time I can merge the pull request (I’m the owner of the repository), I can also just close the request or I can generate a comment.

This time I’m going to close the request (not implement it), but I will do it with the message:

No, I don’t want to do this.

I’ve added the message to the box and I close the request by clicking the close and comment button.

Figure 10.19   Closed pull request from the owner’s side

If I go back to the michaelgledhill profile, I don’t see anything that tells me what has happened, there are no messages and there is nothing in the pull request tab.

Figure 10.20   Closed pull on the forked repository home page

The pull requests tab only shows pull requests that are made to this repository (if say I added a branch and wanted to merge it back in).

To view pull requests that have been made by this user, click the pull request link in the black bar at the top (highlighted), it gives the following:

Figure 10.21   A user’s created pull request page

This page by default shows all the open pull requests I’ve created. It also tells me that I have 1 closed request. If I click this I get a list of all the closed pull requests:

Figure 10.22   A list of closed pull requests

Finally, if I click the particular request I see the closed message:

Figure 10.23   The specific closed pull requests

This is exactly the same page as Figure 10.19. It opens the pull request page from the practicalseries-lab repository.

If instead of rejecting the pull request (I clicked close and comment, Figure 10.18), I wanted to merge the changes into my repository, I would click the merge pull request button (Figure 10.18) and this would merge the changes into the master branch of the practicalseries-lab/lab-01-website repository and this would be exactly the same process I covered in section 9.5.3 (if there were no conflicts) or section 9.5.5 (if there were conflicts).

Ok, this is going to be easy.

The question is:

How can I keep my forked repository in synch with the original?

And the answer is:

You can’t—not from GitHub

So that’s that.

You should be able to, it’s a bit like keeping a local copy of a repository in synch with a remote repository, and you should be able to do the equivalent of a pull to get the latest changes in to the forked copy.

But you can’t, GitHub just doesn’t have the facility.

There is a way around it by using a local repository as an intermediary, but It’s convoluted and confusing and I don’t cover it here.

Since I’m not a great fan of forking in the first place; I can’t get too worked up over this—it does seem to be a deficiency with GitHub though.