push

What this skill does

# Git Push

Comprehensive guidance for Git push operations, from basic pushes to force push safety protocols and remote management.

## Overview

This skill provides complete guidance for Git push operations, emphasizing safety protocols (especially for force pushes), remote management, and troubleshooting common push scenarios. It complements the git-commit skill (which handles commit creation) by focusing exclusively on push operations and remote synchronization.

## When to Use This Skill

This skill should be used when:

- **Pushing commits** - Basic push operations to remote repositories
- **Force pushing** - Rewriting history with safety protocols (force-with-lease)
- **Pushing tags** - Annotated tags, lightweight tags, tag workflows
- **Managing remotes** - Adding, removing, renaming, configuring remote repositories
- **Troubleshooting pushes** - Rejected pushes, conflicts, authentication issues
- **Upstream configuration** - Setting up tracking branches, push.autoSetupRemote
- **Branch protection** - Understanding protected branches and push restrictions

**Trigger keywords:** push, force push, force-with-lease, remote, upstream, tracking branch, rejected push, push --force, git push origin, push tags, remote add

## Prerequisites

This skill assumes:

- **Git is installed** (verify with `git --version`)
- **Repository initialized** (local repo with `.git/` directory)
- **Remote configured** (typically `origin` for GitHub/GitLab/Bitbucket)
- **Basic Git knowledge** (commits, branches, remotes)

For Git installation help, see the **setup** skill.

## Quick Start

### Basic Push

```bash
# Push current branch to remote (if upstream is configured)
git push

# Push and set upstream for first-time push
git push -u origin feature-branch

# Push specific branch to remote
git push origin main
```

### Safe Force Push

```bash
# Safe force push (recommended - only overwrites if no one else pushed)
git push --force-with-lease

# Safest force push (recommended for maximum safety)
git push --force-with-lease --force-if-includes

# Force-with-lease for specific branch
git push --force-with-lease origin feature-branch
```

### Push Tags

```bash
# Push specific tag
git push origin v1.0.0

# Push all tags
git push --tags

# Push commits + annotated tags pointing to them
git push --follow-tags
```

## Core Capabilities

### 1. Basic Push Operations

Push local commits to remote repositories for collaboration and backup.

**Essential commands:**

```bash
# Push current branch (upstream must be configured)
git push

# Push and set upstream (first-time push)
git push -u origin feature-branch

# Push specific branch
git push origin main

# Dry run (preview without pushing)
git push --dry-run
```

**📖 For detailed configuration:** See [references/push-configuration.md](references/push-configuration.md) for upstream setup, push strategies, and advanced options.

---

### 2. Force Push Safety Protocols

Rewrite remote history safely when necessary (after rebasing, amending, or squashing commits).

**CRITICAL SAFETY RULES:**

- ✅ **ONLY force push on feature branches** (your personal work)
- ✅ **ALWAYS use `--force-with-lease`** (not `--force`)
- ❌ **NEVER force push to main/master/develop** (shared branches)
- ❌ **NEVER force push if others are working on the same branch**

**Safe force push commands:**

```bash
# ✅ SAFE: Only overwrites if no one else pushed since your last fetch
git push --force-with-lease

# ✅ SAFEST: Maximum safety with force-if-includes
git push --force-with-lease --force-if-includes
```

**📖 For comprehensive safety guidance:** See [references/force-push-safety.md](references/force-push-safety.md) for detailed safety protocols, pre-push checklist, recovery procedures, and branch protection.

---

### 3. Tag Pushing

Push version tags to remote for releases and milestones.

**Quick commands:**

```bash
# Create and push annotated tag (recommended for releases)
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# Push all tags
git push --tags

# Push commits + annotated tags (recommended)
git push --follow-tags
```

**📖 For complete tag workflows:** See [references/tag-pushing.md](references/tag-pushing.md) for tag types, strategies, aliases, and best practices.

---

### 4. Remote Management

Configure and manage remote repositories for push/fetch operations.

**Quick commands:**

```bash
git remote -v                    # List remotes
git remote add origin <url>      # Add remote
git remote set-url origin <url>  # Change URL
git remote rename origin upstream # Rename remote
```

**📖 For detailed remote management:** See [references/remote-management.md](references/remote-management.md) for configuration, fork workflows, and credential management.

---

### 5. Troubleshooting Push Issues

Diagnose and resolve common push failures and conflicts.

**Common issues - quick fixes:**

```bash
# Rejected push (non-fast-forward)
git pull --rebase && git push

# Authentication failure
ssh -T [email protected]  # Test SSH
git remote set-url origin [email protected]:username/repo.git

# Protected branch
git switch -c feature-branch
git push -u origin feature-branch
```

**📖 For comprehensive troubleshooting:** See [references/troubleshooting.md](references/troubleshooting.md) for detailed diagnosis and solutions.

---

## Common Workflows

### Feature Branch Development

```bash
git switch -c feature/user-auth
git commit -m "feat(auth): implement authentication"
git push -u origin feature/user-auth  # First push sets upstream
git push  # Subsequent pushes
```

### Rebase and Force Push

```bash
git fetch origin
git rebase origin/main
git push --force-with-lease  # Safe force push
```

### Hotfix to Production

```bash
git switch main && git pull
git switch -c hotfix/critical-bug
git commit -m "fix: resolve critical bug"
git push -u origin hotfix/critical-bug
gh pr create --title "HOTFIX: ..."
```

**📖 For additional workflows:** See [references/workflows.md](references/workflows.md) for fork contribution, release tagging, and complex multi-remote scenarios.

---

## Best Practices

**Critical Safety Rules:**

- ✅ Always use `--force-with-lease` (not `--force`)
- ✅ Never force push to main/master/develop
- ✅ Verify no sensitive data before pushing
- ✅ Run tests before pushing (don't push broken code)

**Push Frequency:**

- ✅ Push daily for backup and collaboration
- ✅ Push after completing logical units of work
- ❌ Don't push broken code or sensitive data

**📖 For comprehensive best practices:** See [references/best-practices.md](references/best-practices.md) for safety protocols, security, collaboration guidelines, and advanced scenarios.

---

## References

**Detailed Guides:**

- [references/push-configuration.md](references/push-configuration.md) - Upstream setup, push strategies, advanced options
- [references/force-push-safety.md](references/force-push-safety.md) - Force push safety protocols and recovery
- [references/tag-pushing.md](references/tag-pushing.md) - Tag types, strategies, and workflows
- [references/remote-management.md](references/remote-management.md) - Remote configuration and fork workflows
- [references/troubleshooting.md](references/troubleshooting.md) - Push issue diagnosis and solutions
- [references/workflows.md](references/workflows.md) - Common workflow patterns
- [references/best-practices.md](references/best-practices.md) - Safety, security, and collaboration

**Related Skills:**

- **git-commit** - Commit creation, commit messages, PR workflows
- **config** - Git configuration, aliases, credential management
- **line-endings** - .gitattributes, Git LFS setup

---

## Test Scenarios

### Scenario 1: Basic feature branch push

**Query**: "I made some commits on my feature branch. How do I push them to the remote?"

**Expected Behavior**:

- Skill activates on "push", "feature branch", "commits", "remote"
- Provides basic push command with upstream setup
- Explains -u flag for first-time push

### Sce