Skip to content

Home

Jump to bottom
Skyler Kuhn edited this page Aug 19, 2024 · 8 revisions

project-template

Welcome to the project template wiki! This is a Github template you canuse in your projects. It is a minimal, barebones project scaffold that you can use as a starting point for your projects.

0. Pre-requisites

Requires: github account

Once you have created or logged into your existing github account on Github, you will need to create a personal access token (PAT) with repo scope. You can create a PAT by following the steps below:

Steps for creating a Github personal access token (PAT)

Please note: You should store your PAT in a secure place as you will not be able to see it again. If you lose it, you will need to create a new one. You will only need to do this once a year.

Github now authenticates using personal access tokens (PAT) instead of passwords. You will need to create a PAT with repo scope to authenticate and push anything to Github. To pull or clone a private repository, you will need to use the PAT as a password. When git asks for a username, you will use your Github username and for the password, use the PAT. Never share your PAT with anyone else. Treat it like a password.

It is worth noting that you should only need to do this once a year, if you follow the instructions below. You can use this personal access token across all your different Github repositories/projects.

  1. Go to your Github account settings.
  2. Click on Developer settings (at the bottom left of the side bar).
  3. Click on Personal access tokens (PAT) and Tokens (classic).
  4. Click on Generate new token and Generate new token (classic).

image

  1. Enter a name for your token under the Note field, set the Expiration as a Custom date a year from now, and click on repo as Select scopes.

image

  1. Click on Generate token, this will redirect you to a page with your PAT. Copy the PAT and store it in a secure place. Once you leave/exit/close this page, you will not be able to see the PAT again. If you lose it, you will need to create a new one. As so, you will want to save the github PAT to a safe location that no one else can access. Later, when git prompts you for a password, you will provide this long string of random numbers and letter. It should start with the prefix: ghp_.

image

Steps for installing Git

Please note: You can verify if git is installed on your local machine by running the following command in your terminal:

git --version

Git is a version control system that allows you to track changes in your codebase. You will need to install Git on your local machine to push and pull code from Github. Git is included in the Xcode Command Line Tools package. If you have already installed Xcode, you can skip this step.

If git is missing, you can install Git by following the steps below on macOS:

  1. Open a terminal on your local mac.
  2. Install Xcode Command Line Tools by running the following command: xcode-select --install
  3. Follow the instructions on the screen to install the Xcode Command Line Tools. This will take a few minutes to install, and may require you restart your computer.
  4. Once the installation is complete, you can verify the installation by running the following command: git --version
  5. If git is installed, you will see the version number of git. If you see an error message, you may need to install git manually. You can download the latest version of git from the git website.

1. Creating a new project from the template

You can create a new project with this template with the following steps:

  1. Click on the Use this template button on the top right of the repository, or visit this link to create a new repository.

image

  1. Select OpenOmics/project-template from the drop down in Repository template.
  2. Enter a name for your repository in the Repository name field, please ensure the repository name is matches the project name in AMP, for example: NCBR-123, NIAMS-123, NHLBI-123, NIDDK-123. Please make sure the Owner is set to OpenOmics.
  3. Enter a description for your repository in the Description field, just a small sentence or a few words will work.
  4. Select Private for the repository visibility. This will ensure only our group can see the repository. Before making anything public, please ensure you have permission from the PI or wait until the project is published.

image

  1. Click on Create repository button.

2. Cloning the repository

Once you have created the repository from the template, you can clone the repository to your local machine.

Please note: For a quick refresher on git commands, you can refer to this git cheatsheet or Github's gettings started page. There are a lot of great resources/videos online to learn git, so don't worry if you are new to git.

Here are a few basic git commands to get you started:

  1. Clone the repository to your local machine. This will download a local copy of the repository on Github to your local machine. We will will make our changes locally and push them to Github.
# Clone the repository to your local machine,
# please update this to your repository name,
# for example: NCBR-123, NIAMS-123, NHLBI-123, 
# NIDDK-123, etc. This will be whatever you 
# named the repository in step 3. when you 
# created the repository from the template.
# Ideally, you should should have named the
# repository the same as the project name 
# in AMP.
project_name="NCBR-123"  # please change this 
git clone https://github.com/OpenOmics/${project_name}.git
  1. Change directory to the repository you just cloned.
cd ${project_name}/
  1. Update the README to add your project name to the README.md. The easiest way to do this is with sed or find/replace in your text editor. I have provided to different commands. Please select the correct command based on your operating system. The first command is for macOSX, and the second command is for linux.

Here is an example sed command:

# On local macOSX laptop,
# Example sed on macOSX,
# this can be run on your local machine
sed -i '' "s/IC-123/${project_name}/g" README.md

# On Linux, i.e biowulf/helix,
# Example sed commnad on linux,
# this can be run on Biowulf
sed -i "s/IC-123/${project_name}/g" README.md

3. Adding your code or scripts to Github

Now that we have cloned the repository to our local machine, we can add our code or scripts to the repository. You can add your scripts to the scripts/ directory in the repository.

  1. Add your scripts to the repository. You can add your scripts to the repository by copying them to the scripts/ directory in the repository.
# Before you copy your scripts to the repository,
# let's pull in the latest changes from Github.
# This will ensure you have the latest changes
# from the repository on Github. Generally 
# speaking, it is a good practice to pull any 
# changes before you commit or push any changes.
# please make sure you are in the repository 
# directory before running this command.
git pull

# Copy the script into the script directory,
# please update the path to your script, this 
# is just an example.
cp /path/to/your/script/* scripts/

# Stage the changes to the repository, committing
# files to git is a two step process. First you
# stage the changes, then you commit the changes.
# Staging the changes is like telling git which
# files you want to commit. This will add all 
# files in the scripts/ directory to the staging.
git add scripts/
# Alternatively, we may not want to add everything
# in a folder/directory, we can add and stage a 
# single file via the follow command
git add script/deseq2_deg.R 
git add script/limma_deg.R 

# By default, any data copied to the data directory
# of this template will be ignored, we can override 
# this behavior, let's say we want to add a sample
# sheet containing sample to group information.
# This is a good example of data to include for 
# a project. Remember, we do NOT want to push any
# large files to github (such as FastQs, BAMs, etc.)
cp /path/to/sample/sheet/metadata.tsv data/
git add -f data/metadata.tsv

# Let's see what files are staged for commit
git status
# If we are happy with the files staged for commit,
# we can commit the changes to the repository.
git commit -m "Add scripts to the repository"
  1. Push the changes to the repository on Github. This will update the repository on Github with the changes you made locally.
# Pull in any changes from the repository on Github,
# this will ensure you have the latest changes from
# the repository on Github. This is a good practice
# and it will ensure you don't have any conflicts.
git pull

# Push the changes to the repository on Github,
# this will update the repository on Github with
# the changes you made locally. Please enter your
# Github for the username and your personal access
# token (PAT) when prompted for the password.
git push
Clone this wiki locally