OpenStreetMap

Github HowTo: Clone Repository then make a Pull Request

Posted by alexkemp on 12 January 2019 in English (English)

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. fork pic
    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)
     
    Halfway down the page on the right-hand-side of a Repository page is a “Clone or Download” button:
    clone pic
    All you will need is the URL that it provides.
     
    This is the relevant page for the repository that I cloned:–
    https://github.com/alexkemp9/openstreetmap-promotional-leaflets
    And the 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:
    pull request image

Location: Lace Market, St Ann's, City of Nottingham, East Midlands, England, NG1 1LJ, United Kingdom

Comment from Mateusz Konieczny on 23 January 2019 at 09:44

Thanks for contributing your changes and helping everybody else! Especially as it required you to go through the entire setup process.

git is powerful and useful (especially in programming) but noone sane will call it friendly to beginners - it is mostly result that it was created to support work of experienced programmers in developing Linux, so focus was on “fast, powerful, flexible” rather than on “newbies will not run away”.

Hopefully https://github.com/gravitystorm/openstreetmap-promotional-leaflets/pull/5 will be merged soon.

Comment from MarkusHD on 2 February 2019 at 17:03

GitHub’s pricing had been changed a few days before your diary post. You now have unlimited private repositories with your free account.

https://blog.github.com/2019-01-07-new-year-new-github/

Login to leave a comment