hfsutils/.github/copilot-instructions.md

GitHub Copilot Instructions for hfsutils

Project Overview

hfsutils is a modern collection of tools for manipulating Hierarchical File System (HFS and HFS+) volumes. This is a modernized version of the original hfsutils by Robert Leslie, with additional HFS+ support and Unix standard filesystem utilities.

Key Components

Core Binaries

• hfsutil - Main unified binary containing all HFS utilities
• hfsck/hfsck - HFS/HFS+ filesystem checker

Filesystem Utilities (Unix Standard)

• mkfs.hfs - Create HFS filesystems
• mkfs.hfs+ - Create HFS+ filesystems
• mkfs.hfsplus - Alias for mkfs.hfs+
• fsck.hfs - Check/repair HFS filesystems
• fsck.hfs+ - Check/repair HFS+ filesystems
• fsck.hfsplus - Alias for fsck.hfs+

Traditional HFS Utilities (symlinks to hfsutil)

• hattrib, hcd, hcopy, hdel, hdir, hformat, hls, hmkdir, hmount, hpwd, hrename, hrmdir, humount, hvol

Build System

Build Commands

./build.sh          # Respects CC, CFLAGS, PREFIX variables
make                # Build all components
make symlinks       # Create filesystem utility symlinks
make clean          # Clean all build artifacts and symlinks
make install        # Install to PREFIX (default: /usr/local)
make install-symlinks # Install with traditional command symlinks

Key Directories

• src/ - Source code for hfsutil and common utilities
• hfsck/ - HFS/HFS+ filesystem checker
• libhfs/ - Core HFS library
• librsrc/ - Resource fork library
• doc/man/ - Manual pages (sections 1 and 8)
• test/ - Test suite

Code Style Guidelines

C Code

• Use consistent indentation (2 spaces)
• Follow existing naming conventions
• Include proper error handling
• Add comments for complex logic
• Use const where appropriate

Build System

• Support standard variables: CC, CXX, CFLAGS, CXXFLAGS, LDFLAGS, PREFIX
• Use proper dependency tracking
• Include clean targets
• Support DESTDIR for staged installations

Documentation

• Update manual pages for new features
• Include examples in man pages
• Keep README.md current
• Document build requirements

HFS+ Implementation Notes

Key Features

• Full HFS+ volume creation with proper structures
• Volume header and allocation bitmap setup
• Catalog and extents B-tree initialization
• Unicode filename support
• Large volume support (up to 8 exabytes)

Filesystem Detection

• Automatic HFS vs HFS+ detection
• Proper signature validation
• Fallback mechanisms for edge cases

Testing

Test Structure

• test/run_tests.sh - Main test runner
• test/test_*.sh - Individual test suites
• Comprehensive HFS+ formatting and validation tests
• Build system validation

Manual Testing

# Test filesystem utilities
./mkfs.hfs+ --version
./fsck.hfs+ --version

# Test HFS+ creation
dd if=/dev/zero of=test.img bs=1M count=10
./mkfs.hfs+ -l "Test Volume" test.img
./fsck.hfs+ test.img

Common Patterns

Version Information

All utilities support --version and --license flags with consistent output format.

Error Handling

Use proper exit codes and descriptive error messages. Follow Unix conventions.

Symlink Management

Symlinks are generated by build system, not tracked in git. Use make symlinks to create them.

Maintenance Notes

Adding New Features

1. Update source code with proper error handling
2. Add/update manual pages
3. Update test suite
4. Update build system if needed
5. Test installation process

Release Process

1. Update version in src/common/version.c
2. Update CHANGELOG.md
3. Run full test suite
4. Test installation process
5. Create git tag

Dependencies

• Standard C compiler (gcc/clang)
• make
• perl (for some build scripts)
• Standard Unix utilities

Compatibility

• Linux (primary target)
• BSD variants
• macOS
• Other Unix-like systems

Focus on maintaining compatibility while adding modern features and following Unix standards.