Skip to content

Getting Started

This guide walks you through setting up Git DRS and performing common workflows.

Navigation: Installation → Getting Started → Commands Reference → Troubleshooting

Repository Initialization

Every Git repository using Git DRS requires configuration, whether you're creating a new repo or cloning an existing one.

Cloning Existing Repository (Gen3)

  1. Clone the Repository
git clone <repo-clone-url>.git
cd <name-of-repo>
  1. Configure SSH (if using SSH URLs)

If using SSH URLs like git@github.com:user/repo.git, add to ~/.ssh/config:

Host github.com
    TCPKeepAlive yes
    ServerAliveInterval 30

  1. Get Credentials

  2. Log in to your data commons (e.g., https://calypr-public.ohsu.edu/)

  3. Profile → Create API Key → Download JSON

  4. Note: Credentials expire after 30 days

  5. Initialize Repository

git drs init
  1. Verify Configuration
git drs remote list

Output: 

* production  gen3    https://calypr-public.ohsu.edu/

The * indicates this is the default remote.

New Repository Setup (Gen3)

  1. Create and Clone Repository
git clone <repo-clone-url>.git
cd <name-of-repo>

  1. Configure SSH (if needed - same as above)

  2. Get Credentials (same as above)

  3. Get Project Details

Contact your data coordinator for: - DRS server URL - Project ID - Bucket name

  1. Initialize Git DRS
git drs init
  1. Add Remote Configuration
git drs remote add gen3 production \
    --cred /path/to/credentials.json \
    --url https://calypr-public.ohsu.edu \
    --project my-project \
    --bucket my-bucket

Note: Since this is your first remote, it automatically becomes the default. No need to run git drs remote set.

  1. Verify Configuration
git drs remote list

Output: 

* production  gen3    https://calypr-public.ohsu.edu

Managing Additional Remotes

You can add more remotes later for multi-environment workflows (development, staging, production):

# Add staging remote
git drs remote add gen3 staging \
    --cred /path/to/staging-credentials.json \
    --url https://staging.calypr.ohsu.edu \
    --project staging-project \
    --bucket staging-bucket

# View all remotes
git drs remote list

# Switch default remote
git drs remote set staging

# Or use specific remote for one command
git drs push production
git drs fetch staging

File Tracking

Git DRS uses Git LFS to track files. You must explicitly track file patterns before adding them.

View Current Tracking

git lfs track

Track Files

Single File

git lfs track path/to/specific-file.txt
git add .gitattributes

File Pattern

git lfs track "*.bam"
git add .gitattributes

Directory

git lfs track "data/**"
git add .gitattributes

Untrack Files

# View tracked patterns
git lfs track

# Remove pattern
git lfs untrack "*.bam"

# Stage changes
git add .gitattributes

Basic Workflows

Adding and Pushing Files

# Track file type (if not already tracked)
git lfs track "*.bam"
git add .gitattributes

# Add your file
git add myfile.bam

# Verify LFS is tracking it
git lfs ls-files

# Commit and push
git commit -m "Add new data file"
git push

Note: Git DRS automatically creates DRS records during commit and uploads files to the default remote during push.

Downloading Files

Single File

git lfs pull -I path/to/file.bam

Pattern

git lfs pull -I "*.bam"

All Files

git lfs pull

Directory

git lfs pull -I "data/**"

Checking File Status

# List all LFS-tracked files
git lfs ls-files

# Check specific pattern
git lfs ls-files -I "*.bam"

# View localization status
# (-) = not localized, (*) = localized
git lfs ls-files

Working with S3 Files

You can add references to existing S3 files without copying them:

# Track the file pattern first
git lfs track "myfile.txt"
git add .gitattributes

# Add S3 reference
git drs add-url s3://bucket/path/to/file \
  --sha256 <file-hash> \
  --aws-access-key <key> \
  --aws-secret-key <secret>

# Commit and push
git commit -m "Add S3 file reference"
git push

See S3 Integration Guide for detailed examples.

Configuration Management

View Configuration

git drs remote list

Update Configuration

# Refresh credentials - re-add remote with new credentials
git drs remote add gen3 production \
    --cred /path/to/new-credentials.json \
    --url https://calypr-public.ohsu.edu \
    --project my-project \
    --bucket my-bucket

# Switch default remote
git drs remote set staging

View Logs

  • Logs location: .drs/ directory

Command Summary

Action Commands
Initialize git drs init
Add remote git drs remote add gen3 <name> --cred...
View remotes git drs remote list
Set default git drs remote set <name>
Track files git lfs track "pattern"
Check tracked git lfs ls-files
Add files git add file.ext
Commit git commit -m "message"
Push git push
Download git lfs pull -I "pattern"

Session Workflow

For each work session:

  1. Refresh credentials (if expired - credentials expire after 30 days)
git drs remote add gen3 production \
    --cred /path/to/new-credentials.json \
    --url https://calypr-public.ohsu.edu \
    --project my-project \
    --bucket my-bucket

  1. Work with files (track, add, commit, push)

  2. Download files as needed

git lfs pull -I "required-files*"

Next Steps