Note: I've seen a few people talking about this article as a "beginners guide to Git and Github". That's really wasn't my intention at all. This is just the very minimum Git and Github knowledge that you need to participate in the Weekly Challenge. That's a very specific use case. If you're starting to use Git and Github for general development, then you're going to need a lot more than what I cover here. See the "Further information" section at the end of this post for a couple of good links.

The Weekly Challenge has been running for about eighteen months and it has become a really popular way for people to flex their programming muscles. It started as the Perl Weekly Challenge but has evolved to embrace any language that you might want to use. Every week they publish two puzzles that participants are encouraged to solve using a Perl program (or, indeed, any other programming language of their choosing).

This week I read a blog post giving some reasons why the author didn't take part in the challenge. One of those reasons was that solutions are submitted using Git and Github and she didn't feel she knew enough about those tools to do this. I assume that if one person mentions that as a problem then there must be several others thinking the same way. So in this post, I'll explain enough about using Git and Github to enable anyone to take part in the challenge.

We'll start with a couple of definitions.

Git and Github

Git is a source code control system. It was created in 2005 by Linus Torvalds and has quickly become the standard source code control system for most open source projects. I have to think back a very long way to remember the last client I worked for that wasn't using Git to store its source code. Git is a distributed system - that is, many developers can have their own local copy of a source code repository and Git supplies tools that make it easy to incorporate changes from other developers' repositories into your local repository. Another of Git's strengths is the ease with which you can create branches of your repository - so that experimental work you're doing for a new feature is kept separate from the production-ready version of the code. Then, when you're satisfied that your new code is ready to be released, you can merge your experimental branch into the main branch. This is a very common development model.

Github is a system for hosting Git repositories. It's far from being the only such system (Gitlab and Bitbucket are two other well-known systems) but it has become the most popular. Github allows you to host a central version of your Git repository on their servers and it is then easy for other developers to take a copy of your repository and then submit changes to your code - using a system called pull requests. Github also gives you other features - an issue tracker, a wiki, project planning, continuous integration and hosted web pages - but it's copying someone else's repository and submitting a pull request that we'll need to concentrate on here.

Getting started

We'll be using both Git and Github in order to participate in the Perl Weekly Challenge, so we'll need to get both of them set up before we can begin. We'll ensure that Git is installed on our development machine and we'll register for an account on Github.

Installing Git

I'm going to assume that you're developing on some kind of Linux system here. If you're developing on Windows or macOS, then I'm sure that installing Git will be just as easy for you - it's just not something that I've ever done. Detailed instructions are available on the Git web site.

But Linux users have it really easy. Git will be available as a pre-built package for whatever distribution you are using. If you have a distribution that is based on Red Hat (including RHEL, Centos and Fedora), you can install Git with a command like:

$ sudo dnf install git

(On older versions of Red Hat, you'll need to replace dnf with yum.)

If you have a Debian-based distribution (which includes Ubuntu) then you can install Git using:

$ sudo apt-get install git

Once that command has finished, you can test that the installation has been successful by running git --version which will give you an output like this:

$ git --version
git version 2.25.4

Before moving on, it's worth configuring your email address and name. You can do that with these two commands.

$ git config --global user.name "Your name here"
$ git config --global user.email "your.email@your-domain.com"

Having installed Git successfully, we can move onto setting up your Github account.

Setting up a Github account

This is pretty simple stuff. If you visit github.com, you'll see a "sign-up" button in the top-right of the screen. Signing up is just a case of giving them a username, email address and password. You'll also need to verify your email address by clicking a link in the email they will send you.

Having set up your account, it's a good idea to add an SSH key as this will make it easier to use Git and Github together. You can do that by clicking on your profile picture (in the top right of the screen) and selecting the "settings" menu option. From the menu screen, you can choose "SSH and GPG keys" page and click the "New SSH key" button. You can then paste in the public version of your SSH key and give the key a title.

Now we can start looking at the Weekly Challenge code.

Getting the Weekly Challenge code

The repository for the Weekly Challenge code is at:

• https://github.com/manwar/perlweeklychallenge-club

We need to create our own copy (or "fork") of the code. You can do that by pressing the "Fork" button that you'll see in the top-right corner of the screen (just below your profile picture). A couple of seconds after pressing that button, the page will refresh and you'll be looking at your copy of manwar's repository. This copy is still hosted on Github's servers and the next thing you'll want to do is to make a local copy that you can work on.

It's up to you where you work on the code. I like to create a ~/git directory on any system where I'm doing development work and store all of my Git repositories in there.

The command we use to create a local copy of the remote repository is git clone. We'll need the address of your remote repository - you can get that by going to the web page for your repository and clicking the green button with a down arrow and "Code" on it. Pressing that will open a small window that contains the clone address for your repository (it will start git@github.com:...). Copy that address and then go to your ~/git directory in a terminal and enter this command:

$ git clone [paste address here]

That will whirr away for a short while, and when it has finished you'll see a new directory called perlweeklychallenge-club. If you change into that directory, you'll see all of the Weekly Challenge code.

Exploring the Weekly Challenge code

At the top level of the Weekly Challenge repository, you'll see a directory for each week's challenge. Presumably, you're interested in the most recent challenge - so change into that directory. You'll see a directory for each person who participates in the challenges. If you're taking place for the first time, then your name obviously won't appear there, so just create a directory with your name.

At this point, you can wander around the codebase and look at other people's solutions to earlier challenges. It's also worth reading the README file to find out more about submitting code to the challenge.

Taking part in the challenge

To take part in a challenge, you need to create another directory to put your code in. It's possible to submit solutions in many different languages and each language lives in its own directory. So, under the named directory that you created above, create a directory called perl (or raku or whatever other language you'd like to use). Your code then goes in these directories. It's best if you give your programs a standard name, so I use ch-1.pl and ch-2.pl for my Perl solutions.

Helping you solve the week's challenges is beyond the scope of this post, so let's just assume time passes and you have one or two solutions that you want to submit.

Submitting your solutions

Ok. At this point, you have one or two solutions in files that are stored on your local system. We need to go through a number of steps to get that into the main copy of the repository.

1. Add the new files to your local repository.
2. Commit the new files.
3. Push the changes to your Github version of the repository.
4. Create a pull request to add your changes to the main copy of the repository.

To add the new files to your repository, move back to the main perlweeklychallenge-club directory. You can then add your whole new directory in one command. If your new directory was called jane-doe then you would type:

$ git add jane-doe

You'll see Git reporting on the new files that it has found and added to the repository.

You then commit these changes with the command:

$ git commit

That will prompt you for a description of the changes that you've made, so write something like "Solutions for challenge 76" and close the editor. You can see your changes have been added to the repository by running the command git log which should show your latest commit at the top of the list.

You can then push these changes to the Github version of the repo by running:

$ git push

If you've set up your SSH key then this will run seamlessly, otherwise, you'll be prompted for your username and password.

If you now go to the Github page for your repository, you can refresh the page and see your new commit on the web site.

Finally, you need to create a pull request to copy your changes to the main Weekly Challenge repository.

At the top of your repository page, you'll see a "forked from" line which includes a link to the original repository. Click that to go back this version of the code. From there you can select "Pull requests" from the menu and press the "New pull request" button.

Because we're created a pull request based on your fork of the repository, we need to click the link labelled "compare across forks". You can then choose your fork from the "head repository" dropdown and that will show you the differences between your fork and the main repository. Hopefully, you'll recognise those changes as the files that you have just added. If you're happy with what you see, press the "Create pull request" button.

Congratulations! You have just submitted your first solutions to the Weekly Challenge. You can sit back and wait for Mohammad to notice your pull request and merge it into his repository. You'll then see your solutions mentioned in the next weekly round-up and your name will start to appear in the weekly stats. Hopefully, you will have enjoyed the process enough that you'll want to submit more solutions each week.

A little bit of admin

If you want to continue participating in the challenge each week, there's a little bit of admin that will make your life easier.

Obviously other people will be submitting changes to the main version of the repository and it would be nice if your version kept up to date with those. Not least because once you've submitted your first solution, your name will automatically be added to the new challenge directory that is added each week.

We can make it easy to keep your version in step with the central version by adding a new Git remote to your local repository. A "Git remote" is an address that your local repository recognises as a source for potential updates. You can see the remotes that your repository currently recognises by running the command:

$ git remote -v

You'll see two remotes listed (which are actually both the same remote); one is for reading from (marked as fetch) and one for writing to (marked as push). They are both called "origin" which is the standard Git name for the main remote repository that your local repository is linked to.

We can add another remote using the git remote add command. We'll need a name for the new remote and it's common to use the name "upstream" for a repository that your repository only ever pulls changes from.

As everyone will have the same upstream repository, everyone can use exactly the same command to add it as a remote:

$git remote add upstream https://github.com/manwar/perlweeklychallenge-club.git

Note that this URL starts with https://github.com/ whereas the URL for your own remote starts with git@github.com:. This demonstrates that you have read/write access to your repository, but only read access to the upstream repository.

Having run this command, you can list the remotes again and you'll see the upstream repository added (twice) to the list.

Once we have this new remote added, we can update our local repository to bring in the latest upstream changes by running:

$ git pull upstream master

And you'll see everyone else's changes being pulled into your local repository. And they'll be pushed to your Github repository along with your new solutions each week (and don't worry, Github is clever enough to not include those changes in your pull request).

I recommend running this command each week before you start work on the new challenge.

Further information

This has been a very quick introduction that just covered enough Git and Github to get you up and running on the Perl Weekly Challenge. There is a lot more to both Git and Github and I highly recommend that you spend the time to get to know more about both tools.

• There's a great book about Git that is available for free online.
• The Github documentation site is huge and covers everything you could possibly need to know about Github.

I hope this is useful. Please let me know if you have any further questions.