git-lfs-cloudinary 0.2.1
Git LFS integration with Cloudinary for binary media storage
License: MIT
Requires Python: >=3.8
Keywords: git, lfs, cloudinary, media, storage

# 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:

```python
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](LIBRARY_USAGE.md) for complete API documentation.

### 2. Command-Line Interface

Use via command-line for manual operations:

```bash
# 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

```bash
pip install git-lfs-cloudinary
```

### Command Usage

Use the Python module directly (works immediately, no setup needed):

```bash
py -m git_lfs_cloudinary.cli push myfile.psd
```

**Optional shortcut:** If you want to use just `flash` instead, see [SETUP_PATH.md](SETUP_PATH.md) for PATH configuration.

```bash
# After PATH setup (optional):
flash push myfile.psd
```

## Prerequisites

1. **Git LFS**: Install from [git-lfs.github.com](https://git-lfs.github.com/)
2. **Cloudinary Account**: Sign up for free at [cloudinary.com](https://cloudinary.com/)

## Quick Start

### Simple Workflow (Recommended)

The easiest way to use git-lfs-cloudinary:

**1. Setup once:**
```bash
py -m git_lfs_cloudinary.cli setup
```

**2. Push any file (uploads to Cloudinary + commits to git):**
```bash
py -m git_lfs_cloudinary.cli push myfile.psd
```

**3. Push to remote:**
```bash
git push
```

That's it! The file is uploaded to Cloudinary, replaced with a pointer, and committed to git.

**Pull files back when needed:**
```bash
py -m git_lfs_cloudinary.cli pull myfile.psd
```

### Advanced: Git LFS Integration

For automatic LFS integration:

**1. Setup Cloudinary Credentials**

```bash
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](https://console.cloudinary.com/).

**2. Initialize in Your Git Repository**

```bash
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:

```bash
# 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:

```bash
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):

```bash
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:

```bash
py -m git_lfs_cloudinary.cli pull myfile.psd
```

This downloads the file from Cloudinary and replaces the pointer.

### `setup`

Configure Cloudinary credentials:

```bash
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:

```bash
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:

```bash
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:

```bash
git-lfs-cloudinary upload path/to/file.psd
```

### `download` (Advanced)

Download a file by OID:

```bash
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)

```python
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](LIBRARY_USAGE.md) and [examples/facade_example.py](examples/facade_example.py) for more.

### CLI Workflow (Recommended)

```bash
# 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

```bash
# 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](https://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

```bash
git clone https://github.com/yourusername/git-lfs-cloudinary
cd git-lfs-cloudinary
pip install -e .
```

### Run Tests

```bash
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](https://github.com/cloudinary/pycloudinary)
- Integrates with [Git LFS](https://git-lfs.github.com/)

## Links

- [Cloudinary](https://cloudinary.com/)
- [Git LFS](https://git-lfs.github.com/)
- [Git LFS Custom Transfers](https://github.com/git-lfs/git-lfs/blob/main/docs/custom-transfers.md)