Git LFS Cloudinary

A Python library that integrates Git LFS (Large File Storage) with Cloudinary, allowing you to store your binary media files in Cloudinary's cloud storage instead of traditional Git LFS servers.

Features

• 🚀 Seamless Integration: Works as a Git LFS custom transfer agent
• ☁️ Cloudinary Storage: Store binary files in Cloudinary (free tier available)
• 🔒 Secure: Credentials stored securely in your home directory
• 📦 Easy Setup: Simple command-line interface for configuration
• 🎯 Automatic: Works transparently with Git LFS commands
• 🆓 Free Tier: Use Cloudinary's free plan for small projects
• 📚 Library & CLI: Use as a command-line tool OR as a Python library

Usage Modes

1. Simple Library (Flash Facade)

Use it directly in your Python code with a simple, clean API:

from git_lfs_cloudinary import flash as fs

# Setup once
fs.setup("cloud-name", "api-key", "api-secret")

# Push files
result = fs.push("myfile.psd")
print(f"Uploaded to: {result['url']}")

# Pull files
fs.pull("myfile.psd")

# Check status
status = fs.status()
print(f"Configured: {status['configured']}")

See LIBRARY_USAGE.md for complete API documentation.

2. Command-Line Interface

Use via command-line for manual operations:

# Simple workflow
py -m git_lfs_cloudinary.cli push myfile.psd
py -m git_lfs_cloudinary.cli pull myfile.psd

3. Advanced: Git LFS Integration

Fully integrate with Git LFS for automatic file handling.

Why Use This?

Git LFS is great for managing large files in Git repositories, but it requires either:

• GitHub's LFS storage (limited free tier, paid beyond that)
• Setting up your own LFS server

With git-lfs-cloudinary, you can:

• Use Cloudinary's generous free tier (25GB storage, 25GB bandwidth/month)
• Leverage Cloudinary's global CDN for fast downloads
• Benefit from Cloudinary's image optimization features
• Avoid setting up your own LFS server

Installation

pip install git-lfs-cloudinary

Command Usage

Use the Python module directly (works immediately, no setup needed):

py -m git_lfs_cloudinary.cli push myfile.psd

Optional shortcut: If you want to use just flash instead, see SETUP_PATH.md for PATH configuration.

# After PATH setup (optional):
flash push myfile.psd

Prerequisites

1. Git LFS: Install from git-lfs.github.com
2. Cloudinary Account: Sign up for free at cloudinary.com

Quick Start

Simple Workflow (Recommended)

The easiest way to use git-lfs-cloudinary:

1. Setup once:

py -m git_lfs_cloudinary.cli setup

2. Push any file (uploads to Cloudinary + commits to git):

py -m git_lfs_cloudinary.cli push myfile.psd

3. Push to remote:

git push

That's it! The file is uploaded to Cloudinary, replaced with a pointer, and committed to git.

Pull files back when needed:

py -m git_lfs_cloudinary.cli pull myfile.psd

Advanced: Git LFS Integration

For automatic LFS integration:

1. Setup Cloudinary Credentials

git-lfs-cloudinary setup

You'll need:

• Cloud Name: Your Cloudinary cloud name
• API Key: Your API key from Cloudinary dashboard
• API Secret: Your API secret from Cloudinary dashboard

You can find these in your Cloudinary Console Dashboard.

2. Initialize in Your Git Repository

cd your-repo
git-lfs-cloudinary init

This will:

• Initialize Git LFS in your repository
• Configure Git LFS to use Cloudinary as the storage backend

3. Track Files with Git LFS

Track the file types you want to store in Cloudinary:

# Track Photoshop files
git lfs track "*.psd"

# Track video files
git lfs track "*.mp4"

# Track ZIP archives
git lfs track "*.zip"

# Track all files in a directory
git lfs track "assets/**"

4. Commit and Push

Now just use Git normally! Files matching your LFS patterns will automatically be uploaded to Cloudinary:

git add .
git commit -m "Add large media files"
git push

Commands

push - Simple file push

Push a file to Cloudinary, replace with pointer, and commit (recommended):

py -m git_lfs_cloudinary.cli push myfile.psd

This one command:

1. Uploads myfile.psd to Cloudinary
2. Replaces it with an LFS pointer
3. Commits the pointer to git

Then just: git push

Options:

• -m "message" - Custom commit message (default: "Add myfile.psd")
• --no-commit - Skip the git commit step

pull - Get file back

Replace an LFS pointer with the actual file:

py -m git_lfs_cloudinary.cli pull myfile.psd

This downloads the file from Cloudinary and replaces the pointer.

setup

Configure Cloudinary credentials:

py -m git_lfs_cloudinary.cli setup

Options:

• --cloud-name: Your Cloudinary cloud name
• --api-key: Your Cloudinary API key
• --api-secret: Your Cloudinary API secret
• --folder: Cloudinary folder for LFS files (default: git-lfs)

status

Check configuration status:

py -m git_lfs_cloudinary.cli status

Shows:

• Cloudinary configuration status
• Git LFS installation status
• Configuration details

init (Advanced)

Initialize Git LFS with Cloudinary in the current repository:

git-lfs-cloudinary init

Must be run inside a Git repository. Only needed for automatic Git LFS integration.

upload (Advanced)

Upload a file without replacing it locally:

git-lfs-cloudinary upload path/to/file.psd

download (Advanced)

Download a file by OID:

git-lfs-cloudinary download <oid> output/path.psd --size <bytes>

How It Works

1. LFS Pointer Files: When you commit a tracked file, Git LFS creates a small "pointer" file in your repository
2. Custom Transfer Agent: This library acts as a custom transfer agent for Git LFS
3. Cloudinary Upload: Instead of uploading to a Git LFS server, files are uploaded to Cloudinary
4. OID-based Storage: Files are stored in Cloudinary using their SHA256 hash (OID) as the identifier
5. Transparent Downloads: When you clone or pull, files are automatically downloaded from Cloudinary

Configuration

Configuration is stored in ~/.git-lfs-cloudinary/:

• config.json: Non-sensitive configuration
• .env: Cloudinary credentials (keep this secure!)

Example Workflows

Library Usage (Simple & Pythonic)

from git_lfs_cloudinary import flash as fs

# Setup once
fs.setup("cloud-name", "api-key", "api-secret")

# Upload files
result = fs.push("design/logo.psd")
print(f"Uploaded to: {result['url']}")

fs.push("videos/intro.mp4")
fs.push("assets/bundle.zip")

# Check if file exists in Cloudinary
if fs.exists("design/logo.psd"):
    print("File is in Cloudinary!")

# Get file info
info = fs.info("design/logo.psd")
print(f"OID: {info['oid']}, Size: {info['size']}")

# Later, pull files back
fs.pull("design/logo.psd")

# Convenience aliases
fs.up("file.psd")    # Same as fs.upload()
fs.down("abc123", "file.psd")  # Same as fs.download()

See LIBRARY_USAGE.md and examples/facade_example.py for more.

CLI Workflow (Recommended)

# 1. Setup once
py -m git_lfs_cloudinary.cli setup

# 2. Push large files (each one uploads + commits automatically)
py -m git_lfs_cloudinary.cli push design/logo.psd
py -m git_lfs_cloudinary.cli push videos/intro.mp4
py -m git_lfs_cloudinary.cli push assets/bundle.zip

# 3. Push to remote
git push

# Files are now stored in Cloudinary with pointers in Git!

# 4. Later, to get the actual files back:
py -m git_lfs_cloudinary.cli pull design/logo.psd

Advanced: Git LFS Automatic Workflow

# 1. Setup (one time)
py -m git_lfs_cloudinary.cli setup

# 2. In your repository
cd my-project
py -m git_lfs_cloudinary.cli init

# 3. Track large files
git lfs track "*.psd"
git lfs track "*.ai"
git lfs track "design/**"

# 4. Add and commit
git add .gitattributes
git commit -m "Configure LFS tracking"

# 5. Add your large files
git add design/logo.psd
git commit -m "Add logo design"
git push

# File is automatically stored in Cloudinary!

Cloudinary Free Tier

Cloudinary's free tier includes:

• 25 credits/month (1 credit = 1GB storage or 1GB bandwidth)
• 25GB total storage
• 25GB monthly bandwidth
• Image and video transformations
• Global CDN

Perfect for small to medium projects!

Troubleshooting

"Cloudinary not configured"

Run git-lfs-cloudinary setup to configure your credentials.

"Git LFS not installed"

Install Git LFS from git-lfs.github.com.

"Not in a Git repository"

Make sure you're inside a Git repository when running git-lfs-cloudinary init.

Files not uploading

1. Check that files are tracked: git lfs ls-files
2. Verify LFS configuration: git lfs env
3. Check Cloudinary status: git-lfs-cloudinary status

Development

Install for Development

git clone https://github.com/yourusername/git-lfs-cloudinary
cd git-lfs-cloudinary
pip install -e .

Run Tests

pytest

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Credits

• Built with Cloudinary Python SDK
• Integrates with Git LFS

Links

• Cloudinary
• Git LFS
• Git LFS Custom Transfers