290 lines
6.7 KiB
Markdown
290 lines
6.7 KiB
Markdown
# s3-genindex - Detailed Documentation
|
|
|
|
## Overview
|
|
|
|
s3-genindex is a Go rewrite of the original Python genindex.py script. It generates HTML directory listings with file type icons, responsive design, and dark mode support.
|
|
|
|
## Features
|
|
|
|
- **File Type Detection**: Recognizes 100+ file extensions with appropriate icons
|
|
- **Responsive Design**: Works on desktop and mobile devices
|
|
- **Dark Mode**: Automatic dark mode support based on system preferences
|
|
- **Recursive Processing**: Generate indexes for entire directory trees
|
|
- **File Filtering**: Include/exclude files by pattern or regex
|
|
- **Symlink Support**: Special handling for symbolic links
|
|
- **Custom Output**: Configurable output filename
|
|
- **Breadcrumb Navigation**: Parent directory navigation
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone https://git.ipng.ch/ipng/s3-genindex.git
|
|
cd s3-genindex
|
|
make build
|
|
```
|
|
|
|
### Using Go Install
|
|
|
|
```bash
|
|
go install git.ipng.ch/ipng/s3-genindex/cmd/s3-genindex@latest
|
|
```
|
|
|
|
## Command Line Options
|
|
|
|
```
|
|
Usage: s3-genindex [OPTIONS] [directory]
|
|
|
|
-d append output file to directory href
|
|
-f string
|
|
only include files matching glob (default "*")
|
|
-i include dot hidden files
|
|
-o string
|
|
custom output file (default "index.html")
|
|
-r recursively process nested dirs
|
|
-v verbosely list every processed file
|
|
-x string
|
|
exclude files matching regular expression
|
|
```
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Generate index.html in current directory
|
|
s3-genindex
|
|
|
|
# Generate index for specific directory
|
|
s3-genindex /path/to/directory
|
|
|
|
# Generate with custom output filename
|
|
s3-genindex -o listing.html
|
|
```
|
|
|
|
### Recursive Processing
|
|
|
|
```bash
|
|
# Process directory tree recursively
|
|
s3-genindex -r
|
|
|
|
# Process recursively with verbose output
|
|
s3-genindex -rv /var/www
|
|
```
|
|
|
|
### File Filtering
|
|
|
|
```bash
|
|
# Include only Python files
|
|
s3-genindex -f "*.py"
|
|
|
|
# Exclude build artifacts and dependencies
|
|
s3-genindex -x "(build|dist|node_modules|__pycache__|\\.tmp)"
|
|
|
|
# Include hidden files
|
|
s3-genindex -i
|
|
```
|
|
|
|
### Advanced Usage
|
|
|
|
```bash
|
|
# Recursive with custom output and exclusions
|
|
s3-genindex -r -o index.html -x "(\.git|\.svn|node_modules)" /var/www
|
|
|
|
# Verbose processing with directory appending
|
|
s3-genindex -r -v -d /home/user/public
|
|
```
|
|
|
|
## File Type Support
|
|
|
|
The tool recognizes and provides appropriate icons for:
|
|
|
|
### Programming Languages
|
|
- Go (`.go`)
|
|
- Python (`.py`, `.pyc`, `.pyo`)
|
|
- JavaScript/TypeScript (`.js`, `.ts`, `.json`)
|
|
- HTML/CSS (`.html`, `.htm`, `.css`, `.scss`)
|
|
- Shell scripts (`.sh`, `.bash`, `.bat`, `.ps1`)
|
|
- SQL (`.sql`)
|
|
|
|
### Documents
|
|
- PDF (`.pdf`)
|
|
- Text/Markdown (`.txt`, `.md`, `.markdown`)
|
|
- Office documents (`.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`)
|
|
- CSV (`.csv`)
|
|
|
|
### Media Files
|
|
- Images (`.jpg`, `.png`, `.gif`, `.svg`, `.webp`)
|
|
- Videos (`.mp4`, `.mov`, `.avi`, `.webm`)
|
|
- Audio (`.mp3`, `.wav`, `.flac`, `.ogg`)
|
|
|
|
### Archives
|
|
- Zip files (`.zip`, `.tar`, `.gz`, `.7z`, `.rar`)
|
|
- Package files (`.deb`, `.rpm`, `.dmg`, `.pkg`)
|
|
|
|
### System Files
|
|
- Certificates (`.crt`, `.pem`, `.key`)
|
|
- Configuration files
|
|
- License files (LICENSE, README)
|
|
|
|
## HTML Output Features
|
|
|
|
### Responsive Design
|
|
- Mobile-friendly layout
|
|
- Collapsible columns on small screens
|
|
- Touch-friendly navigation
|
|
|
|
### Dark Mode
|
|
- Automatic detection of system preference
|
|
- Clean dark color scheme
|
|
- Proper contrast ratios
|
|
|
|
### File Information
|
|
- File sizes in human-readable format
|
|
- Last modified timestamps
|
|
- File type icons
|
|
- Sorting (directories first, then alphabetical)
|
|
|
|
### Navigation
|
|
- Parent directory links
|
|
- Breadcrumb-style navigation
|
|
- Clickable file/directory entries
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
s3-genindex/
|
|
├── cmd/s3-genindex/ # Main application
|
|
│ ├── main.go # CLI entry point
|
|
│ └── main_test.go # CLI tests
|
|
├── internal/indexgen/ # Core library
|
|
│ ├── indexgen.go # Main functionality
|
|
│ ├── indexgen_test.go # Unit tests
|
|
│ └── integration_test.go # Integration tests
|
|
├── docs/ # Documentation
|
|
├── Makefile # Build automation
|
|
├── README.md # Quick start guide
|
|
└── go.mod # Go module definition
|
|
```
|
|
|
|
## Development
|
|
|
|
### Building
|
|
|
|
```bash
|
|
make build # Build binary
|
|
make test # Run tests
|
|
make test-coverage # Run tests with coverage
|
|
make check # Run all checks (fmt, vet, lint, test)
|
|
```
|
|
|
|
### Testing
|
|
|
|
The project includes comprehensive tests:
|
|
|
|
- **Unit tests**: Test individual functions and utilities
|
|
- **Integration tests**: Test complete directory processing workflows
|
|
- **Template tests**: Verify HTML template generation
|
|
- **CLI tests**: Test command-line argument parsing
|
|
|
|
Run tests with:
|
|
|
|
```bash
|
|
make test # Basic test run
|
|
make test-coverage # With coverage report
|
|
go test -v ./... # Verbose output
|
|
go test -short ./... # Skip integration tests
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
make fmt # Format code
|
|
make vet # Vet for issues
|
|
make lint # Run golangci-lint (if installed)
|
|
make check # Run all quality checks
|
|
```
|
|
|
|
## Configuration
|
|
|
|
No configuration files are needed. All options are provided via command-line arguments.
|
|
|
|
### Environment Variables
|
|
|
|
The tool respects standard Go environment variables:
|
|
- `GOOS` and `GOARCH` for cross-compilation
|
|
- `GOPATH` and `GOBIN` for installation paths
|
|
|
|
## Comparison with Original
|
|
|
|
This Go version provides the same functionality as the original Python script with these improvements:
|
|
|
|
### Performance
|
|
- Faster execution, especially for large directory trees
|
|
- Lower memory usage
|
|
- Single binary deployment
|
|
|
|
### Maintenance
|
|
- Comprehensive test suite
|
|
- Type safety
|
|
- Better error handling
|
|
- Structured codebase
|
|
|
|
### Compatibility
|
|
- Identical HTML output
|
|
- Same command-line interface
|
|
- Cross-platform binary
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Permission Errors**
|
|
```bash
|
|
# Ensure read permissions on target directory
|
|
chmod +r /path/to/directory
|
|
```
|
|
|
|
**Large Directories**
|
|
```bash
|
|
# Use verbose mode to monitor progress
|
|
s3-genindex -v /large/directory
|
|
|
|
# Exclude unnecessary files
|
|
s3-genindex -x "(\.git|node_modules|__pycache__)"
|
|
```
|
|
|
|
**Memory Usage**
|
|
```bash
|
|
# Process directories individually for very large trees
|
|
for dir in */; do s3-genindex "$dir"; done
|
|
```
|
|
|
|
### Debug Mode
|
|
|
|
Enable verbose output to see detailed processing:
|
|
|
|
```bash
|
|
s3-genindex -v /path/to/debug
|
|
```
|
|
|
|
## License
|
|
|
|
Licensed under the Apache License 2.0. See original Python script for full license text.
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Add tests for new functionality
|
|
4. Run `make check` to ensure code quality
|
|
5. Submit a pull request
|
|
|
|
## Changelog
|
|
|
|
### v1.0.0
|
|
- Initial Go rewrite
|
|
- Complete feature parity with Python version
|
|
- Comprehensive test suite
|
|
- Modern Go project structure |