Grizzly

A modern cross-platform application for viewing and extracting ZIP archives, built with SwiftUI. Available for macOS and iOS/iPadOS.

Features

• Hierarchical File Browser: Navigate through zip contents with a Finder-like view
• File & Folder Selection: Select single or multiple items for extraction
• Quick Look Preview: Press spacebar to preview files without extracting (text, images, PDFs, etc.)
• Search & Filter: Quickly find files and folders within the archive
• Flexible Extraction: Extract individual files, folders, or the entire archive
• Drag & Drop Support: Simply drag a zip file into the app to open it
• File Picker: Use the traditional file picker dialog to open zip files
• User-Controlled Extraction: Choose the destination folder for each extraction
• Progress Tracking: Visual feedback during extraction operations

Requirements

macOS

• macOS 14.0 (Sonoma) or later
• Xcode 15.0 or later (for building from source)
• Swift 5.9 or later

iOS/iPadOS

• iOS/iPadOS 17.0 or later
• Xcode 15.0 or later (for building from source)
• Swift 5.9 or later

Installation

Download Pre-built App (Recommended)

1. Go to the Releases page
2. Download the latest Grizzly-X.X.X.dmg
3. Open the DMG file
4. Drag Grizzly.app to the Applications folder
5. Right-click the app and select "Open" the first time to bypass Gatekeeper

Build from Source

Building from Source

Quick Build (Swift Package Manager)

git clone https://github.com/YOUR_USERNAME/Grizzly.git
cd Grizzly/ZipViewer
swift build
swift run

Build macOS App Bundle

./build-app.sh

This creates a full .app bundle at .build/release/Grizzly.app with:

• Custom app icon
• File associations for .zip files
• Proper bundle structure for distribution

To install:

open .build/release/Grizzly.app  # Run the app
# or
cp -r .build/release/Grizzly.app /Applications/  # Install to Applications

Build with Xcode

open Package.swift
# Then press Cmd+R to run
# For iOS: Select an iOS destination in Xcode before building

Building for iOS/iPadOS

See IOS_BUILD_INSTRUCTIONS.md for detailed instructions on building and deploying to iOS devices and simulators.

Key differences on iOS/iPadOS:

• Files extract to the app's Documents folder
• Use document picker instead of drag & drop
• Optimized touch interface
• Share extracted files via iOS share sheet

Usage

Opening a Zip File

1. Drag & Drop: Drag a .zip file onto the application window
2. File Menu: Use Cmd+O or File → Open to select a zip file
3. Double-click: Associate .zip files with Grizzly and open them directly

Navigating Contents

• Double-click folders to navigate into them
• Double-click files to extract and open them with default application
• Back button or breadcrumb navigation to go up directories
• Single-click to select a file or folder
• Cmd+Click to toggle selection (multi-select)
• Shift+Click to select a range of items
• Arrow keys (↑/↓) to navigate between items
• Return to open selected file or enter folder

Previewing & Opening Files

• Double-click a file to extract and open it with the default application
• Press Spacebar to Quick Look preview without extracting
• Preview supports: images, PDFs, text files, code files, and more

Extracting Files

1. Select the files/folders you want to extract
2. Click the "Extract" button in the toolbar or right-click and select "Extract..."
3. Choose the destination folder
4. Click "Extract" to confirm

Searching

Use the search bar at the top of the sidebar to filter files and folders by name.

Keyboard Shortcuts

Navigation

• ↑/↓ - Navigate between items
• Shift+↑/↓ - Extend selection (range select)
• Cmd+↑ - Navigate up to parent folder
• Cmd+↓ - Navigate into selected folder
• Return - Open file or enter folder
• Delete/Backspace - Clear selection or go up

Selection

• Cmd+A - Select all in current view
• Escape - Clear selection
• Cmd+C - Copy selected file paths

File Operations

• Cmd+O - Open zip file / Open selected files
• Spacebar - Quick Look preview
• Cmd+E - Extract selected items
• Cmd+Shift+E - Extract all
• Cmd+F - Focus search field

Architecture

The app is built using modern SwiftUI patterns with async/await:

• Models: ZipEntry for representing archive contents, ZipArchiveManager for memory-efficient archive operations
• ViewModels: AppState (@MainActor) for managing application state with async operations
• Views: SwiftUI components with comprehensive keyboard navigation and accessibility support

For detailed technical information, see PROJECT_SUMMARY.md

Dependencies

• ZIPFoundation 0.9.0+: Memory-efficient zip archive handling with streaming support

Contributing

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

Releasing

To create a new release:

1. Tag your commit with a version number:

   git tag v1.0.0
   git push origin v1.0.0

2. GitHub Actions will automatically:

   • Build the app
   • Create a DMG installer
   • Publish a new release with the DMG attached

3. The release will appear on the Releases page

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have suggestions, please open an issue on GitHub.