Bulk Operations

Ghit excels at managing multiple issues at once, saving time when setting up new repositories or performing batch updates.

Overview

Bulk operations allow you to:

Create dozens of issues from markdown files
Update multiple issues with smart diffing
Delete issue ranges efficiently
Track changes in version control

Seeding Issues

Create multiple issues from a directory of markdown files.

Directory Structure

Organize your issues in a directory:

issues/
├── 001-setup-ci-pipeline.md
├── 002-add-unit-tests.md
├── 003-update-documentation.md
├── 004-improve-error-handling.md
└── 005-add-logging.md

Markdown File Format

Each file represents one issue with frontmatter metadata:

markdown

---
type: Feature
title: Setup CI Pipeline
labels: ['enhancement', 'ci', 'devops']
assignees: ['devops-team', 'ci-admin']
---

## Description

Implement GitHub Actions workflow for automated testing and deployment.

## Tasks

- [ ] Create workflow file
- [ ] Configure test jobs
- [ ] Add deployment steps
- [ ] Set up environment secrets

## Acceptance Criteria

- All tests pass on every push
- Automatic deployment to staging
- Production deployment on release tags

Running the Seeder

bash

ghit issues:seed ./issues

This will:

Parse all .md files in the directory
Extract frontmatter (title, labels, assignees)
Use remaining content as issue body
Create issues in sequential order
Display progress with success/error messages

With Specific Repository

bash

ghit issues:seed ./issues --repo owner/repository

With Single Markdown Issues File

bash

ghit issues:seed ./issues/multiple-issues.md

When using a single file, each issue should be separated by ++++++ or ====== lines.

txt

---
title: Bug: Login Fails
labels: bug, auth
type: Bug
---

## Description

Login fails for users with special characters in their password.

++++++

---
title: Feature: Export Data
labels: feature, data
type: Feature
---

## Description

Allow users to export their data in CSV format.

Example Output

✔ DNS resolution successful: 140.82.121.6
✔ GitHub access validated successfully.
✔ Found 3 issue files
✔ Found 2 existing issues.

ℹ  INFO  Issues to CREATE:

1. Initialize API with Next.js API routes, food and database configuration
2. Define database schema and create Prisma models for all entities
3. Create authentication endpoints for wallet-based login

⚠️   CONFIRM  This will create 3 new issues on GitHub.
✔ Do you want to proceed? Yes

✔ Created #29: Initialize API with Next.js API routes, food and database configuration
ℹ  URL  https://github.com/toneflix-forks/dummy/issues/29

✔ Created #30: Define database schema and create Prisma models for all entities
ℹ  URL  https://github.com/toneflix-forks/dummy/issues/30

✔ Created #31: Create authentication endpoints for wallet-based login
ℹ  URL  https://github.com/toneflix-forks/dummy/issues/31

✔ All 3 issues processed.
=========================
✔ Created: 3
x Failed: 0
> Skipped: 0
☑ Total: 3
========================

Updating Issues

Modify existing issues based on updated markdown files.

How It Works

The updater uses intelligent diffing to detect changes:

Reads your markdown files
Fetches corresponding issues from GitHub
Compares content using diff algorithm
Updates only modified fields
Preserves unchanged data

Smart Diffing

Only updates when content actually changes:

Title changed → Updates title
Labels added/removed → Updates labels array
Body modified → Updates body content
No changes → Skips update (saves API calls)

Running the Updater

bash

ghit issues:update ./issues

Workflow Example

Create initial issues:
bash
```
ghit issues:seed ./issues
```

Make changes to markdown files:

markdown

---
type: Task
title: Setup CI Pipeline (Updated)
labels: ['enhancement', 'ci', 'devops', 'priority']
assignees: ['devops-team', 'ci-admin', 'new-member']
---

## Description (Enhanced)

Implement comprehensive GitHub Actions workflow...

Update the issues:
bash
```
ghit issues:update ./issues
```

Only modified issues are updated:

   ✔ DNS resolution successful: 140.82.121.5
   ✔ GitHub access validated successfully.
   ✔ Found 3 issue files
   ✔ Found 5 existing issues.

   ℹ  INFO  Issues to UPDATE:

   >  Initialize API with Next.js API routes, food and database configuration
      Existing: #29 (open)
   >  Define database schema and create Prisma models for all entities
      Existing: #30 (open)
   >  Create authentication endpoints for wallet-based login
      Existing: #31 (open)

   ⚠️   CONFIRM  This will update 3 existing issues on GitHub.
   ✔ Do you want to proceed? Yes

   ✔ Updated #29: Initialize API with Next.js API routes, food and database configuration
   ℹ  URL  https://github.com/toneflix-forks/dummy/issues/29

   ✔ Updated #30: Define database schema and create Prisma models for all entities
   ℹ  URL  https://github.com/toneflix-forks/dummy/issues/30

   ✔ Updated #31: Create authentication endpoints for wallet-based login
   ℹ  URL  https://github.com/toneflix-forks/dummy/issues/31

   ✔ All 3 issues processed.
   =========================
   ✔ Updated: 3
   x Failed: 0
   > Skipped: 0
   ☑ Total: 3
   ========================

Deleting Issues

Remove multiple issues in a range.

Basic Usage

bash

ghit issues:delete

With Confirmation

The command will:

Show a list of all deletable issues
You can select multiple issues to delte
Ask for confirmation
Delete issues one by one
Display progress

Example Output

✔ 2 issues fetched successfully.
? Select Issue
❯◯ #27: 🟢 Define database schema and create Prisma models for all entities
◯ #26: 🟢 Initialize API with Next.js API routes, food and database.

↑↓ navigate • space select • a all • i invert • ⏎ submit

Specific Repository

bash

ghit issues:delete owner/repository

DANGER

Issue deletion is permanent. Deleted issues cannot be recovered. Always double-check before confirming.

Version Control Integration

Track your issues in Git for better collaboration and history.

Repository Structure

project/
├── .git/
├── .gitignore
├── src/
├── docs/
└── .github/
└── issues/
├── 001-feature-a.md
├── 002-feature-b.md
└── 003-bug-fix.md

Workflow

Initial Setup

bash

mkdir -p .github/issues
cd .github/issues
# Create your markdown files

Commit to Git

bash

git add .github/issues/
git commit -m "Add initial issue templates"
git push origin main

Seed to GitHub
bash
```
ghit issues:seed .github/issues
```

Team Member Makes Changes

bash

# Edit .github/issues/001-feature-a.md
git commit -am "Update feature A requirements"
git push

Sync to GitHub

bash

git pull
ghit issues:update .github/issues

Best Practices

File Naming

Use numeric prefixes for ordering:

001-first-issue.md
002-second-issue.md
...
099-ninety-ninth-issue.md

This ensures:

Predictable creation order
Easy file management
Clear visual ordering

Frontmatter Standards

Be consistent with metadata:

yaml

---
type: Bug
title: Clear, Descriptive Title
labels: ['type:feature', 'priority:high', 'area:frontend']
assignees: ['username1', 'username2']
---

Label conventions:

type: - feature, bug, enhancement, docs
priority: - low, medium, high, critical
area: - frontend, backend, devops, design

Content Structure

Use markdown effectively:

markdown

---
title: Feature Title
labels: ['feature']
---

## Overview

Brief description of the feature.

## Requirements

- Requirement 1
- Requirement 2

## Tasks

- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Acceptance Criteria

- Criteria 1 is met
- Criteria 2 is met

## Additional Context

Any extra information, links, or references.

Incremental Updates

Don't recreate everything at once:

Start with high-priority issues
Seed them first
Iterate based on feedback
Add more issues as needed

Review Before Seeding

Check files before bulk creation:

bash

# Preview what will be created
ls .github/issues/
cat .github/issues/*.md

Backup Important Ranges

Before bulk deletion, if you have generated commands:

bash

# Export issues first (using generated commands)
ghit issues:list-for-repo > backup.json

Real-World Examples

Project Kickoff

Set up a new repository with standard issues:

bash

# Create template directory
mkdir -p project-templates/standard-setup

# Add issue templates
cat > project-templates/standard-setup/001-setup-ci.md << 'EOF'
---
title: Setup CI/CD Pipeline
labels: ["devops", "setup"]
assignees: ["devops-lead"]
---
Configure GitHub Actions for CI/CD
EOF

# Create more templates...

# Seed to multiple projects
ghit set-repo org/project-a
ghit issues:seed project-templates/standard-setup

ghit set-repo org/project-b
ghit issues:seed project-templates/standard-setup

Migration from Other Tools

Convert issues from Jira, Linear, etc.:

bash

# 1. Export from other tool (format as markdown)
# 2. Place in directory
# 3. Seed to GitHub

ghit issues:seed ./migrated-issues

Sprint Planning

Create sprint issues in bulk:

bash

# Sprint directory structure
sprint-2024-Q1/
├── 001-user-story-1.md
├── 002-user-story-2.md
└── 003-bug-fixes.md

ghit issues:seed sprint-2024-Q1

Quarterly Goals

Track OKRs as issues:

bash

okrs-2024-Q1/
├── objective-1-increase-users.md
├── objective-2-improve-performance.md
└── objective-3-expand-features.md

ghit issues:seed okrs-2024-Q1

Automation

CI/CD Integration

Auto-sync issues on changes:

yaml

# .github/workflows/sync-issues.yml
name: Sync Issues

on:
  push:
    paths:
      - '.github/issues/**'
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Ghit
        run: npm install -g ghit

      - name: Update Issues
        run: ghit issues:update .github/issues
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Scripted Workflows

Combine with shell scripts:

bash

#!/bin/bash
# bulk-create-features.sh

FEATURES=("Login" "Dashboard" "Settings" "Profile" "Notifications")

for i in "${!FEATURES[@]}"; do
  NUM=$(printf "%03d" $((i+1)))
  FEATURE="${FEATURES[$i]}"

  cat > "issues/${NUM}-${FEATURE,,}.md" << EOF
---
title: Implement ${FEATURE}
labels: ["feature", "frontend"]
assignees: ["dev-team"]
---

Implement ${FEATURE} feature for the application.
EOF
done

ghit issues:seed ./issues

Troubleshooting

Rate Limiting

If you hit rate limits during bulk operations:

bash

# Reduce concurrency (future feature)
# For now, seed in smaller batches

ghit issues:seed ./issues/batch-1
sleep 60
ghit issues:seed ./issues/batch-2

Validation Errors

If issues fail to create:

Check frontmatter syntax (valid YAML)
Verify labels exist in repository
Confirm assignees have access

Enable debug mode:

bash

ghit config --debug true
ghit issues:seed ./issues

Diff Detection Issues

If updates aren't detected:

Check file encoding (use UTF-8)
Verify line endings (LF, not CRLF)
Remove invisible characters
Check that issue numbers match filenames

Permission Errors

Ensure your token has proper scopes:

bash

# Re-login to refresh permissions
ghit logout
ghit login

Required scopes:

repo - Full repository access
write:org - Organization access (if applicable)

Performance Tips

Large Batches

For 100+ issues:

Split into multiple directories
Seed in batches
Monitor progress
Use version control to track seeded files

Network Optimization

Run on stable internet connection
Avoid VPNs that might throttle
Consider time of day (GitHub's load)

File Organization

Keep directories focused:

issues/
├── features/
│ └── _.md
├── bugs/
│ └── _.md
└── enhancements/
└── \*.md

Seed by category:

bash

ghit issues:seed issues/features
ghit issues:seed issues/bugs

Next Steps

Issues API Reference - Full command documentation
Configuration - Customize behavior

Bulk Operations ​

Overview ​

Seeding Issues ​

Directory Structure ​

Markdown File Format ​

Running the Seeder ​

With Specific Repository ​

With Single Markdown Issues File ​

Example Output ​

Updating Issues ​

How It Works ​

Smart Diffing ​

Running the Updater ​

Workflow Example ​

Deleting Issues ​

Basic Usage ​

With Confirmation ​

Example Output ​

Specific Repository ​

Version Control Integration ​

Repository Structure ​

Workflow ​

Best Practices ​

File Naming ​

Frontmatter Standards ​

Content Structure ​

Incremental Updates ​

Review Before Seeding ​

Backup Important Ranges ​

Real-World Examples ​

Project Kickoff ​

Migration from Other Tools ​

Sprint Planning ​

Quarterly Goals ​

Automation ​

CI/CD Integration ​

Scripted Workflows ​

Troubleshooting ​

Rate Limiting ​

Validation Errors ​

Diff Detection Issues ​

Permission Errors ​

Performance Tips ​

Large Batches ​

Network Optimization ​

File Organization ​

Next Steps ​

Bulk Operations

Overview

Seeding Issues

Directory Structure

Markdown File Format

Running the Seeder

With Specific Repository

With Single Markdown Issues File

Example Output

Updating Issues

How It Works

Smart Diffing

Running the Updater

Workflow Example

Deleting Issues

Basic Usage

With Confirmation

Example Output

Specific Repository

Version Control Integration

Repository Structure

Workflow

Best Practices

File Naming

Frontmatter Standards

Content Structure

Incremental Updates

Review Before Seeding

Backup Important Ranges

Real-World Examples

Project Kickoff

Migration from Other Tools

Sprint Planning

Quarterly Goals

Automation

CI/CD Integration

Scripted Workflows

Troubleshooting

Rate Limiting

Validation Errors

Diff Detection Issues

Permission Errors

Performance Tips

Large Batches

Network Optimization

File Organization

Next Steps