nngit

Overview

A command-line utility for managing Git branches and history. nngit offers helpers for creating, switching, and deleting branches, discarding local changes, and undoing commits.

Features

• Create branches with optional prefixes and issue numbers
• Switch between local and remote branches
• Delete merged branches with optional origin pruning (supports -m and --all-merged flags)
• Push new branches with safety checks and upstream tracking
• Git activity reporting with colorized output and optional daily breakdowns
• Stage and unstage files with interactive multi-selection
• Discard staged/unstaged changes with file selection options
• Enhanced undo commits with soft/hard reset strategies, safety checks, and interactive selection
• Stop tracking files that match gitignore patterns with interactive selection
• Register and unregister template files for reuse across projects
• Edit overall nngit configuration

Installation

brew tap nikolainobadi/nntools
brew install nngit

Usage

Run commands via swift run or the built binary. A few examples:

$ nngit new-branch feature "Add login"
$ nngit switch-branch
$ nngit new-push                   # Push new branch with safety checks
$ nngit activity --days 7          # Show Git activity for last 7 days
$ nngit activity --days 30 --verbose # Activity with daily breakdown
$ nngit staging stage              # Interactively stage files
$ nngit staging unstage            # Interactively unstage files
$ nngit delete-branch -m           # Delete all merged branches (short flag)
$ nngit delete-branch --all-merged # Delete all merged branches (long flag)
$ nngit discard --files both       # Discard staged and unstaged changes
$ nngit undo hard 2 --select       # Interactive selection of commits to hard reset
$ nngit stop-tracking              # Stop tracking files matching gitignore patterns
$ nngit register-git-file --source ~/template.md --name README.md
$ nngit unregister-git-file README.md  # Remove registered template
$ nngit add-git-file                   # Add template to current repo
$ nngit edit-config --default-branch develop

New Push Workflow

Safely push new branches to remote with comprehensive checks:

$ nngit new-push                     # Push current branch with safety checks

Safety Features:

• Verifies remote repository exists
• Checks that no remote branch with the same name already exists
• Validates no uncommitted changes exist
• Compares with default branch and warns if behind (with user confirmation)
• Sets upstream tracking automatically
• Prevents accidental pushes with clear error messages

Git Activity Reporting

View Git activity statistics with colorized output and optional daily breakdowns:

$ nngit activity                     # Show today's activity (default: 1 day)
$ nngit activity --days 7            # Show activity for last 7 days
$ nngit activity --days 30 --verbose # Show 30-day activity with daily breakdown
$ nngit activity --no-color          # Disable colored output

Features:

• Colorized output using terminal colors (automatically disabled in CI/testing environments)
• Daily breakdown for multi-day periods with --verbose flag
• Statistics include: commits, files changed, lines added/deleted, total modifications
• Intelligent singular/plural formatting based on counts
• Comprehensive git log parsing with proper error handling
• Respects NO_COLOR environment variable

Staging Workflow

Interactively stage and unstage files with multi-selection:

$ nngit staging stage                # Select from unstaged/untracked files to stage
$ nngit staging unstage              # Select from staged files to unstage

Features:

• Multi-selection interface using arrow keys and space to select
• Lists all relevant files (unstaged, untracked, or staged depending on command)
• Executes individual git commands for each selected file
• Clean, user-friendly selection process

Undo Workflow

Undo commits using soft or hard reset strategies with enhanced safety features:

$ nngit undo 3                      # Soft reset 3 commits (moves to staging area, default)
$ nngit undo soft 2 --force         # Soft reset 2 commits, including from other authors
$ nngit undo soft --select          # Interactive selection from last 7 commits
$ nngit undo hard 1                 # Hard reset 1 commit (completely discards changes)
$ nngit undo hard 2 --force         # Hard reset 2 commits, including from other authors
$ nngit undo hard --select --force  # Interactive selection with force override

Safety Features:

• Enhanced authorship detection using both git username and email
• Automatic prevention of resetting commits by other authors (unless --force is used)
• Interactive commit selection with --select flag
• Clear confirmation prompts showing what will be affected

Stop Tracking Workflow

Manage files that should be untracked according to your .gitignore:

$ nngit stop-tracking               # Interactive workflow to stop tracking gitignored files
# (analyzes .gitignore patterns, finds matching tracked files, offers selection options)

Features:

• Reads .gitignore patterns and identifies tracked files that match
• Offers choice between stopping all matching files or selecting specific ones
• Handles complex gitignore patterns including wildcards, negation, and directory patterns
• Executes git rm --cached with proper file path escaping

Template File Management

Register template files for reuse across multiple repositories:

$ nngit register-git-file --source ~/templates/README.md --name README.md --nickname "Project Readme"
$ nngit register-git-file          # Interactive mode prompts for all options
$ nngit add-git-file               # Add registered template to current repository
$ nngit unregister-git-file "Project Readme"  # Remove by nickname
$ nngit unregister-git-file --all  # Remove all registered templates

Register Features:

• Register template files with custom names and nicknames
• Use --direct-path to reference files at their current location
• Interactive prompts for missing parameters
• Templates stored in ~/.config/nngit/templates/ by default
• Handles file conflicts with confirmation prompts

Unregister Features:

• Remove templates by filename or nickname
• Case-insensitive matching for convenience
• Interactive selection when no name provided
• --all flag to remove all registered templates
• Option to delete template files from disk

Configuration

nngit stores its settings in a JSON file located at ~/.config/nngit/config.json. This file is created automatically the first time you run the tool. You can modify values using the config command or by opening the file in your editor of choice.

The configuration includes settings for:

• Default branch name
• Branch loading behavior
• Rebase and prune preferences
• Branch prefix configurations (for structured branch naming)
• Registered template files (for reuse across projects)

Non-Homebrew users can build the executable manually:

swift build -c release

The compiled binary will be available at .build/release/nngit.

Architecture

This Swift CLI tool follows a clean, modular architecture with clear separation of concerns:

Project Structure

Sources/nngit/
├── Core/                     # Essential components
│   ├── Context/              # Dependency injection
│   ├── Models/               # Data models
│   └── Extensions/           # Type extensions
├── Services/                 # External integrations
│   ├── Git/                  # Git operations (protocols & implementations)
│   └── Configuration/        # Config management
├── Managers/                 # Business logic
│   ├── Branch/               # Branch-related workflows (including NewPushManager)
│   ├── FileOperations/       # File staging/unstaging/discarding/stop-tracking
│   ├── Reset/                # Commit reset operations
│   ├── Configuration/        # Template file and config management
│   └── Utility/              # Utility functions (including GitActivityManager)
├── Commands/                 # CLI command definitions
│   ├── Branch/               # Branch commands (NewBranch, SwitchBranch, DeleteBranch, NewPush)
│   ├── FileOperations/       # File operation commands (Staging, Discard, StopTracking)
│   ├── Reset/                # Reset commands (Undo with soft/hard variants)
│   ├── Utility/              # Utility commands (GitActivity)
│   └── Configuration/        # Config commands (EditConfig, RegisterGitFile, UnregisterGitFile, AddGitFile, NewGit, NewRemote)
├── Errors/                   # Error definitions
└── Main/Nngit.swift         # Main entry point (v0.4.1)

Key Design Principles

• Dependency Injection: Context-based injection for testability
• Feature-Based Organization: Related functionality grouped together
• Protocol/Implementation Split: Clean abstraction boundaries
• Enhanced Safety Systems: Comprehensive authorship detection and permission checks
• Comprehensive Testing: 350+ passing tests with behavior-driven approach and stable execution

Dependencies

• Built on swift-argument-parser for CLI parsing
• Uses SwiftShell and GitShellKit for Git operations
• Configuration managed via NnConfigKit
• User interaction through SwiftPicker

Documentation

The source is documented with inline comments, and a test suite resides under Tests/.

Troubleshooting

If you see a "missing git repository" error when running commands, ensure you are inside a git repository. Navigate to your project root or run git init to create one before using nngit.

Acknowledgments

• SwiftShell
• NnGitKit
• NnConfigKit
• swift-argument-parser
• SwiftPicker

About This Project

This public repository hosts a tool for automating everyday Git tasks on macOS. It streamlines branch workflows and provides safeguards when discarding work.

Contributing

Feel free to open issues and pull requests on GitHub.

License

This project is available under the MIT license. See LICENSE for details.