Most things are easy once you know all the jargon and have done it for a while. That broke down for me with Github. It seemed that everybody just assumed that everybody else already knew all the jargon, and nobody bothered to explain how to do anything step-by-step.

1. Fonts missing from OSM Promotional Leaflets
2. Github HowTo: Clone Repository then make a Pull Request
3. Printing OSM Promotional Leaflets
4. Update to OSM Promotional Leaflets due to Padding errors
5. Adding a Preview JPG + crop-marks for printing

I cannot explain everything about git nor Github, but I’ve just successfully created my first git Repository on Github by forking another repository, have cloned it to my local Desktop, made three commits & also a pull request. So, whilst everything is still reasonably fresh in my mind & I have the history available to report it all to you, here is some of what all that shit means and how to get into it if you want to do something similar.

Brief Background & Overview

Near the end of last year (2018) I tried to use Andy Allan’s OSM Promotional Leaflets to get some little giveaway-leaflets printed, and failed. It was missing some crucial items & also needed updating, so I tried, and eventually succeeded in updating it, and also made a post about that: Fonts missing from OSM Promotional Leaflets.

I’ve found Andy to be tremendously helpful in the past, so I was also privately in conversation with him about his Repository. He suggested that I make a Pull Request as to add links for the necessary fonts to the README file. I thought that that might be a great idea, just as soon as I could find out what a Pull Request was, and then how to do it.

Git + Github Overview

My home computer is powered by Devuan (a variant of Debian), and I have been working with various versions of Linux for the last 20 years, ever since I realised that the corporate world had decided that I was too old at 50 to be viable as an employee so decided, with essentially zero prior experience, to become a network engineer in charge of an enterprise, internet-connected computer. The enterprise + the computer were entirely owned by me, but that was fun! In part.

Linux is one practical realisation of the power of the Open Source movement (as, in another way, is OSM, and the Scientific community). One fundamental feature of Open Source software is that it is freely available to all to Fork (which means, to copy in it’s entirety and to then develop it further in the way that you see fit). Of course, a better way may be to feed bugfixes/improvements back to those developing a software suite so that it can continue to improve, but perhaps you get the point. git & GitHub is a means to implement that process.

git

a version control system for tracking changes in computer files and coordinating work on those files among multiple people

It was originally written by Linus Torvalds (the same guy that wrote Linux, and who still keeps an iron grip over the Linux kernel).

GitHub

a web-based hosting service for version control using Git

Founded in 2008 as a USA LLC, and sold 10 years later to Micro$oft for the silly sum of USD $7.5 billion. In June 2018 it had 28 million public repositories. That figure went from 46,000 one year after being founded (Feb 2009) to 1 million (Jul 2010) & 2 million (Apr 2011).

It is free to create a username on GitHub. It is also free of financial charge to create a Public Repository, but a Private Repository requires a monthly payment (‘repositories’ are places to store files; they can also contain sub-directories of files, to any depth). Public Repositories are truly public, as anyone can copy the content. Most will keep upload private, which is where the phrase Pull Request comes in (request the Repository owner to pull in — Merge — some extra and/or changed files).

The key to understanding the interaction between git & GitHub is that git (which is the software) can be used to control a set of files either remotely or locally, and that one of the things that it expects is to handle copy/clone or update operations between two mirror Repositories, one of which is local & the other of which is remote. Typically, the remote Repository is held within GitHub whilst the local mirror may be one of (possibly) hundreds of local mirrors being worked on at any place within the world. There can thus be hundreds of updates to the remote mirror from the distributed local mirrors. In addition, each local mirror will have a schedule of regular updates from remote to local in order to keep up to date with changes from all other users.

Here were my recent actions step-by-step:–

1. Create an Account on GitHub
     
   This is needed only if you need to update a GitHub repository (no GitHub account is required to retrieve a file from a GitHub public repository).
    
   Go to GitHub and create a username. It needs to be unique.
    
   My OSM username was already taken (dammit) so I originally chose ‘Alexander-Kemp’. Fortunately GitHub has a rename-facility (under Settings | Account), so I renamed to ‘alexkemp9’. Do not do anything like this after you have created a repository.

2. Fork an Existing Repository
   (see also Forking Projects)
    
   Whilst logged in (that’s the bit that foxed me for a bit) go to the project that you are interested in & click on the Fork link at top-right.
   After GitHub has finished processing you should be back at your own repository page & able to see the newly-forked repository.

3. Clone an Existing Repository
   (see also Cloning Repositories)
    
   (2022-June-23: the method has changed from my original writing):
    
   Partway down the page near the right-hand-side of a Repository page is a green “Code” button:
   
   Click on the green “Code” button to obtain a clone-URL:
   
   All you will need is the HTTPS URL that it provides.
    
   This is the relevant page for the repository that I cloned:–
   https://github.com/alexkemp9/openstreetmap-promotional-leaflets
   And the HTTPS clone URL provided from that page is:–
   https://github.com/alexkemp9/openstreetmap-promotional-leaflets.git
    
   That repository was cloned to my hdd by taking the following actions at the terminal command-line (note that for me git was already installed; go to git downloads if you are on Windows/Mac and need to install it, or use your normal distribution install methods if you work under Linux):–

    cd ~/    
    git clone https://github.com/alexkemp9/openstreetmap-promotional-leaflets.git    
   

   That creates ~/openstreetmap-promotional-leaflets/, drops all files from remote into the directory including ~/openstreetmap-promotional-leaflets/.git + necessary plain-text entries to help make it easy to push/pull files up/down from remote. The .git hidden directory is also the point of cloning — rather than copying — the repository (a full-stop at the start of a file and/or directory name means that it is hidden from ordinary file-listings). Cloning the repository means that you will be keeping the local mirror in step with the remote mirror.

4. Update the Clone
   (see also Fonts missing from OSM Promotional Leaflets)
    
   (I copied various files across from my earlier work to the clone repository)

5. Commit then Push the Clone
   (see also How can I upload committed changes)
    
   git needs to be informed of changes to the local mirror before you can push those changes up to GitHub. git maintains a config file in 3 possible places:–
   > a. local — <repository>/.git/config — repository-wide values
   > b. global — $HOME/.gitconfig — per-user fall-back values for .git/config
   > c. system — /etc/gitconfig — system-wide default config

   Here is the bunch of commands that committed all changes to git and then pushed those changes up to remote. The GitHub email address is found at Settings | Emails. git config commands are one-time for each --local (default), --global or --system.

    $ cd ~/openstreetmap-promotional-leaflets
    $ git config --local user.name 'alexkemp9'
    $ git config --local user.email '46583865+alexkemp9@users.noreply.github.com'
    $ unix2dos -n README.md README.txt
    $ git add ./*
    $ git status
    On branch master
    Your branch is up-to-date with 'origin/master'.
    Changes to be committed:
      (use "git reset HEAD <file>..." to unstage)
       
    	modified:   README.md
    	modified:   README.txt
    	new file:   osmflyer.pdf
       
    $ git commit -m "Added osmflyer.pdf (combo of osmflyer?-r15371.pdf)"
    [master e47f9a6] Added osmflyer.pdf (combo of osmflyer?-r15371.pdf)
     3 files changed, 22 insertions(+), 22 deletions(-)
     create mode 100644 osmflyer.pdf
    $ git push origin master
    Username for 'https://github.com': alexkemp9
    Password for 'https://alexkemp9@github.com': 
    Counting objects: 5, done.
    Delta compression using up to 4 threads.
    Compressing objects: 100% (5/5), done.
    Writing objects: 100% (5/5), 16.12 MiB | 601.00 KiB/s, done.
    Total 5 (delta 3), reused 0 (delta 0)
    remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
    To https://github.com/alexkemp9/openstreetmap-promotional-leaflets.git
       bb69dda..e47f9a6  master -> master
   

   git config -e will launch the default terminal editor with the relative config file loaded. Be careful, since that editor may be vim (which is fine if you are a fan of the ’60s or ’70s). Use sudo update-alternatives --config editor to find which is the default, and change it if you wish.

    $ cd ~/openstreetmap-promotional-leaflets
    $ git config -e
    ^K  I    ~/openstreetmap-promotional-leaflets/.git/config (ini)
    [core]
            repositoryformatversion = 0
            filemode = true
            bare = false
            logallrefupdates = true
    [remote "origin"]
            url = https://github.com/alexkemp9/openstreetmap-promotional-leaflets.git
            fetch = +refs/heads/*:refs/remotes/origin/*
    [branch "master"]
            remote = origin
            merge = refs/heads/master
    [user]
            name = alexkemp9
            email = 46583865+alexkemp9@users.noreply.github.com
   

6. Create a Pull Request
   (see also Pull request from a Fork)
    
   Finally! At the end of this marathon I created a Pull Request.
    
   The main issue is to go to the Repository that the Fork was created from and click on the “New Pull Request” button to the right of the “Branch” menu: