Skip to content

README.md

Latest commit

 

History

History
217 lines (159 loc) · 4.43 KB

README.md

File metadata and controls

217 lines (159 loc) · 4.43 KB

Ultimate Golang Justfile

A comprehensive, production-ready Justfile system for Go projects of any size. This Justfile provides a complete set of commands for development, testing, building, and deployment workflows while remaining flexible and customizable.

Note: This is a just-based alternative to ultimate-gomake. Both provide identical functionality but use different build systems.

🚀 Features

  • Flexible Configuration: Support for environment variables, .env files, and command-line overrides
  • Multi-Environment Support: Development, staging, and production builds
  • Cross-Platform Building: Support for multiple OS/Architecture combinations with optimized build flags
  • Advanced Testing: Unit, integration, and end-to-end testing with coverage reports and benchmarking
  • Docker Integration: Build, push, and run Docker containers
  • Database Operations: Migration management and database utilities
  • Development Tools: Hot reload, formatting, linting, and security scanning
  • CI/CD Ready: Integrated pipeline support for common CI systems
  • Documentation: Automatic API documentation generation
  • Monorepo Support: Build and manage multiple services
  • Comprehensive Reporting: Test coverage, benchmarks, and security reports
  • Version Control Integration: Automatic version detection and build information embedding

📋 Prerequisites

  • Go 1.21 or higher
  • just
  • Docker (optional)
  • Git

🛠 Installation

  1. Install just if you haven't already:
# On macOS
brew install just

# On Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash

# On Windows
winget install just
  1. Copy the justfile to your project root:
curl -O https://raw.githubusercontent.com/crazywolf132/ultimate-gojust/main/justfile
  1. Initialize your project:
just init

This will:

  • Create necessary directories
  • Initialize Go modules
  • Install required tools
  • Create default configuration files

⚙️ Configuration

Environment Variables

Create a .env file in your project root to override default settings:

# Project Configuration
PROJECT_NAME=myapp
ORGANIZATION=myorg
ENABLE_DOCKER=true
ENABLE_PROTO=false

# Build Settings
CGO_ENABLED=0
COVERAGE_THRESHOLD=80

# Docker Settings
DOCKER_REGISTRY=docker.io
DOCKER_REPO=myorg/myapp

Project Structure

The Justfile assumes the following project structure:

.
├── main/
│   └── main.go
├── pkg/
├── internal/
├── api/
├── docs/
├── scripts/
├── build/
├── configs/
├── test/
│   ├── e2e/
│   └── integration/
└── justfile

🎯 Common Commands

Development

# Start development with hot reload
just dev

# Run tests
just test

# Run tests with coverage
just test-coverage

# Format and lint code
just fmt lint

# Generate mocks and protobuf
just generate

Building

# Build for current platform
just build

# Build for all platforms
just build-all

# Build with debug symbols
just build-debug

# Build with race detector
just build-race

Docker Operations

# Build Docker image
just docker-build

# Push Docker image
just docker-push

# Run in Docker container
just docker-run

Database Operations

# Run migrations
just db-migrate

# Rollback last migration
just db-rollback

# Reset database
just db-reset

Maintenance

# Install/update dependencies
just deps
just deps-update

# Clean build artifacts
just clean

# Update tools
just tools

🎨 Customization

Adding New Recipes

Add custom recipes at the end of the justfile:

# Custom recipe description
custom-target:
    echo "Running custom target..."
    # Custom commands here

Modifying Existing Recipes

Override existing recipes by redefining them in config.just:

# config.just
# Custom test implementation
test:
    echo "Running custom tests..."
    # Custom test commands

🤝 Contributing

  1. Fork the repository
  2. Create your feature branch
  3. Commit your changes
  4. Push to the branch
  5. Create a new Pull Request

📜 License

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

🙏 Acknowledgements

Special thanks to the Go community and all contributors who have helped shape this Justfile system.