129 lines
5.6 KiB
Markdown
129 lines
5.6 KiB
Markdown
---
|
|
name: git-workflow
|
|
description: Procedures for git commits, worktrees, branches, and GitHub PRs — load
|
|
before any git operation
|
|
permalink: opencode-config/skills/git-workflow/skill
|
|
---
|
|
|
|
## Git Commit Procedure
|
|
|
|
1. Run `git status` to see all untracked and modified files.
|
|
2. Run `git diff` (staged + unstaged) to review changes that will be committed.
|
|
3. Run `git log --oneline -5` to see recent commit message style.
|
|
4. Draft a Conventional Commit message (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`):
|
|
- Focus on **why**, not **what**.
|
|
- 1-2 sentences max.
|
|
- Match the repository's existing style.
|
|
5. Check for secrets: do NOT commit `.env`, credentials, or key files.
|
|
6. The managed per-repo basic-memory project directory is `<repo>/.memory/`; do not edit managed `.memory/*` files directly. Older repo-local memory workflow artifacts (including `.memory.legacy/` and legacy contents from prior workflows) are non-authoritative and should not be edited unless explicitly migrating historical content into basic-memory.
|
|
7. Stage relevant files: `git add <files>` (not blindly `git add .`).
|
|
8. Commit: `git commit -m "<message>"`.
|
|
9. Run `git status` after commit to verify success.
|
|
|
|
## Git Worktree Procedure
|
|
|
|
### When to use worktrees:
|
|
- Always use a worktree for new feature work to keep `main` clean.
|
|
- **One worktree per independent workstream.** If implementing multiple unrelated features, create separate worktrees for each.
|
|
|
|
### Deciding on worktree count:
|
|
- **1 worktree**: Single feature, or 2 tightly-coupled features sharing state/files.
|
|
- **2+ worktrees**: Features that touch different domains, have different risk profiles, or could ship independently. Each gets its own worktree, branch, and PR.
|
|
|
|
### Creating a worktree for a new feature:
|
|
```bash
|
|
# From project root
|
|
mkdir -p .worktrees
|
|
git check-ignore -q .worktrees || { printf "Add .worktrees/ to .gitignore before continuing.\n"; exit 1; }
|
|
git worktree add .worktrees/<feature-name> -b <branch-name>
|
|
```
|
|
|
|
Before starting feature implementation in the new worktree:
|
|
- Verify `.worktrees/` is the project-local location and ignored by git before creating or reusing worktrees.
|
|
- Run project-declared setup/config scripts if the worktree needs dependencies or generated files.
|
|
- Run a baseline verification (project-declared check/test/lint scripts) to confirm the branch is clean before making changes.
|
|
- If baseline verification fails, stop and diagnose the environment or branch state before coding.
|
|
|
|
### Creating multiple worktrees for independent workstreams:
|
|
```bash
|
|
# From project root — create all worktrees upfront
|
|
git worktree add .worktrees/<workstream-1> -b feat/<workstream-1>
|
|
git worktree add .worktrees/<workstream-2> -b feat/<workstream-2>
|
|
```
|
|
|
|
### Working in a worktree:
|
|
- All file edits, test runs, and dev server starts must use the worktree path.
|
|
- Example: `workdir="/path/to/project/.worktrees/my-feature"` for all bash commands.
|
|
- **Each coder invocation must target a specific worktree** — never mix worktrees in one coder dispatch.
|
|
|
|
### After implementation and tests pass: choose one finish path
|
|
|
|
1. **Merge locally**
|
|
- Merge `<branch-name>` into your tracked/current base branch, then remove the feature worktree.
|
|
- If the branch is fully integrated and no longer needed, delete it.
|
|
2. **Push and open PR**
|
|
- Push `<branch-name>` and create a PR to the base branch using the GitHub PR procedure below.
|
|
- Keep the worktree until review/merge is complete, then remove the worktree and delete the merged branch.
|
|
3. **Keep branch/worktree for later**
|
|
- Leave branch and worktree in place when work is paused or awaiting input.
|
|
- Record the next step and expected resume point so cleanup is not forgotten.
|
|
4. **Discard work (destructive)**
|
|
- Only for work you explicitly want to throw away.
|
|
- Require typed confirmation before running destructive commands: `Type exactly: DISCARD <branch-name>`.
|
|
- After confirmation, remove the worktree and force-delete the unmerged branch with `git branch -D <branch-name>`; this cannot be undone from git alone once commits are unreachable.
|
|
|
|
### Example local-merge cleanup flow:
|
|
```bash
|
|
# From the primary working tree
|
|
git checkout <base-branch>
|
|
git merge <branch-name>
|
|
git worktree remove .worktrees/<feature-name>
|
|
git branch -d <branch-name> # optional cleanup when fully merged
|
|
```
|
|
|
|
### Completing multiple worktrees (independent PRs):
|
|
Complete and merge each worktree independently. If workstream-2 depends on workstream-1, merge workstream-1 first, then rebase workstream-2 before merging.
|
|
|
|
## GitHub PR Procedure
|
|
|
|
### Push and create PR:
|
|
```bash
|
|
# Push branch
|
|
git push -u origin <branch-name>
|
|
|
|
# Create PR with heredoc body
|
|
gh pr create --title "<title>" --body "$(cat <<'EOF'
|
|
## Summary
|
|
- <bullet 1>
|
|
- <bullet 2>
|
|
|
|
## Changes
|
|
- <file/area>: <what changed>
|
|
|
|
## Testing
|
|
- <how it was validated>
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
### Check CI status:
|
|
```bash
|
|
gh run list # List recent workflow runs
|
|
gh run view <run-id> # View specific run details
|
|
gh pr checks <pr-number> # Check statuses on a PR
|
|
```
|
|
|
|
### Issue operations:
|
|
```bash
|
|
gh issue list # List open issues
|
|
gh issue view <number> # View specific issue
|
|
gh issue comment <number> -b "<comment>" # Add comment
|
|
```
|
|
|
|
## Safety Rules
|
|
|
|
- **Never `git push --force` to `main`/`master`** unless the user explicitly confirms.
|
|
- **Never skip hooks** (`--no-verify`) unless the user explicitly requests it.
|
|
- **Never `git commit --amend`** unless: (1) explicitly requested OR pre-commit hook auto-modified files, (2) HEAD was created in this session, AND (3) commit has NOT been pushed to remote.
|
|
- If commit fails due to pre-commit hook, fix the issue and create a NEW commit.
|