repository-management

name	repository-management
description	Manage GitHub repositories - create, fork, branch, and file operations using gh CLI

GitHub Repository Management Skill

This skill provides comprehensive repository management operations including creating repositories, managing branches, and working with files.

Available Operations

1. Create Repository

Create a new GitHub repository in your account or organization.

2. Fork Repository

Fork an existing repository to your account or specified organization.

3. Create Branch

Create a new branch in a repository from an existing branch.

4. Search Repositories

Search for GitHub repositories using GitHub's search syntax.

5. Get File Contents

Retrieve the contents of a file or directory from a repository.

6. Create or Update File

Create a new file or update an existing file in a repository.

7. Push Multiple Files

Push multiple files to a repository in a single commit.

Usage Examples

Create a New Repository

Public repository:

gh repo create my-awesome-project --public --description "My awesome project" --clone

Private repository:

gh repo create my-private-repo --private --description "Private project" --clone

With README initialization:

gh repo create my-project --public --add-readme

Fork a Repository

Fork to your personal account:

gh repo fork owner/repo-name --clone

Fork to an organization:

gh repo fork owner/repo-name --org my-org --clone

Fork without cloning:

gh repo fork owner/repo-name

Create a Branch

Create from default branch:

gh api repos/owner/repo-name/git/refs -f ref=refs/heads/new-feature -f sha=$(gh api repos/owner/repo-name/git/refs/heads/main --jq '.object.sha')

Using Git directly (if repo is cloned):

cd repo-name
git checkout -b new-feature
git push -u origin new-feature

Search Repositories

Search by keyword:

gh search repos "machine learning" --limit 20

Search with filters:

gh search repos "web framework" --language python --stars ">1000" --limit 10

Search in organization:

gh search repos "org:myorg" --limit 50

Search by topic:

gh search repos "topic:docker" --stars ">100"

Get File Contents

View file contents:

gh api repos/owner/repo-name/contents/path/to/file.txt --jq '.content' | base64 -d

List directory contents:

gh api repos/owner/repo-name/contents/path/to/directory

Get file from specific branch:

gh api repos/owner/repo-name/contents/README.md?ref=develop --jq '.content' | base64 -d

Create or Update File

Create a new file:

echo "file content" | gh api repos/owner/repo-name/contents/path/to/newfile.txt \
  -X PUT \
  -f message="Add new file" \
  -f content=$(echo "file content" | base64) \
  -f branch=main

Update an existing file (requires SHA):

# First, get the file SHA
SHA=$(gh api repos/owner/repo-name/contents/path/to/file.txt --jq '.sha')

# Then update
echo "updated content" | gh api repos/owner/repo-name/contents/path/to/file.txt \
  -X PUT \
  -f message="Update file" \
  -f content=$(echo "updated content" | base64) \
  -f sha="$SHA" \
  -f branch=main

Push Multiple Files

For pushing multiple files, it's recommended to clone the repository and use Git:

# Clone the repository
gh repo clone owner/repo-name
cd repo-name

# Create/modify multiple files
echo "content1" > file1.txt
echo "content2" > file2.txt
mkdir -p src
echo "code" > src/main.py

# Commit and push
git add .
git commit -m "Add multiple files"
git push

Alternative: Using GitHub API for multiple files (requires tree/commit API):

# This is more complex and typically requires a script
# Recommended to use Git directly for multiple files

Common Patterns

Create Repository and Push Initial Code

# Create repository
gh repo create my-project --public --clone
cd my-project

# Add initial files
echo "# My Project" > README.md
echo "print('Hello')" > main.py

# Commit and push
git add .
git commit -m "Initial commit"
git push -u origin main

Fork, Branch, and Push Changes

# Fork the repository
gh repo fork upstream/repo-name --clone
cd repo-name

# Create feature branch
git checkout -b my-feature

# Make changes
echo "new feature" > feature.txt
git add feature.txt
git commit -m "Add new feature"

# Push branch
git push -u origin my-feature

# Create PR (using pull-request-management skill)
gh pr create --title "Add new feature" --body "Description of changes"

Clone Private Repository

# Ensure you're authenticated
gh auth status

# Clone
gh repo clone owner/private-repo

Error Handling

Repository Already Exists

# Check if repo exists first
gh repo view owner/repo-name 2>/dev/null && echo "Exists" || echo "Does not exist"

Insufficient Permissions

# Verify authentication and permissions
gh auth status

# Try refreshing credentials
gh auth refresh

File Not Found

# Verify the file path exists
gh api repos/owner/repo-name/contents/path/to/file.txt 2>&1 | grep -q "Not Found" && echo "File does not exist"

Best Practices

1. Always specify owner/repo format: Use owner/repo-name not just repo-name
2. Check authentication first: Run gh auth status before operations
3. Use descriptive commit messages: Include context about what changed and why
4. Branch protection: Set up branch protection rules for important branches
5. Clone for multiple changes: Use Git directly when making multiple file changes
6. Handle errors gracefully: Check command exit codes and handle failures

Related Skills

• issue-management - Create and manage issues
• pull-request-management - Work with pull requests
• commit-operations - View commit history

References

• GitHub CLI Manual
• GitHub API Documentation
• Git Documentation