Karttur's git repos

Introduction

SSH keys

Creating a new GitHub repo

If I have understood correctly, you can only create an online GitHub repo using a browser and being logged in to your GitHub account. Explained in the GitHub page on Creating a new repository. However, you only need to create the repo, everything else can be done from your local command line as outlined on another of GitHub´s help pages Adding an existing project to GitHub using the command line.

Creating a new gh-pages blog repo

To be completed

Fork Karttur geoimagine

To contribute towards Karttur’s GeoImagine Framework you have to sign up with GitHub.com - see the post on Remote repositories with GitHub.

Fork indicidual packages

Indicvidual packages are named geoimagine-“package”.

Identify source repo

Go to Karttur’s GitHub account, and identify (search in the Find a repository) the repo you want to fork. If for instance you want to work with the package on database setup (setup_db) you should look for the repo “geoimagine-setup_db”.

Click on the fork symbol to retrieve (fork) the repo to your account.

Github - the master branch of the forked project.

Clone to local machine

To work with the package/repp you need to clone or download. The most difficult way to get the package to your local machine is to clone it with an SSH key (hidden credentials that allows you to seamlessly interact with from your local machine with your online GitHub account) or using GitHub Desktop. You can also download, but as you will have to push any changes to you GitHub account to particiapte in teh develoment, that is nto receommendd.

Clone using terminal

Open a terminal window and change directory (cd) to the parent folder where you want to have the clone of GeoImagine package. You need to consider the setup of your PyDev Integrated Development Environment (IDE). And locate the package/repo inside your IDE working directory setup for Karttur’s GeoImagine Framework.

$ cd /path/to/IDE/workingarea

While the onlne repo has the prefix “geoimagine” you shoudl remove that for the local clone. That is simply done using the standard clone command git clone [source-url] [target-name].

$ git clone git@github.com:thomasgumbricht/geoimagine-setup_db.git setup_db

Cloning into 'setup_db'...
remote: Enumerating objects: 10, done.
remote: Counting objects: 100% (10/10), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 124 (delta 2), reused 4 (delta 0), pack-reused 114
Receiving objects: 100% (124/124), 65.10 KiB | 653.00 KiB/s, done.
Resolving deltas: 100% (66/66), done.

cd to the cloned package/repo/directory and list (ls) the content:

$ cd setup_db
$ ls

README.md		doc			setup_db_main.py
__init__.py		setup_db_class.py	version.py

Create development branch

As a developer wanting to contribute, I suggest that you create a branch called dev and then use that for staging and committing edits to the codes and documents.

Working with branches is explored in detail in the post git branches in local repositories, expanded for use with GitHub in Remote repositories with GitHub and also how to use with forks in Forking repositories.

With the Terminal window still in your local repository (“setup_db”), type:

$ git branch

* master

There is only one branch in your repo - master.

Create a new branch and immediately switch to this branch: $ git checkout -b dev

Switched to a new branch 'dev'

Make some edits

to start the newly created development branch you need to make at least a minor edit to one of the included files. Changing a text string in README.md is sufficient.

$ pico README.md

# geoimagine-setup_db

%%%% Edits added by "githubuser" marked by "%%"  %%%%

Stage and commit changes

With edits done to the source files you can stage (add) and commit (lock in and save) the changes to your local git repository:

git add . git commit -m ‘edits to README.md’

If you did not create a new file, you can add (-a) the staging to the commit command, and insted of two commands just execute the one:

git commit -am ‘edits to README.md’

You can check out is anything is pending in the active branch (dev):

$ git status

On branch dev
nothing to commit, working tree clean

To get a graphical view of the commit log:

$ git log –all –decorate –oneline –graph

* a4efe67 (HEAD -> dev) edits to README.md
*   217a091 (origin/master, origin/HEAD, master) Merge pull request #1 from karttur/setup_db_main-edits

From the returned message you can see that the local HEAD pointer is ahead of origin/master, origin/HEAD, master, where origin is the default alias for the primary remote repository.

Push

Confirm the remote connections of the cloned repo you are working with:

$ git remote -v

origin	git@github.com:thomasgumbricht/geoimagine-setup_db.git (fetch)
origin	git@github.com:thomasgumbricht/geoimagine-setup_db.git (push)

To send your local changes to your GitHub online account, use the git push command:

$ git push -u origin dev

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 4 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 342 bytes | 342.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote:
remote: Create a pull request for 'dev' on GitHub by visiting:
remote:      https://github.com/thomasgumbricht/geoimagine-setup_db/pull/new/dev
remote:
To github.com:thomasgumbricht/geoimagine-setup_db.git
 * [new branch]      dev -> dev
Branch 'dev' set up to track remote branch 'dev' from 'origin'.

If you execute the extended log, you will see that the branch origin/dev has been added, and is up to date with the local dev branch.

$ git log –all –decorate –oneline –graph

* a4efe67 (HEAD -> dev, origin/dev) edits to README.md
*   217a091 (origin/master, origin/HEAD, master) Merge pull request #1 from karttur/setup_db_main-edits

Return to your browser and your online GitHub account with the fork of “geoimagine-setup_db”. There should now be one additional branch. If you click on the button Branch: master a dropdown menu shows all the branches (and some actions you can take).

Github - the dev branch with your edits of the forked project.

Review and verify edits

You have made some edits and you want to either merge you edits into you own version of master or submit them to Karttur for updating of the original system (the repo residing with karttur itself). To review and verify edits use the git diff command. To find the differences between two branches:

$ git diff master..dev

diff --git a/README.md b/README.md
index 85d8158..85e7484 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # geoimagine-setup_db

+%%%% Edits added by "githubuser" marked by "%%"  %%%%
+
 Karttur Geoimagine database setup python project

 ## Introduction

As the local clone is in sync with origin, the result will be the same if you compare the remote branches:

$ git diff origin/master..origin/dev

If the edits are extensive you can compare difference on a file basis:

$ git diff master..dev --\ README.md

pull request

At this stage, with reviewed and verified edits that you feel Karttur’s GeoImagine Framework would benefit from incorporating, you should create a pull request.