Fork your own Framework

Introduction

This post describes how to setup your own mirror (or fork) of Karttur´s GeoImagine Framework on GitHub.com, clone it to you local system, track your own changes as well as updates at Karttur’s upstream repo and suggest improvements. The most efficient setup is using git terminal tool, but it also works with GitHub Desktop; both alternatives are described in the post Git clone with GitHub Desktop and terminal. But in this post you will first fork the complete Framework and then clone it from a GitHub account that you have access to. This means that you can push any changes you make to your online repo, and then send a pull request to Karttur with a suggestion to incorporate your changes in the original code. Further, you can follow, and update your own mirror with, changes made in the Framework at github.com/karttur.

This post is a summary of my blog on git command line contains detailed tutorials on how to use git, including a tutorial on Forking repositories, and then ends with a post on git for Karttur’s GeoImagine Framework. This post is a summary of the blog git command line

Prerequisits

To fork a mirror of Karttur’s GeoImagine Framework that you can control, you must have your own GitHub account. GitHub.com. You then either use GitHub Desktop or the git commandline tool.

Karttur’s GitHub repository

Go to GitHub.com, if you do not have an account it is free to create an account, and sign in. Go to Karttur’s repository containing the complete GeoImagine Framework (kt-gi-test01). This repository in more or less an empty shell with all the GeoImagine Framework packages linked as submodules. The top level of the repository only contains a few files.

If you drill down (by clicking), first to Karttur2019GitHub (the PyDev project) and then to geoimagine, you will see the list of all python packages beloning to the GeoImagine Framework.

Clone the GeoImagine Framework project

This tutorial covers three routes for cloning Karttur’s complete GeoImagine Framework to your local machine:

1. Clone from online repository
2. Clone directly from GitHub Desktop
3. Clone using the git command line tool

Clone from online repository

In your web-browser, return to the top of Karttur’s assembled Framework project https://github.com/karttur/kt-gi-test01. Click the Clone or Download button and then click the Open in Desktop button. If you click “Download ZIP”, you will get a download but with empty submodules and this will not work.

Your local copy of GitHub Desktop will start, and then guide you through the cloning process.

Clone directly from GitHub Desktop

Instead of linking to GitHub Desktop from the online GitHub repository, you can start your copy of GitHub Desktop and go via the menu:

File –> Clone Repository…

In the window Clone a Repository that opens, fill in the Repository URL and the Local Path. When complete, press Clone.

Clone using Git command line tools

Start a Terminal session. Change directory cd to the parent directory where you want to save the GitHub project (repository):

$ cd /Users/thomasgumbricht/eclipse/repos

If you accept that the repo you are going to clone will have the same local name as online (recommended), execute the command:

$ git clone https://github.com/karttur/kt-gi-test01

If you want the local clone to have another name, instead use:

$ git clone https://github.com/karttur/kt-gi-test01 karttur-geoimagine-01

To speed up the cloning of multiple submodules (up to 8 parallel downloads) and get all the linked submodule repositories cloned (version 2.13 and later) you should be able to execute:

$ git –recurse-submodules -j8 clone https://github.com/karttur/kt-gi-test01 [karttur-geoimagine-01]

But with Git version 2.16 it did not work out for me.

Check that the cloned repo actually contain all the GeoImagine Framework python packages. if not, cd to the top directory (kt-gi-test01 or karttur-geoimagine-01). Then execute the following commands for initiating and then updating all the the submodule linked repositories.

$ git submodule init

$ git submodule update

Update submodules

To update all submodules to latest individual commit of each, run the command:

$ git submodule foreach git pull origin master

import or copy project to Eclipse

Regardless of which route you chose for cloning the GitHub repo containing the PyDev project and packages, you should now have a complete, working, clone in your local machine. The next step is to either import or copy the Framework project to Eclipse.