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)
```bash
# 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
```bash
# 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`):

```bash
# 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!)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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

```bash
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

```bash
# 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

```bash
# 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