Skip to content

QUICKSTART.md

Latest commit

 

History

History
242 lines (170 loc) · 4.25 KB

QUICKSTART.md

File metadata and controls

242 lines (170 loc) · 4.25 KB

Quick Start (5 Minutes)

Get started with git-native-issue in 5 minutes. No theory, just commands.

Install

Homebrew (macOS/Linux)

brew install remenoscodes/git-native-issue/git-native-issue

Install Script (Any POSIX System)

curl -sSL https://raw.githubusercontent.com/remenoscodes/git-native-issue/main/install.sh | sh

Verify

git issue version
# git-issue version 1.3.3

Your First Issue

1. Create an Issue

cd your-git-repo/
git issue create "Add dark mode support" -m "Users have requested this feature"
# Created issue a7f3b2c

2. List Issues

git issue ls
# a7f3b2c [open]  Add dark mode support

3. Show Details

git issue show a7f3b2c

4. Add a Comment

git issue comment a7f3b2c -m "Working on this now. Will have PR ready by Friday."
# Added comment to a7f3b2c

5. Close the Issue

git issue state a7f3b2c --close --fixed-by abc123
# Closed issue a7f3b2c

6. Push to Remote

git push origin 'refs/issues/*'
# Your issues now travel with your code

Common Workflows

Create Issue with Labels and Priority

git issue create "Fix login crash" \
  -l bug -l auth -l urgent \
  -p critical \
  -a alice@example.com

Search Issues

git issue search "login"
# Searches titles, bodies, and comments

Filter by State

git issue ls --state open    # Default
git issue ls --state closed
git issue ls --all           # Both open and closed

Edit Issue Metadata

git issue edit a7f3b2c -p high --add-label security

Sync with Remote

# Pull issues from remote
git fetch origin 'refs/issues/*:refs/issues/*'

# Push your issues
git push origin 'refs/issues/*'

GitHub Bridge

Import Issues from GitHub

# Requires: gh CLI and jq
brew install gh jq
gh auth login

# Import all open issues
git issue import github:owner/repo

# Import all issues (open + closed)
git issue import github:owner/repo --state all

Export Issues to GitHub

git issue export github:owner/repo

Two-Way Sync

git issue sync github:owner/repo --state all

GitLab Bridge

Import Issues from GitLab

# Requires: glab CLI and jq
brew install glab jq
glab auth login

# Import all open issues
git issue import gitlab:group/project

# Import from self-hosted GitLab
git issue import gitlab:company/product \
  --url https://gitlab.company.com \
  --state all

Export Issues to GitLab

git issue export gitlab:group/project

Gitea/Forgejo Bridge

Setup Authentication

# Create token on Gitea/Forgejo instance
# Settings → Applications → Generate New Token
# Scopes: read:issue, read:repository (+ write:issue for export)

# Store token
mkdir -p ~/.config/git-native-issue
echo "your-token-here" > ~/.config/git-native-issue/gitea-token
chmod 600 ~/.config/git-native-issue/gitea-token

Import Issues from Gitea

# Requires: jq
brew install jq

# Import all open issues
git issue import gitea:owner/repo

# Import from self-hosted Gitea
git issue import gitea:company/product \
  --url https://gitea.company.com \
  --state all

# Import from Forgejo (e.g., Codeberg.org)
export FORGEJO_TOKEN="your-codeberg-token"
git issue import forgejo:username/project \
  --url https://codeberg.org \
  --state all

Export Issues to Gitea/Forgejo

git issue export gitea:owner/repo
git issue export gitea:owner/repo --url https://gitea.company.com

What's Next?

Learn More

Try Advanced Features

# Distributed merge (resolve divergent issue updates)
git issue merge origin

# Validate data integrity
git issue fsck

# Custom sorting and filtering
git issue ls --sort priority --reverse
git issue ls --assignee alice@example.com
git issue ls --priority critical

Get Help

git issue --help
git issue create --help
git issue ls --help

That's it! You're now tracking issues with Git. Issues travel with your code, sync with git fetch/push, and work completely offline.

Happy issue tracking! 🚀