Skip to content
GoFigr Docs

Git Repository Import

Overview

Section titled “Overview”

Git Repository Import connects your code repositories to your figure library. Import Jupyter notebooks directly from GitHub, GitLab, Bitbucket, or any Git-compatible host, and GoFigr extracts every figure from every commit—preserving your version history with full attribution.

Key Benefits for Users

Section titled “Key Benefits for Users”

Preserve Your Research History

Section titled “Preserve Your Research History”
  • Full Commit History: Import figures from all commits, not just the latest version
  • Version Tracking: Each notebook revision becomes a tracked figure revision in GoFigr
  • Git Metadata Preserved: Branch names, commit hashes, and timestamps are stored with each import
  • Author Attribution: Git commit authors are automatically mapped to GoFigr users

Seamless Integration with Your Workflow

Section titled “Seamless Integration with Your Workflow”
  • No Workflow Changes: Keep using Git as you always have—GoFigr pulls from your repositories
  • Multiple Git Hosts: Support for GitHub, GitLab, Bitbucket, and any standard Git server
  • Both HTTPS and SSH: Use public repos via HTTPS or private repos with SSH key authentication
  • Branch Selection: Choose exactly which branches to import

Automatic Figure Extraction

Section titled “Automatic Figure Extraction”
  • Jupyter Notebook Processing: All output cells with images are automatically extracted
  • Code Association: Each figure is linked to the code cell that generated it
  • Source Document Linking: Figures are connected back to their source notebook files
  • Intelligent Deduplication: Identical figures are detected and not duplicated

How It Works

Section titled “How It Works”

Step 1: Navigate to Import

Section titled “Step 1: Navigate to Import”
  1. Go to the Import page from the main navigation
  2. Select your target workspace
  3. Choose the “Git Repository” import option

Step 2: Enter Repository URL

Section titled “Step 2: Enter Repository URL”

Enter your Git repository URL. GoFigr supports multiple formats:

HTTPS URLs (public repositories):

  • https://github.com/username/repository.git
  • https://gitlab.com/username/repository.git
  • https://bitbucket.org/username/repository.git

SSH URLs (private repositories):

  • git@github.com:username/repository.git
  • git@gitlab.com:username/repository.git
  • git+ssh://git@github.com/username/repository.git

Step 3: Configure SSH Key (for Private Repos)

Section titled “Step 3: Configure SSH Key (for Private Repos)”

For SSH-based URLs to private repositories:

  1. The SSH Key selector appears automatically
  2. Choose an existing SSH key or add a new one
  3. SSH keys are stored encrypted and used securely for authentication
  4. Click “Manage SSH Keys” to add, view, or remove keys

Note: SSH keys are optional for HTTPS URLs to public repositories.

Step 4: Select Branches

Section titled “Step 4: Select Branches”

Once the repository is validated:

  1. GoFigr automatically fetches available branches
  2. Main/master branches are selected by default if present
  3. Use the multi-select dropdown to add or remove branches
  4. Each selected branch will be scanned for notebooks

Step 5: Start Import

Section titled “Step 5: Start Import”

Click “Import from Git” to begin:

  1. GoFigr clones the repository to a secure temporary location
  2. All commits in selected branches are scanned for .ipynb files
  3. Each notebook file at each commit is processed
  4. Figures are extracted from cell outputs
  5. Progress is displayed in real-time

Step 6: Monitor Progress

Section titled “Step 6: Monitor Progress”

The import progress modal shows:

  • Overall Progress: Percentage complete across all files
  • Current File: Which notebook is being processed
  • Branch Progress: Which branch/commit is being scanned
  • Log Messages: Detailed status updates
  • Cancel Option: Stop the import at any time if needed

What Gets Imported

Section titled “What Gets Imported”

From Each Notebook

Section titled “From Each Notebook”
  • All Figure Outputs: PNG, JPEG, SVG, and other image outputs from cells
  • Cell Code: The code that generated each figure is preserved
  • Notebook Metadata: Kernel info, notebook version, and custom metadata

From Git History

Section titled “From Git History”
  • Commit Timestamps: Each figure revision uses the original Git commit time
  • Author Information: Commit authors are mapped to GoFigr users by email
  • Branch Context: Which branch each version came from
  • Commit Hash: Links back to the exact commit for provenance

How Figures Are Organized

Section titled “How Figures Are Organized”
  1. One Analysis per Notebook Path: Notebooks with the same path share an analysis
  2. One Figure per Output: Each distinct figure in the notebook becomes a GoFigr figure
  3. Revisions by Commit: Different commits create different figure revisions
  4. Source Linking: Each figure links back to its source notebook asset

Author Attribution

Section titled “Author Attribution”

GoFigr intelligently maps Git authors to GoFigr users:

Automatic Matching

Section titled “Automatic Matching”
  • Git commit author emails are matched against GoFigr user emails
  • Matching requires the importing user to have a confirmed email address
  • Matched figures show the original author in GoFigr

When No Match Is Found

Section titled “When No Match Is Found”
  • The “on behalf of” field stores the Git author name and email
  • Full attribution is preserved even without a GoFigr account
  • Future users can claim their figures when they join

Importing User as Fallback

Section titled “Importing User as Fallback”
  • If author matching is disabled or fails, the importing user is credited
  • The original Git author info is still stored in metadata

Real-Time Progress Tracking

Section titled “Real-Time Progress Tracking”

Progress Indicators

Section titled “Progress Indicators”
  • File Count: “Processing file 5 of 23”
  • Branch Progress: “Scanning branch: feature/analysis”
  • Commit Info: “Processing commit a1b2c3d…”
  • Detailed Logs: Timestamped log messages for debugging

Error Handling

Section titled “Error Handling”
  • Graceful Failures: Individual file failures don’t stop the entire import
  • Error Messages: Clear descriptions of what went wrong
  • Partial Success: Successfully imported figures are kept even if some fail
  • Retry Option: Failed imports can be retried after fixing issues

Cancellation

Section titled “Cancellation”
  • Click “Cancel” at any time during import
  • Already-imported figures are preserved
  • The repository clone is cleaned up automatically

Import History

Section titled “Import History”

Recent imports are tracked and displayed:

  • Repository URL: Which repository was imported
  • Import Time: When the import occurred
  • Status: Success, partial, or failed
  • Figure Count: How many figures were extracted

Best Practices

Section titled “Best Practices”

Before Importing

Section titled “Before Importing”
  1. Clean Up Notebooks: Clear unnecessary output cells to reduce processing time
  2. Organize by Project: One repository = one logical project for cleaner organization
  3. Tag Important Commits: Consider which commits contain meaningful figure changes

SSH Key Management

Section titled “SSH Key Management”
  1. Use Deploy Keys: GitHub/GitLab deploy keys limit access to specific repositories
  2. Read-Only Access: GoFigr only needs read access to clone
  3. Rotate Periodically: Update SSH keys regularly for security
  4. One Key Per Repository: Easier to manage and audit

Branch Selection

Section titled “Branch Selection”
  1. Start with Main Branch: Begin with main/master for the primary history
  2. Add Feature Branches Selectively: Only import branches with meaningful figures
  3. Consider Tag-Based Workflows: Some teams may want to import only tagged releases

Security & Privacy

Section titled “Security & Privacy”

SSH Key Storage

Section titled “SSH Key Storage”
  • SSH keys are encrypted at rest
  • Keys are only decrypted during clone operations
  • Temporary key files are securely deleted after use
  • Thread-safe handling prevents key leakage

Repository Access

Section titled “Repository Access”
  • GoFigr clones to isolated temporary directories
  • Clone directories are deleted after processing
  • No repository data is stored except extracted figures
  • Network access is limited to the clone operation

Duplicate Import Prevention

Section titled “Duplicate Import Prevention”
  • GoFigr prevents simultaneous imports of the same repository
  • Avoids race conditions and duplicate figures
  • Clear error messages if import already in progress

Technical Details

Section titled “Technical Details”

Supported Notebook Versions

Section titled “Supported Notebook Versions”
  • Jupyter Notebook (.ipynb) format versions 4.x
  • JupyterLab notebooks
  • Google Colab exports

Processing Architecture

Section titled “Processing Architecture”
  • Parallel File Processing: Multiple notebooks processed simultaneously (configurable)
  • Sequential Commit Processing: Commits for each file processed in chronological order
  • Thread-Safe SSH: Isolated SSH key handling per operation
  • Automatic Cleanup: Temporary files removed even on errors

Git Operations

Section titled “Git Operations”
  • Full repository clone (not shallow) for complete history
  • Remote branch fetching when needed
  • Git protocol support: HTTPS, SSH, git://

Figure Extraction

Section titled “Figure Extraction”
  • All image MIME types from display_data outputs
  • Execute_result outputs with image data
  • Embedded images in markdown cells (future enhancement)

Troubleshooting

Section titled “Troubleshooting”

“Failed to clone repository”

Section titled ““Failed to clone repository””
  • Check the URL format is correct
  • Verify SSH key has access (for private repos)
  • Ensure the repository exists and is accessible

“SSH key required”

Section titled ““SSH key required””
  • Non-HTTPS URLs require an SSH key
  • Add a key via “Manage SSH Keys”
  • Verify the key has read access to the repository

“No notebooks found”

Section titled ““No notebooks found””
  • Ensure the repository contains .ipynb files
  • Check selected branches contain notebooks
  • Verify notebooks are committed (not just in working directory)

Import Taking Too Long

Section titled “Import Taking Too Long”
  • Large repositories with many commits may take time
  • Consider importing specific branches only
  • Check network connectivity to the Git host