vitesse-dependency-scripts/GIT-SETUP.md

Automated toolkit for managing dependencies with pnpm catalogs in Vue/Vite projects

# Git Setup Guide

This guide will help you prepare this project for git and make it runnable for others.

## 🚀 Quick Setup (First Time)

```bash
# Navigate to the project
cd dependency-scripts

# Run the setup script
./setup.sh

# Or manually:
chmod +x *.js *.sh
```

## 📦 Pushing to Git

### 1. Initialize Git Repository (if not already done)

```bash
git init
```

### 2. Configure .gitignore

The `.gitignore` file is already created and will exclude:
- `node_modules/`
- Backup files (`*.backup.*`)
- OS-specific files (`.DS_Store`, etc.)
- IDE files (`.vscode/`, `.idea/`, etc.)
- Log files
- Temporary files

### 3. Add Remote Repository

```bash
# Replace with your actual repository URL
git remote add origin https://github.com/your-username/your-repo.git

# Or for SSH
git remote add origin git@github.com:your-username/your-repo.git
```

### 4. Update package.json

Edit `package.json` and update:
- `author`: Your name or organization
- `repository.url`: Your git repository URL

```json
{
  "author": "Your Name <your.email@example.com>",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-username/your-repo.git"
  }
}
```

### 5. Commit and Push

```bash
# Stage all files
git add .

# Commit
git commit -m "Initial commit: Vitesse dependency management scripts"

# Push to main branch
git push -u origin main

# Or push to master branch
git push -u origin master
```

## 📥 For Others to Use Your Repository

Once pushed, others can use it like this:

### Option 1: Clone and Use Locally

```bash
# Clone the repository
git clone https://github.com/your-username/your-repo.git dependency-scripts
cd dependency-scripts

# Run setup
./setup.sh

# Use it
pnpm create my-awesome-app
```

### Option 2: Clone and Link Globally

```bash
# Clone the repository
git clone https://github.com/your-username/your-repo.git dependency-scripts
cd dependency-scripts

# Run setup
./setup.sh

# Link globally
pnpm link --global

# Now use from anywhere
cd ~/projects
vitesse-create my-new-project
```

### Option 3: Use with npx (if published to npm)

```bash
npx vitesse-dependency-scripts create my-app
```

## 🔄 Updating from Git

Users can pull the latest changes:

```bash
cd dependency-scripts
git pull origin main

# Ensure scripts are still executable
chmod +x *.js *.sh
```

## 📝 Recommended README Updates

After setting up your repository, update `README.md`:

1. Replace `<your-repo-url>` with your actual repository URL
2. Add badges (optional):
   - Build status
   - License badge
   - Version badge
   - Downloads badge

Example badges:
```markdown
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Node Version](https://img.shields.io/badge/node-%3E%3D14.18-brightgreen)
![pnpm](https://img.shields.io/badge/pnpm-%3E%3D7.0-orange)
```

## 🔒 Private Repository

If using a private repository:

```bash
# Team members need access
# Clone with authentication
git clone https://github.com/your-org/your-private-repo.git

# Or use SSH with keys
git clone git@github.com:your-org/your-private-repo.git
```

## 🏢 Enterprise/Organization Setup

For enterprise use:

1. **Host on internal Git server** (GitLab, Bitbucket, etc.)
2. **Create documentation** specific to your organization
3. **Add CI/CD** for automated testing
4. **Set up branch protection** rules
5. **Configure access permissions**

## 📚 Next Steps

After pushing to git:

1. ✅ Create a release/tag for version 1.0.0
2. ✅ Add a CHANGELOG.md
3. ✅ Set up GitHub Actions for CI (optional)
4. ✅ Create GitHub templates for issues/PRs
5. ✅ Add contributing guidelines (see CONTRIBUTING.md)
6. ✅ Consider publishing to npm

## 🎯 Publishing to npm (Optional)

To make it available via `npm install`:

```bash
# Login to npm
npm login

# Publish
npm publish

# Or publish scoped package
npm publish --access public
```

Then users can install globally:

```bash
npm install -g vitesse-dependency-scripts
vitesse-create my-app
```

## ⚠️ Important Notes

- ✅ All scripts have shebang (`#!/usr/bin/env node`) for direct execution
- ✅ Scripts are ES modules (`"type": "module"` in package.json)
- ✅ No external dependencies required (uses Node.js built-ins)
- ✅ Cross-platform compatible (Windows/Mac/Linux)
- ✅ Git-friendly (proper .gitignore included)

## 🔧 Troubleshooting

### Scripts not executable after git clone

```bash
chmod +x *.js *.sh
```

### Permission denied on setup.sh

```bash
chmod +x setup.sh
./setup.sh
```

### Cannot find module errors

Make sure the repository has `package.json` with `"type": "module"`

---

**Ready to share with your team!** 🎉