cgeb2001's DokuWiki!

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

===== GitHub repositories of the lab =====

//By Joran Martijn (Apr 2023)//

GitHub repositories are in its most basic form just //git repositories//, hosted on the internet by the GitHub company. To learn more about the basics of git, checkout the Tips and Tricks slides (and video recording!) [[https://perun.biochem.dal.ca/downloads/icgvideo/TAT/|here]]

==== The RogerLab repositories ====

The Roger lab has an 'organization' account on GitHub, created and currently managed by Joran. If you do not have account yet, create a free GitHub account and ask the current admin to add you. Under this account (click [[https://github.com/RogerLab|here]]), there are currently five repositories:

* gospel_of_andrew
  * fundicalc
  * garp_free_rates
  * gtr_test

These are are private repositories, meaning that only people with GitHub accounts that are members of the RogerLab GitHub organization can access them. They are invisible to the wider world. This is useful if you want to minimize the risk of your projects being scooped, for example.

The [[https://github.com/RogerLab/gospel_of_andrew|gospel_of_andrew]] is simply a collection of various utility scripts that are developed by members of the lab. It's purpose is mainly to serve as a central location where lab members can easily find scripts without having to ask around who has what script. Because it is git-tracked, we can also check past-changes or revert to older versions if newer versions break somehow. There is a README file which has a very brief description of what each script does. 
There is also a directory of ready-baked shell scripts for running softwares on perun. These can serve as templates for your own perun submission scripts.

The other repositories are used for in-development projects of the lab.

When you finish a manuscript and want to submit it to a journal, it is more and more common practice that you publish your code along with it. Your manuscript may for example have a short "Code availability" statement or something along those lines. Creating a public repository under the RogerLab account is an excellent way of doing this. Alternatively, you can create a private repository initially as you are working on your project, and when you are ready to publish, you can change it into a //public// repository.

==== The ICG repositories ====

I've also created a GitHub account for ICG. It isn't used a lot right now, but it may be in the future. These are the [[ https://github.com/orgs/Dalhousie-ICG/repositories|repositories]] currently part of this account.

The [[ https://github.com/Dalhousie-ICG/icg-shared-scripts|icg-shared-scripts ]] serves a similar purpose as the gospel_of_andrew repository, but for anyone within the ICG department.

===== Interacting with the repositories =====

==== Cloning a repository ====

To have access to all the scripts and other files in a repository on your local machine (your laptop, PC, MAC, etc), do the following:

* Open a new Terminal window
  * Go to the directory where you wish to have your local copy of the repository
  * In an internet browser, go to the GitHub website of your desired repository (e.g. https://github.com/RogerLab/gospel_of_andrew). This is the "remote".
  * Click the big "<> Code" button on the top right
  * Copy the displayed URL to your clipboard
  * execute ''git clone <copied_url>'', (e.g. ''git clone git@github.com:RogerLab/gospel_of_andrew.git'')
  * You may be asked to enter your GitHub username and password. If so, do so

The repository should now be downloaded to your local machine!

This means that you in principle don't have to download individual scripts anymore from the GitHub website, you have them all locally available to you. Internet access no longer required :)

In addition, you can now submit changes to the files in the repository and push these changes to the remote. You can also add your own scripts and push them to the remote as well!

==== Saving changes as "commits" ====

Let's say you have edited one of the scripts in the repository and you wish your version of the script to overwrite the current version of the script in the repo. We can do this!

Before anything else, it's good practice to run ''git pull''. This will ensure that we are working with the most up-to-date repo we have. Someone else may have made changes while we were working on our changes!

If we we're already working on the latest version, we see

<code>
Already up to date.
</code>

and we're good to go.

If not, you may something along the lines of

<code>
remote: Enumerating objects: 9, done.
remote: Counting objects: 100% (9/9), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 6 (delta 4), reused 5 (delta 3), pack-reused 0
Unpacking objects: 100% (6/6), done.
From github.com:RogerLab/gospel_of_andrew
   cf52972..f843408  main       -> origin/main
Updating cf52972..f843408
Fast-forward
 find_polyA_sites.py | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------------------------------
 1 file changed, 69 insertions(+), 51 deletions(-)
</code>

It tells us in this case that the find_polyA_sites.py script was modified in the last commit or commits that were lacking in our local copy of the main branch, and that our local copy is now updated with those changes. We're good to go.

Now, let's run ''git status'', while we are in the git repo directory. 
This git command is extremely useful and will always give you a nice overview of the current status of the repo. It is probably the git command I use the most. Here is an example output:

<code>
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   sketch_tree.py

no changes added to commit (use "git add" and/or "git commit -a")
</code>

Our current "branch" is "main". Don't worry too much about this now, to learn more about branches, check out the Tips and Tricks slides.

"origin/main" is our remote, and ''git status'' is reporting that we are up to date with the remote. It essentially means that the remote and our local copy of the repo are the exact same.

Then we see that the ''sketch_tree.py'' file has been modified! To see how the file was modified, we can run ''git diff sketch_tree.py'':

<code>
diff --git a/sketch_tree.py b/sketch_tree.py
index 9929356..a284b17 100755
--- a/sketch_tree.py
+++ b/sketch_tree.py
@@ -11,7 +11,7 @@ import sys
 # make command line interface
 parser = argparse.ArgumentParser(
     description="""Root, color and render a tree in PNG, SVG or PDF.
-                Roots with outgroup defined in the mapping file"""
+                Roots at midpoint"""
 )
 parser.add_argument(
     "-t",
</code>

It shows that in our edit, the line indicated with ''-'' (possibly colored in red in your terminal) was deleted, and replaced with the line indicated with ''+'' (possibly colored in green).
The lines above and below that merely show the context, to help identify where in the file the changes were made.

If we are OK with these changes, we can now "commit" these changes. We are in a way, committed, to make these changes, hence the word commit. To do so, execute the following:

<code>
git add sketch_tree.py
</code>

With ''git add'' we can control what changed files we want to commit. We may have more files in the repo that have changed, but we do not necessarily want to commit all these changes. Add all the scripts / files you want to commit.

<code>
git commit -m "rooting at midpoint, not with outgroup"
</code>

The text in the quotes is our **commit message**. Its a brief description of our commit, which will help us understand the reason for the change if we ever decide to go back and check out git commit history.

We see an output like this

<code>
[main f843408] rooting at midpoint, not with outgroup
 1 file changed, 1 insertion(+), 1 deletion(-)
</code>

It informs us that the "main" branch was updated with a commit, and the identifier of this commit is "f843408".

Our local "main" branch is now updated, but the remote remains unchanged. To also update the remote repo, we need to execute ''git push''

<code>
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 328 bytes | 328.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
To github.com:RogerLab/gospel_of_andrew.git
   dc36c1e..f843408  main -> main

</code>

A succesfull push! If you check the online GitHub repository now in your internet browser, the file should be updated!

You should now be familiar with the basics of interacting with a GitHub repository. Using git can be far more advanced, with different branches, re-basing etc etc but I'd say for 99% of our usecases this should suffice.

Please fill all the letters into the box to prove you're human. V W A E D Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International