npm package: @runlater/auto-git
Description: A command-line application that automates common Git commands through an interactive terminal user interface (TUI)
Author: await
Latest version: 1.0.0

# auto-git

A command-line application that automates common Git commands through an intuitive terminal user interface (TUI). **auto-git** simplifies Git workflows by providing interactive prompts and a user-friendly menu system for managing your repositories.

## 🎯 Features

- **Repository Verification**: Automatically checks if the current directory is a Git repository and offers to initialize one if needed
- **Git Status Display**: View modified, staged, and untracked files with formatted, color-coded output
- **Interactive File Staging**: Easily stage and unstage files with interactive checkbox selections
- **Conventional Commits**: Guided commit process supporting commit types (feat, fix, docs, style, init, chore, etc.)
- **Commit Scoping**: Optional scope parameter for more organized commits
- **Interactive Commit Preview**: Review your commit message before finalizing
- **Push to Remote**: Simple push workflow with remote selection and branch management
- **Credential Management**: Prompt for GitHub credentials when needed
- **Full Workflow Mode**: Combine staging, committing, and pushing in one workflow
- **Error Handling**: Comprehensive error handling for all Git operations
- **Intuitive TUI**: Easy-to-navigate keyboard-driven interface
- **Keyboard Controls**: Navigate menus with arrow keys, select with Enter

## 📋 Requirements

- **Node.js**: >= 14.0.0
- **npm**: >= 6.0.0
- **Git**: >= 2.0 (installed and accessible from command line)

## 🚀 Installation

### Install Globally (Recommended)

```bash
npm install -g auto-git
```

Then run from anywhere:

```bash
auto-git
```

### Install Locally in Project

```bash
npm install auto-git
```

Then run with:

```bash
npx auto-git
```

### Or Clone and Run

```bash
git clone https://github.com/awaitUser/auto-git.git
cd auto-git
npm install
npm start
```

## 💻 Usage

### Quick Start

```bash
auto-git
```

This will launch the interactive TUI menu. Use arrow keys to navigate and Enter to select.

### Global Installation Usage

```bash
# Run the application from anywhere
auto-git

# Or with npx
npx auto-git
```

### Main Menu Options

The application presents the following options:

1. **📊 Show Git Status** - Display current repository status with modified, staged, and untracked files
2. **➕ Stage Files** - Interactively select and stage files for commit
3. **➖ Unstage Files** - Remove files from staging area
4. **💬 Commit Changes** - Create a commit with guided conventional commit format
5. **🚀 Push to Remote** - Push commits to remote repository with credential support
6. **✨ Stage, Commit & Push** - Complete workflow combining all three operations
7. **❌ Exit** - Close the application

### Workflow Examples

#### Example 1: Simple Commit

```
$ auto-git
[Main Menu]
→ 💬 Commit Changes
  Select commit type: feat
  Scope: api
  Subject: add user authentication endpoint
  Body: (optional detailed description)
  
  Commit Preview:
  feat(api): add user authentication endpoint
  
  Proceed with commit? (Y/n)
```

#### Example 2: Stage, Commit & Push

```
$ auto-git
[Main Menu]
→ ✨ Stage, Commit & Push
  [Shows current status]
  Select files to stage: (checkbox list)
  Select commit type: fix
  Subject: resolve login bug
  [Creates commit]
  Push to origin/master? (Y/n)
```

#### Example 3: Using npx

```bash
# First time - installs on the fly and runs
npx auto-git

# Shows Git Status
📊 Show Git Status
```

## 📚 Commit Types

auto-git supports conventional commit types:

- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Code style changes (formatting, missing semicolons, etc)
- **refactor**: Code refactoring without feature changes or bug fixes
- **perf**: Performance improvements
- **test**: Test changes
- **chore**: Build process, dependencies, or tooling changes
- **init**: Initial commit
- **ci**: CI/CD configuration changes

## 🎮 Keyboard Controls

- **Arrow Keys**: Navigate menu options
- **Enter/Return**: Select highlighted option
- **Space**: Toggle checkbox items in multi-select
- **Type**: Filter or input text as needed

## 🛠️ Technical Details

### Dependencies

- **nodegit** (v0.27.0): Node.js bindings for libgit2
- **inquirer** (v8.2.5): Interactive command line prompts
- **chalk** (v4.1.2): Terminal string styling
- **ora** (v5.4.1): Elegant terminal spinner

### Project Structure

```
auto-git/
├── bin/
│   └── cli.js                    # CLI entry point with shebang
├── src/
│   ├── index.js                  # Main application logic
│   └── utils/
│       ├── repositoryChecker.js  # Git repository validation
│       ├── statusDisplay.js      # Status display utilities
│       ├── staging.js            # File staging/unstaging
│       ├── commit.js             # Commit creation
│       └── push.js               # Push to remote
├── package.json                  # Project metadata
└── README.md                      # This file
```

## 🐛 Error Handling

auto-git includes comprehensive error handling for:

- Non-Git directories (offers initialization)
- Git configuration issues
- File staging/unstaging errors
- Commit creation failures
- Remote push failures with credential prompts
- Invalid inputs and edge cases

All errors display user-friendly messages in the terminal.

## 🔧 Configuration

### Git User Configuration

auto-git uses your Git configuration for commits:

```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

Set these before using auto-git to ensure commits have your information.

### Remote Setup

To use push functionality:

```bash
git remote add origin <repository-url>
```

## 📝 Examples

### Initialize a New Repository and Make First Commit

```bash
$ cd my-project
$ auto-git
→ [Prompted to initialize]
✓ Git repository initialized
→ 📊 Show Git Status
→ ➕ Stage Files
→ 💬 Commit Changes
  Type: init
  Subject: initial commit
  ✓ Commit created successfully!
```

### Push Changes to GitHub

```bash
$ auto-git
→ 🚀 Push to Remote
  Push branch "main" to remote? (Y/n)
  ✓ Successfully pushed to origin/main
```

## 🤝 Contributing

Contributions are welcome! To contribute:

1. **Fork** the repository at https://github.com/awaitUser/auto-git
2. **Create** a new branch for your feature: `git checkout -b feature/amazing-feature`
3. **Make** your changes and test them
4. **Commit** using conventional commits: `git commit -m 'feat: add amazing feature'`
5. **Push** to your branch: `git push origin feature/amazing-feature`
6. **Open** a Pull Request on GitHub

### Development Setup

```bash
# Clone the repository
git clone https://github.com/awaitUser/auto-git.git
cd auto-git

# Install dependencies
npm install

# Run in development
npm start
```

### Code Style

- Use arrow functions where appropriate
- Include JSDoc comments for functions
- Handle errors gracefully with try-catch
- Use chalk for colored output
- Test all Git operations in a test repository

## 📄 License

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

## 👨‍💻 Author

**await** - [@awaitUser](https://github.com/awaitUser)

## 🔗 Links

- **Repository**: https://github.com/awaitUser/auto-git
- **Issues**: https://github.com/awaitUser/auto-git/issues
- **npm Package**: https://www.npmjs.com/package/auto-git

## ❓ FAQ

**Q: Can I use auto-git with GitHub?**
A: Yes! auto-git works with any Git provider (GitHub, GitLab, Bitbucket, etc.)

**Q: Does auto-git work with SSH keys?**
A: Currently, auto-git prompts for credentials. SSH key support may be added in future versions.

**Q: Can I use auto-git in CI/CD pipelines?**
A: auto-git is designed for interactive use. For CI/CD, use native Git commands.

**Q: What if I make a mistake in the commit message?**
A: You'll have a preview of the commit message before confirming. If you've already committed, use `git amend` or create a new commit.

## 🐞 Troubleshooting

### "This directory is not a Git repository"
Make sure you're in the correct directory or run auto-git with initialization option.

### "Failed to push"
Check your remote configuration: `git remote -v`
Verify you have push permissions to the repository.

### "Node.js not found"
Install Node.js from https://nodejs.org (LTS recommended)

### "Git not found"
Install Git from https://git-scm.com

## 🚀 Future Enhancements

- Branch management (create, switch, delete branches)
- Stash operations
- Merge and rebase support
- Repository cloning
- SSH key authentication
- Commit history viewing
- Tag management
- Diff viewing

## 📞 Support

For issues, bugs, or feature requests, please open an issue on GitHub:
https://github.com/awaitUser/auto-git/issues

---

**Made with ❤️ by await**