A CLI tool that dynamically generates port numbers based on repository and branch names

branch2ports is a tool designed to avoid port conflicts when developing with git worktree or multiple branches in parallel. It generates unique port numbers by hashing the combination of repository identifier and branch name, then calculating an offset to add to base ports.

# Create configuration file interactively
npx branch2ports init

# Basic usage
npx branch2ports

# Or explicitly specify generate command
npx branch2ports generate

# Specify custom configuration file
npx branch2ports --config .my-config

# Specify output file
npx branch2ports --output .env.local

Create a .branch2ports file in your project root. Refer to .branch2ports.example for a sample configuration.

{
  "basePort": {
    "frontend": 3000,
    "backend": 5000,
    "database": 5432
  },
  "outputFile": ".env",
  "offsetRange": 1000
}

• basePort: Define base port numbers for each service
• outputFile: Output file name for generated port numbers (default: .env)
• offsetRange: Range for offset values (default: 1000)

1. Retrieves Git repository identifier (remote URL → repository root path → current directory, in order of preference) and branch name
2. Hashes the combination of repository identifier + branch name
3. Calculates offset value as the hash modulo offsetRange
4. Determines final port numbers by adding offset to base ports
5. Writes the results to the specified output file as environment variables

Uniqueness Guarantee: The same repository and branch combination always generates the same port numbers, while different repositories or branches generate different port numbers.

# .env file output example
FRONTEND_PORT=3247
BACKEND_PORT=5247
DATABASE_PORT=5679

• Parallel development with git worktree
• Local development environment with multiple branches
• Port management for Docker Compose
• Avoiding port conflicts within development teams

• Language: TypeScript
• Runtime: Node.js
• Dependencies: Minimal (CLI libraries like commander.js)
• Distribution: npm package (executable via npx)

• Node.js >= 16.0.0
• npm or yarn
• Git

# Clone the repository
git clone https://github.com/chaspy/branch2ports.git
cd branch2ports

# Install dependencies
npm install

# Build the project
npm run build

# Run the CLI locally
node dist/cli.js --help

# Watch mode for development
npm run dev

# Run tests in watch mode
npm run test:watch

# Type checking
npm run typecheck

# Linting
npm run lint

We maintain comprehensive test coverage with unit tests, integration tests, and E2E tests.

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run specific test file
npm test src/__tests__/port-calculator.test.ts

# Run tests in watch mode during development
npm run test:watch

• src/__tests__/*.test.ts - Unit tests for individual modules
• src/__tests__/e2e/*.test.ts - End-to-end CLI tests
• src/__tests__/fixtures/ - Test fixtures and mock data

When adding new features or fixing bugs:

1. Write tests first (TDD approach recommended)
2. Ensure tests pass locally before submitting PR
3. Maintain or improve code coverage

Example test:

describe('calculateOffset', () => {
  it('should generate consistent offsets for same input', () => {
    const offset1 = calculateOffset('repo-main', 1000);
    const offset2 = calculateOffset('repo-main', 1000);
    expect(offset1).toBe(offset2);
  });
});

1. Fork & Clone: Fork the repository and clone your fork
2. Branch: Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit: Use conventional commits format:
   • feat: New features
   • fix: Bug fixes
   • docs: Documentation changes
   • test: Test additions or changes
   • refactor: Code refactoring
   • chore: Maintenance tasks
4. Test: Ensure all tests pass (npm test)
5. Lint: Fix any linting issues (npm run lint)
6. Push: Push to your fork
7. PR: Open a Pull Request with a clear description

All pull requests are automatically tested with:

• Multiple Node.js versions (16.x, 18.x, 20.x)
• Type checking
• Linting
• Full test suite
• E2E tests

branch2ports/
├── src/
│   ├── cli.ts           # CLI entry point
│   ├── index.ts         # Main logic
│   ├── port-calculator.ts # Port calculation logic
│   ├── config.ts        # Configuration handling
│   ├── init.ts          # Interactive setup
│   └── types.ts         # TypeScript types
├── src/__tests__/       # Test files
├── dist/                # Compiled output (git ignored)
├── package.json         # Dependencies and scripts
└── tsconfig.json        # TypeScript configuration

For debugging during development:

# Run with Node.js inspector
node --inspect dist/cli.js

# View debug logs (if implemented)
DEBUG=branch2ports* node dist/cli.js

Releases are managed through GitHub Actions (coming soon):

1. Version bump in package.json
2. Create git tag
3. GitHub Actions publishes to npm

• Open an issue for bugs or feature requests
• Join discussions in GitHub Discussions
• Check existing issues before creating new ones

Please note that this project follows a standard Code of Conduct. By participating, you are expected to uphold this code.