CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-nbdev

Create delightful software with Jupyter Notebooks

Pending
Overview
Eval results
Files

git-integration.mddocs/

Git Integration

Handle git merge conflicts and notebook-specific version control concerns. nbdev provides specialized tools for managing notebooks in git repositories, resolving merge conflicts, and maintaining clean version control history.

Capabilities

Merge Conflict Resolution

Resolve git merge conflicts in notebook files automatically.

def nbdev_merge():
    """
    Merge notebooks with conflict resolution.
    
    Automatically resolves common notebook merge conflicts by:
    - Combining cell outputs intelligently
    - Resolving execution count conflicts
    - Merging metadata changes
    - Preserving both sets of changes where possible
    """

def nbdev_fix():
    """
    Fix notebook merge conflicts.
    
    Repairs notebook files that have git merge conflict markers,
    attempting to create valid notebook JSON while preserving
    both versions of conflicting content.
    """

Usage Examples:

from nbdev.merge import nbdev_merge, nbdev_fix

# After git merge with conflicts
nbdev_merge()  # Attempt automatic resolution

# If manual intervention needed
nbdev_fix()    # Fix remaining conflicts

Patch Management

Handle code patches and modifications in version control.

def unpatch():
    """
    Remove patches from code.
    
    Removes temporary patches or modifications that were applied
    for testing or development but shouldn't be permanent.
    """

Configuration Regex

Utilities for handling configuration and merge patterns.

def conf_re():
    """
    Configuration regex patterns.
    
    Returns:
        Regex patterns for identifying configuration sections
        and merge conflict markers in notebook files.
    """

Git Workflow Integration

Standard Git Operations

nbdev enhances standard git operations for notebooks:

# Before committing
nbdev_clean          # Clean notebooks
git add .
git commit -m "Update notebooks"

# After pulling changes
git pull
nbdev_merge         # Resolve any notebook conflicts
nbdev_update        # Sync notebooks with code changes

Merge Conflict Resolution Process

  1. Automatic Resolution: nbdev_merge() attempts to resolve conflicts
  2. Manual Review: Check remaining conflicts in notebook files
  3. Fix Remaining: Use nbdev_fix() for stubborn conflicts
  4. Validation: Ensure notebooks are valid JSON
  5. Testing: Run nbdev_test() to verify functionality
from nbdev.merge import nbdev_merge, nbdev_fix
from nbdev.test import nbdev_test
from nbdev.clean import nbdev_clean

def resolve_notebook_conflicts():
    """Complete workflow for resolving notebook merge conflicts."""
    
    print("Attempting automatic merge resolution...")
    nbdev_merge()
    
    print("Fixing remaining conflicts...")
    nbdev_fix()
    
    print("Cleaning resolved notebooks...")
    nbdev_clean()
    
    print("Testing resolved notebooks...")
    success = nbdev_test()
    
    if success:
        print("✓ Merge conflicts resolved successfully")
    else:
        print("⚠ Manual review needed - some tests failed")
    
    return success

# Use after git merge conflicts
resolve_notebook_conflicts()

Conflict Types and Resolution

Common Notebook Conflicts

Execution Count Conflicts:

<<<<<<< HEAD
"execution_count": 15,
=======
"execution_count": 23,
>>>>>>> branch

Resolution: Remove execution counts (they're not meaningful)

Cell Output Conflicts:

<<<<<<< HEAD
"outputs": [{"text": "Result A"}],
=======
"outputs": [{"text": "Result B"}],
>>>>>>> branch

Resolution: Keep both outputs or choose based on context

Metadata Conflicts:

<<<<<<< HEAD
"metadata": {"tags": ["important"]},
=======
"metadata": {"tags": ["test"]},
>>>>>>> branch

Resolution: Merge metadata or choose appropriate version

Automated Resolution Strategies

nbdev uses intelligent strategies for different conflict types:

  • Execution counts: Always removed (meaningless for version control)
  • Cell IDs: Regenerated to avoid conflicts
  • Outputs: Cleared or merged based on configuration
  • Source code: Manual resolution required (most important)
  • Metadata: Merged where possible, otherwise manual resolution

Git Hooks Integration

Pre-commit Hooks

Automatically clean notebooks before commits:

# Installed via nbdev_install_hooks()
# Pre-commit hook runs:
nbdev_clean --clear_all

Post-merge Hooks

Automatically handle notebook updates after merges:

# Post-merge hook runs:
nbdev_merge
nbdev_update

Advanced Git Operations

Branch Management

from nbdev.merge import nbdev_merge
from nbdev.export import nb_export

def safe_branch_switch(branch_name):
    """Safely switch branches with notebook handling."""
    
    # Clean current state
    nb_export()  # Export current work
    
    # Switch branches
    import subprocess
    subprocess.run(['git', 'checkout', branch_name])
    
    # Handle any conflicts
    nbdev_merge()
    
    print(f"Switched to {branch_name} with notebooks updated")

safe_branch_switch('feature-branch')

Repository Maintenance

from nbdev.merge import nbdev_fix
from nbdev.clean import nbdev_clean

def maintain_notebook_repo():
    """Maintain notebook repository health."""
    
    # Fix any lingering issues
    nbdev_fix()
    
    # Clean all notebooks
    nbdev_clean(clear_all=True)
    
    # Verify repository state
    import subprocess
    result = subprocess.run(['git', 'status', '--porcelain'], 
                          capture_output=True, text=True)
    
    if result.stdout.strip():
        print("Repository has changes after maintenance:")
        print(result.stdout)
    else:
        print("✓ Repository clean after maintenance")

maintain_notebook_repo()

Integration with GitHub

Pull Request Workflows

# Before creating PR
from nbdev.clean import nbdev_clean
from nbdev.export import nb_export
from nbdev.test import nbdev_test

def prepare_pr():
    """Prepare notebooks for pull request."""
    
    # Clean notebooks
    nbdev_clean()
    
    # Export to ensure code is up to date
    nb_export()
    
    # Run tests
    if nbdev_test():
        print("✓ Ready for pull request")
        return True
    else:
        print("✗ Tests failed - fix before PR")
        return False

prepare_pr()

Collaborative Development

from nbdev.merge import nbdev_merge
from nbdev.sync import nbdev_update

def sync_with_team():
    """Sync notebooks with team changes."""
    
    # Pull latest changes
    import subprocess
    subprocess.run(['git', 'pull'])
    
    # Resolve any notebook conflicts
    nbdev_merge()
    
    # Update notebooks with code changes
    nbdev_update()
    
    print("✓ Synced with team changes")

sync_with_team()

Best Practices

Version Control Strategy

  1. Always clean before committing: Use nbdev_clean()
  2. Resolve conflicts immediately: Don't let them accumulate
  3. Test after merges: Run nbdev_test() after conflict resolution
  4. Use meaningful commit messages: Describe notebook changes clearly

Team Collaboration

# Recommended team workflow
def team_workflow():
    """Recommended workflow for team collaboration."""
    
    # Before starting work
    subprocess.run(['git', 'pull'])
    nbdev_merge()  # Handle any conflicts
    nbdev_update()  # Update notebooks
    
    # After making changes
    nbdev_clean()   # Clean notebooks
    nb_export()     # Export code
    nbdev_test()    # Test changes
    
    # Before committing
    subprocess.run(['git', 'add', '.'])
    subprocess.run(['git', 'commit', '-m', 'Update notebooks'])
    subprocess.run(['git', 'push'])

Repository Setup

# Initial repository setup
nbdev_install_hooks  # Install git hooks
git config merge.ours.driver true  # For binary files

Complete Git Integration Example:

from nbdev.merge import nbdev_merge, nbdev_fix
from nbdev.clean import nbdev_clean
from nbdev.test import nbdev_test
import subprocess

def complete_git_workflow():
    """Complete git workflow with notebook handling."""
    
    print("1. Pulling latest changes...")
    subprocess.run(['git', 'pull'])
    
    print("2. Resolving notebook conflicts...")
    nbdev_merge()
    nbdev_fix()
    
    print("3. Cleaning notebooks...")  
    nbdev_clean()
    
    print("4. Running tests...")
    if not nbdev_test():
        print("Tests failed - manual review needed")
        return False
    
    print("5. Git workflow complete!")
    return True

complete_git_workflow()

Install with Tessl CLI

npx tessl i tessl/pypi-nbdev

docs

cleaning.md

configuration.md

development-tools.md

documentation.md

export.md

git-integration.md

index.md

release-management.md

synchronization.md

testing.md

tile.json