gitea-creator/README.md

Gitea Creator

A command line tool to create repositories on Gitea servers with automatic git setup.

Features

• Create repositories on Gitea servers via API
• Interactive prompts for git initialization and setup
• Automatic remote configuration
• Optional automatic pushing to the new repository
• Support for public/private repository creation
• Comprehensive .gitignore creation for Node.js projects

Installation

Option 1: Local Development

1. Clone this repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. The CLI will be available at ./dist/index.js

Option 2: Global Installation (Development)

1. Clone this repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Link globally: npm link
5. Use gitea-creator or gitea command anywhere

Option 3: Global Installation (from npm)

# If published to npm
npm install -g gitea-creator

# Use anywhere with either command
gitea-creator my-repo --public
gitea my-repo --public  # Short alias

Option 4: Direct Usage

# Run directly without global installation
node dist/index.js <repository-name> [options]

Environment Setup

For Local Development

Create a .env file (copy from env.example):

# Copy the example file
cp env.example .env

# Edit the .env file with your values
# GITEA_TOKEN=your_gitea_access_token
# GITEA_API_URL=https://your-gitea-server.com/api/v1

For Global Installation

When installed globally, the tool supports multiple configuration methods:

Option 1: Automated Setup (Easiest!)

# Interactive setup - adds environment variables to your shell profile
gitea --setup
# or
gitea-creator --setup

# Follow the prompts, then reload your shell:
source ~/.zshrc  # or ~/.bashrc

Option 2: Manual Environment Variables

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GITEA_TOKEN=your_gitea_access_token
export GITEA_API_URL=https://your-gitea-server.com/api/v1

# Reload your shell
source ~/.zshrc  # or ~/.bashrc

Option 3: Global Configuration File

# Create global config directory
mkdir -p ~/.gitea-creator

# Create .env file
echo "GITEA_TOKEN=your_token_here" > ~/.gitea-creator/.env
echo "GITEA_API_URL=https://your-gitea-server.com/api/v1" >> ~/.gitea-creator/.env

Option 4: View Configuration Instructions

# Get setup instructions anytime
gitea --config
# or
gitea-creator --config

Getting a Gitea Access Token

1. Log into your Gitea server
2. Go to Settings → Applications
3. Click "Manage Access Tokens"
4. Generate a new token with repository permissions

Usage

gitea-creator <repository-name> [options]
# or use the short alias
gitea <repository-name> [options]

Options

• -p, --public: Create a public repository (non-private)
• -d, --description <description>: Add a description to the repository
• --https: Use HTTPS URL instead of SSH URL (SSH is default)
• --setup: Interactive setup for shell environment variables
• -c, --config: Show configuration setup instructions
• -h, --help: Display help information

Examples

# Setup environment variables (first time only)
gitea --setup

# Create a private repository (SSH URL by default)
gitea my-new-repo
gitea-creator my-new-repo  # Same thing

# Create a public repository with description
gitea my-public-repo --public --description "My awesome project"

# Create with HTTPS URL instead of SSH
gitea my-repo --https

# Combine options
gitea my-repo -p -d "Short description" --https

# Get configuration help
gitea --config

Workflow

When you run the tool, it will:

1. Create Repository: Create the repository on your Gitea server with the specified options
2. Display URL: Show the remote clone URL for the new repository
3. Git Initialization: If no git repository exists, ask if you want to initialize one
   • Creates .gitignore with Node.js patterns if initializing
4. Remote Setup: Ask if you want to set the new repository as the remote origin (defaults to yes)
5. Pushing: Ask if you want to push the current repository (defaults to yes)
   • Automatically handles initial commits if there are uncommitted changes
   • Renames master branch to main if needed

Interactive Prompts

All prompts default to "yes" - you can just press Enter to accept the defaults:

• Initialize git repository? (if none exists)
• Set remote origin?
• Push to remote?
• Commit changes first? (if there are uncommitted changes)

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Test the CLI
node dist/index.js my-test-repo --public
# or if linked globally
gitea my-test-repo --public

Requirements

• Node.js 18+
• Git (for git operations)
• Valid Gitea server access token