GitHub

GitHub is a free development platform that allows programmers to easily upload and share code. As a Tethys developer, you will want to become a GitHub expert as it will make your life much easier. The best way to learn how to develop specific features in Tethys is to find another Tethys app that does what you are looking for and then download and view the code. With GitHub, this can literally be done in a few seconds in many cases. In this unit, we will learn some of the basics about using GitHub.

Creating an Account

If you do not already have one, the first think you will want to do is create a GitHub account. CLick on this link:

https://github.com/join?source=header-home

and follow the instructions. If you already have a GitHub account, go to the GitHub site and log in.

Installing Git

In order to take full advantage of GitHub, you need to install the a software package/utility called Git on your local machine. How you do that depends on your platform (Mac OS X, Windows, Linux). This website:

https://www.atlassian.com/git/tutorials/install-git

has an excellent set of instructions for installing Git. If you have not done so before, please take a few minutes to install Git on your computer before continuing.

Please note that after installing Git, you will need to configure it with the user name and password you created with your GitHub account.

GitHub Basics

In addition to allowing users to share code, GitHub provides a sophisticated software versioning system. This is particularly useful when working with a team of developers. You can have one copy of the current version of your code called the master version and then create one or more branches representing various new developments/bug fixes/etc that represent a deviation from the master version. These can be merged into the master code or combined to make a new version of the software. In order to use GitHub correctly, you need to have a basic understanding of conceptts like repositories, branches, commits, and pull requests.

There are many great resources on the web for learning about GitHub and the Git software. Probably the best place to start is the Hello World tutorial hosted on github.com:

https://guides.github.com/activities/hello-world/

This is a nice interactive tutorial on Git:

https://try.github.io/levels/1/challenges/1

Some additional learning resources:

https://help.github.com/articles/git-and-github-learning-resources/

Feel free to google additional resources.

Cloning a Tethys App

OK, next let's explore how to clone an existing Tethys app. This is what you do when you find an app you are interested in and want to quickly make a copy on your own machine so that you can view the source code. To find some apps, go to the main GitHub site:

https://github.com/

and type "tethysapp" in the search bar at the top and hit Enter.

You should see a big list of Tethys app repositories. Any of these apps could be cloned to your computer. You may wish to look through the ones you have found.

We will clone a simple app that simulates construction dewatering using simple well equations for an unconfined aquifer.

1. Click on this link:

https://github.com/astraiophos/tethysapp-dewater

2. On the right side of the repository, click on Clone or Download link and then click on the button to copy the URL to the respository.

 

3. Now bring up a terminal window and go to your home directory. Then path to your tethysapps directory:

$ cd tethysapps

This should put you in the main directory where your Tethys apps are located. If you type

$ ls -l

you should be able to see a list of your installed Tethys apps. We want to clone the dewatering app here.

4. To clone the app, type the following:

$ git clone URL

Where URL is the URL that you copied to the clipboard. In other words, type $ git clone then paste the URL from the clipboard. When you are done, it should look like this:

$ git clone https://github.com/astraiophos/tethysapp-dewater.git

Then hit Enter.

Look at the contents of the folder. You should see a directory called tethysapp-dewater. Path down into that app and you should see a copy of all of the files on remote repo. Type:

 $ ls -al

and you will see the hidden git folder (.git).

Note that you can browse through the complete set of files associated with the app and open them in your IDE. You now have complete access to the code for this app.

5. To complete the installation, we need to install the app we just downloaded. Make sure you are at the top level of the new directory you just created. There should be a file at that level called setup.py. This is used to install the app on your portal. Before we run this, we need to be in the Tethys virtual environment in order for this to work. If necessary type:

$ conda activate tethys

to launch the Tethy virtual environment. Then to install, type:

(tethys) $ python setup.py develop

To try out the app, launch the Tethys portal:

(tethys) $ tethys manage start

and refresh the browser on the page for the Tethys Portal.

Creating a New Remote Repo

Suppose you created a tethys app and you want to put it on GiHub as a remote repo to share with others or just to archive. Here is a generic guide on how to do that:

https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/

But for this to work correctly in a Tethys environment, you need to be careful how you name things. Using the standard tethys naming convention, each app is located in the tethsydev folder in a subdirectory entitled tethysapp-XXX where XXX is the name of the app. For example, an app named mycoolapp would be in:

/tethysdev/tethysapp-mycoolapp/

Ideally, the remote repo is named and organized in such a way that whenever someone clones it, it creates a local copy of the files that follow this same hierarchy so that you don’t get confused by extra layers of folders. To keep things as clean as possible: do the following:

1. Go to GitHub and create an empty remote repo by clicking on the New repository link:

Then name your new repo exactly the same way your app is spelled:

Do not initialize with README, license, etc. Keep it clean and simple.

2. Open a terminal window

3. Path to your local directory (/tethysdev/tethysapp-mycoolapp/)

4. Initialize your local directory as a Git repo:

 $ git init

5. Add all of your local files to the repo. This adds them to the index.

 $ git add .

6. Commit the files. This adds them to the HEAD and give the commit a message. The message is like a label that is used to identify the commit.

 $ git commit -m “First commit”

7. At the top of your GitHub repository's Quick Setup page, click the copy-to-clipboard icon to copy the remote repository URL.

8. Paste the URL to the following command to link the local repo to the remote repo. (Shift-Insert on Ubuntu BASH).

 $ git remote add origin <remote repository URL>

Verify your URL (optional):

 $ git remote -v

9. Push your local repo to the remote repo. This takes everything (your commit) in the HEAD and writes it to the remote repo.

 $ git push -u origin master

Each repo has a default branch called master. When you create a new repo, it takes this name automatically. After executing this command, you will need to enter your github user name and password.

Some Useful Git Commands

Here is a list of some Git commands that you may find useful.

$ git status
Displays a summary of the status of your repo

$ git add <filename>
Adds the file to the index

$ git add .
Adds everything in the local repo

$ git add *
Same as above.

$ git add ‘*.txt’
Adds all the *.txt files in the local repo

$ git reset <filename>
Unstages the file from the index/staging area. Opposite of add command.

$ git commit
Commits all the files in the staging area (index).

$ git commit -m <COMMENT>
Commits all the files in the staging area (index) and marks with the label COMMENT (in quotes).

$ git commit -a
Adds all the changes (new stuff and deletions) from your working area to the staging area (index) and commits them.

$ git commit -am <COMMENT>
Same as previous but with comment.

$ git reset - -hard
This discards any minor (or major) changes you have made in your working files since the last last clone/checkout/commit.

$ git checkout -- <filename>
Files can be changed back to how they were at the last commit by using the command: git checkout -- <target>. This gets rid of all the changes since the last commit for the file. In other words, it pulls or restores it from the index.

$ git log
Display a log of all the commits you have done with the repo

$ git remote add origin URL
Creates a link to a remote repo and gives it a name = ‘origin’. You get the URL when you create a placeholder for the repo on GitHub.

Git doesn't care what you name your remotes, but it's typical to name your main one origin.
It's also a good idea for your main repository to be on a remote server like GitHub in case your machine is lost at sea during a transatlantic boat cruise or crushed by three monkey statues during an earthquake.

$ git push -u origin master
The push command tells Git where to put our commits when we're ready. So let's push our local changes to our origin repo (on GitHub).
The name of our remote is origin and the default local branch name is master. The -u tells Git to remember the parameters, so that next time we can simply run git push and Git will know what to do.

$ git push
Push using previous settings. See above.

$ git push -u origin branch_name
A branch created locally is not available to others unless you push your branch to the remote repository.

$ git pull origin master
We can check for changes on our GitHub repository and pull down any new changes by running a git pull command.

$ git diff HEAD
This lets you take a look at what is different from your last commit. In this case we want the diff of our most recent commit, which we can refer to using the HEAD pointer. For example, you could do this right after doing a pull from the origin. The HEAD is a pointer that holds your position within all your different commits. By default HEAD points to your most recent commit, so it can be used as a quick way to reference that commit without having to look up the SHA. You want to try to keep related changes together in separate commits. Using 'git diff' gives you a good overview of changes you have made and lets you add files or directories one at a time and commit them separately.

$ git diff (1)
$ git diff --cached (2) ‘<— you can also use --staged in place of cached (synonyms)
$ git diff HEAD (3)
1. Changes in the working tree not yet staged for the next commit.
2. Changes between the index and your last commit; what you would be committing if you run "git commit" without "-a" option.
3. Changes in the working tree since your last commit; what you would be committing if you run "git commit -a"

$ git diff topic master (1)
$ git diff topic..master (2)
$ git diff topic...master (3)
1. Changes between the tips of the topic and the master branch
2. Same as above.
3. Changes that occurred on the master branch since when the topic branch was started off it.

$ git branch <branch_name>
Creates a new branch with the given name.
When developers are working on a feature or bug they'll often create a copy (aka. branch) of their code they can make separate commits to. Then when they're done they can merge this branch back into their main master branch. Branches are what naturally happens when you want to work on multiple features at the same time. You wouldn't want to end up with a master branch which has Feature A half done and Feature B half done. Rather you'd separate the code base into two "snapshots" (branches) and work on and commit to them separately. As soon as one was ready, you might merge this branch back into the master branch and push it to the remote server.

$ git branch
This displays a list of your current branches and shows you which one is the active branch.

$ git checkout <branch_name>
Switches the current branch to branch_name. If you have modified files in the working set, you will get an error message asking you to do a commit first. This is because when you checkout (i.e., switch to) another branch, it makes a complete swap of the working files in your local repo. You can do checkout on a branch located on a remote repo using this command and it downloads the branch. However, if you create a new branch locally, you need to push it to the remote repo to make it available to others.

$ git checkout -b new_branch
You can use this approach to checkout and create a branch at the same time. This is the same thing as doing:
git branch new_branch
git checkout new_branch

$ git rm '*.txt'
Removes all *.txt files from disk and removes them from the index/staging area.

$ git rm -r folder_name
Removing one file is great and all, but what if you want to remove an entire folder? You can use the recursive option on git rm by adding -r folder_name.
This will recursively remove all folders and files from the given directory.
If you happen to delete a file without using 'git rm' you'll find that you still have to 'git rm' the deleted files from the working tree. You can save this step by using the '-a' option on 'git commit', which auto removes deleted files with the commit:
git commit -am "Delete stuff"

$ git master
Switches back to the master branch in preparation for a merge (see below).

$ git merge branch_name
Merges the indicated branch into the current active branch. Typically, you do this from the master branch.
Git tries to auto-merge changes. Unfortunately, this is not always possible and results in conflicts. You are responsible to merge those conflicts manually by editing the files shown by git. After changing, you need to mark them as merged with git add filename. Before merging changes, you can preview differences using the diff command.

$ git branch -d branch_name
Deletes the indicated branch.
What if you have been working on a feature branch and you decide you really don't want this feature anymore? You might decide to delete the branch since you're scrapping the idea. You'll notice that git branch -d bad_feature doesn't work. This is because -d won't let you delete something that hasn't been merged. You can either add the --force (-f) option or use -D which combines -d -f together into one command.