Skip to content

feat: add .gitkeep files to preserve empty directories (#269) #282

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yha9806 wants to merge 5 commits into
base: main
Choose a base branch
from
Open

feat: add .gitkeep files to preserve empty directories (#269) #282

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a359909
feat: add .gitkeep files to preserve empty directories (#269)
yha9806 Nov 5, 2025
90596db
chore: archive add-gitkeep-empty-folders change
yha9806 Nov 5, 2025
2f715d1
fix: change prepare to postinstall for npm install from git
yha9806 Nov 6, 2025
a046536
feat: commit dist directory for npm install from git
yha9806 Nov 6, 2025
ca78a3b
Merge main: resolve package.json conflict
yha9806 Nov 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions openspec/changes/archive/2025-11-05-add-gitkeep-empty-folders/proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Add .gitkeep Files to Empty Folders

## Why

Git does not track empty directories. When `openspec init` creates the directory structure with empty `specs/`, `changes/`, and `changes/archive/` folders, these directories disappear after a commit if no files exist in them.

This causes workflow issues:
- After cloning a fresh repository, running `openspec list` fails because the expected directories don't exist
- New team members encounter errors when trying to use OpenSpec commands
- Users must manually recreate directories or remember to add placeholder files

## What Changes

Modify the `openspec init` command to create `.gitkeep` files in the three empty directories that need to persist in Git:
- `openspec/specs/`
- `openspec/changes/`
- `openspec/changes/archive/`

The `.gitkeep` file is a widely-used convention to force Git to track empty directories. It's an empty file (or a file with a simple comment) that ensures the directory structure is preserved across clones.

## Impact

**Users Affected**: All users who run `openspec init`

**Breaking Changes**: None

**Migration Required**: No - existing projects work as-is, but will benefit from running `openspec init` again in extend mode to add .gitkeep files

**Dependencies**: None

**Timeline**: Quick fix - can be completed in one implementation session
34 changes: 34 additions & 0 deletions ...pec/changes/archive/2025-11-05-add-gitkeep-empty-folders/specs/cli-init/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# CLI Init Specification Changes

## MODIFIED Requirements

### Requirement: Directory Creation
The command SHALL create the complete OpenSpec directory structure with all required directories and files, including `.gitkeep` files to ensure empty directories are tracked by Git.

#### Scenario: Creating OpenSpec structure
- **WHEN** `openspec init` is executed
- **THEN** create the following directory structure:
```
openspec/
├── project.md
├── AGENTS.md
├── specs/
│ └── .gitkeep
└── changes/
├── .gitkeep
└── archive/
└── .gitkeep
```
- **AND** each `.gitkeep` file SHALL be an empty file that forces Git to track the directory

#### Scenario: Preserving empty directories in Git
- **WHEN** a user commits and pushes the OpenSpec structure to a Git repository
- **THEN** the `specs/`, `changes/`, and `changes/archive/` directories SHALL persist in the repository
- **AND** after cloning the repository, all three directories SHALL exist
- **AND** `openspec list` SHALL work immediately without manual directory creation

#### Scenario: Working with fresh clones
- **GIVEN** a repository initialized with OpenSpec
- **WHEN** a new team member clones the repository
- **THEN** running `openspec list` SHALL succeed without errors
- **AND** no manual directory creation SHALL be required
19 changes: 19 additions & 0 deletions openspec/changes/archive/2025-11-05-add-gitkeep-empty-folders/tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Tasks

## Implementation
- [ ] Modify `src/core/init.ts` `createDirectoryStructure` method to create `.gitkeep` files in empty directories
- [ ] Add `.gitkeep` file creation for `openspec/specs/`
- [ ] Add `.gitkeep` file creation for `openspec/changes/`
- [ ] Add `.gitkeep` file creation for `openspec/changes/archive/`

## Testing
- [ ] Add test case verifying `.gitkeep` exists in `specs/` after init
- [ ] Add test case verifying `.gitkeep` exists in `changes/` after init
- [ ] Add test case verifying `.gitkeep` exists in `changes/archive/` after init
- [ ] Run existing test suite to ensure no regressions

## Validation
- [ ] Run `openspec validate add-gitkeep-empty-folders --strict` and resolve all issues
- [ ] Test `openspec init` manually in a fresh directory
- [ ] Verify Git tracks the empty directories with `.gitkeep` files
- [ ] Test `openspec list` works immediately after clone in a new repository
Comment on lines +1 to +19
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Mark completed tasks with [x] checkboxes.

Based on the PR description, all implementation, testing, and validation work is complete:

  • Implementation: src/core/init.ts modified to create .gitkeep files
  • Testing: Three new tests added and passing in test/core/init.test.ts
  • Validation: Manual verification confirmed, proposal validated with --strict mode

All tasks should be marked as completed using - [x] syntax to accurately reflect the work status.

As per coding guidelines

Apply this diff to mark all completed tasks:

 ## Implementation
-- [ ] Modify `src/core/init.ts` `createDirectoryStructure` method to create `.gitkeep` files in empty directories
-- [ ] Add `.gitkeep` file creation for `openspec/specs/`
-- [ ] Add `.gitkeep` file creation for `openspec/changes/`
-- [ ] Add `.gitkeep` file creation for `openspec/changes/archive/`
+- [x] Modify `src/core/init.ts` `createDirectoryStructure` method to create `.gitkeep` files in empty directories
+- [x] Add `.gitkeep` file creation for `openspec/specs/`
+- [x] Add `.gitkeep` file creation for `openspec/changes/`
+- [x] Add `.gitkeep` file creation for `openspec/changes/archive/`
 
 ## Testing
-- [ ] Add test case verifying `.gitkeep` exists in `specs/` after init
-- [ ] Add test case verifying `.gitkeep` exists in `changes/` after init
-- [ ] Add test case verifying `.gitkeep` exists in `changes/archive/` after init
-- [ ] Run existing test suite to ensure no regressions
+- [x] Add test case verifying `.gitkeep` exists in `specs/` after init
+- [x] Add test case verifying `.gitkeep` exists in `changes/` after init
+- [x] Add test case verifying `.gitkeep` exists in `changes/archive/` after init
+- [x] Run existing test suite to ensure no regressions
 
 ## Validation
-- [ ] Run `openspec validate add-gitkeep-empty-folders --strict` and resolve all issues
-- [ ] Test `openspec init` manually in a fresh directory
-- [ ] Verify Git tracks the empty directories with `.gitkeep` files
-- [ ] Test `openspec list` works immediately after clone in a new repository
+- [x] Run `openspec validate add-gitkeep-empty-folders --strict` and resolve all issues
+- [x] Test `openspec init` manually in a fresh directory
+- [x] Verify Git tracks the empty directories with `.gitkeep` files
+- [x] Test `openspec list` works immediately after clone in a new repository
🤖 Prompt for AI Agents 
In openspec/changes/add-gitkeep-empty-folders/tasks.md around lines 1 to 19, the
checklist still shows unfinished tasks; update the file by changing each "- [ ]"
checkbox for the Implementation, Testing, and Validation items to "- [x]" to
mark them completed, ensuring spacing and markdown syntax remain intact so the
file correctly reflects that implementation, tests, and validation are done.

18 changes: 17 additions & 1 deletion openspec/specs/cli-init/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The command SHALL display progress indicators during initialization to provide c
- Then success: "✔ AI tools configured"

### Requirement: Directory Creation
The command SHALL create the complete OpenSpec directory structure with all required directories and files.
The command SHALL create the complete OpenSpec directory structure with all required directories and files, including `.gitkeep` files to ensure empty directories are tracked by Git.

#### Scenario: Creating OpenSpec structure
- **WHEN** `openspec init` is executed
Expand All @@ -29,9 +29,25 @@ openspec/
├── project.md
├── AGENTS.md
├── specs/
│ └── .gitkeep
└── changes/
├── .gitkeep
└── archive/
└── .gitkeep
```
- **AND** each `.gitkeep` file SHALL be an empty file that forces Git to track the directory

#### Scenario: Preserving empty directories in Git
- **WHEN** a user commits and pushes the OpenSpec structure to a Git repository
- **THEN** the `specs/`, `changes/`, and `changes/archive/` directories SHALL persist in the repository
- **AND** after cloning the repository, all three directories SHALL exist
- **AND** `openspec list` SHALL work immediately without manual directory creation

#### Scenario: Working with fresh clones
- **GIVEN** a repository initialized with OpenSpec
- **WHEN** a new team member clones the repository
- **THEN** running `openspec list` SHALL succeed without errors
- **AND** no manual directory creation SHALL be required

### Requirement: File Generation
The command SHALL generate required template files with appropriate content for immediate use.
Expand Down
3 changes: 2 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@
"test:watch": "vitest",
"test:ui": "vitest --ui",
"test:coverage": "vitest --coverage",
"prepare": "pnpm run build",
"preinstall": "echo Installing dependencies...",
"postinstall": "pnpm run build",
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Moving build from prepare to postinstall may negatively impact development workflows.

The change from prepare: pnpm run build to postinstall: pnpm run build is significant:

  • prepare runs once per git dependency and is the standard hook for build steps (suitable for CI and git-based installs).
  • postinstall runs on every pnpm install invocation, which would trigger a full build each time dependencies are reinstalled during development.

This could slow down common development workflows (e.g., pnpm install, switching branches, or updating dependencies). Consider whether this behavioral change is necessary or if prepare should be retained.

I'll verify the claims in this review comment by checking the npm/pnpm lifecycle hook behavior and examining the repository for context.

🏁 Script executed:

#!/bin/bash
# Check git history or current package.json for the change from prepare to postinstall
git log -p --all -- package.json | grep -A5 -B5 "prepare\|postinstall" | head -80

Length of output: 59

🌐 Web query:

pnpm prepare vs postinstall lifecycle hooks behavior when to use

💡 Result:

Short answer

  • prepare: meant to build or prepare a package before it is packed/published and when installing from a Git repository (devDependencies are installed for git installs). Use it for producing artifacts that must exist in the published package (e.g. transpile/build before pack/publish or when consumers install from git). [1][2]
  • postinstall: runs after a package is installed into node_modules. It's appropriate for runtime setup that must run on every install of an installed package (e.g. install native binaries, run post‑install hooks), but is not guaranteed to run in all package manager configurations. [1]

pnpm-specific behavior (important)

  • pnpm caches/isolates side effects and (since pnpm v10) blocks dependency lifecycle scripts by default — postinstall (and other install hooks) of dependencies may not run unless explicitly allowed via pnpm configuration (onlyBuiltDependencies / neverBuiltDependencies / side‑effects settings). Because of this, relying on postinstall for producing published package artifacts or workspace rebuild triggers is fragile with pnpm. [3][4]

When to prefer which

  • Use prepare when:
    • You need built files included in the published tarball (prepare runs before pack/publish and for git installs).
    • You want consistent behavior across npm/pnpm/Yarn for source (git) installs.
  • Use postinstall when:
    • You need a script to run on end-user installs for runtime setup and you accept that some managers (or pnpm default settings) may block/ cache those scripts unless configured to allow them.
  • With pnpm, prefer prepare for build/artifact generation and avoid relying on postinstall for essential build steps; if you must use postinstall for a dependency, configure pnpm to allow that dependency’s scripts. [1][3][4]

Sources

  • npm lifecycle docs (prepare vs postinstall behavior). [1]
  • pnpm v10 lifecycle-scripts default blocking (security/change in behavior). [3]
  • pnpm package.json / onlyBuiltDependencies / neverBuiltDependencies docs. [4]
  • Example community migration away from postinstall to prepare (SvelteKit PR). [2]

Let me check the current package.json and repository context more carefully:

🏁 Script executed:

#!/bin/bash
# View the current package.json around the scripts section
cat package.json | grep -A20 '"scripts"'

Length of output: 777

🏁 Script executed:

#!/bin/bash
# Check if there's a .npmrc or pnpm-workspace.yaml indicating workspace/published package
ls -la | grep -E "npmrc|pnpm-workspace|package-lock"
# Also check git status to see if package.json was changed in this PR
git status package.json 2>/dev/null || echo "Git status not available"
# Try a simpler git diff
git diff HEAD~ package.json 2>/dev/null | head -50 || echo "Git diff not available"

Length of output: 564

Revert postinstall to prepare for git-based installs and CI workflows.

The change from prepare to postinstall is confirmed in the git diff and will negatively impact development workflows. prepare runs once per git dependency and is the standard hook for build steps, while postinstall runs on every pnpm install invocation. For this published package (which has prepublishOnly and release scripts), prepare is the correct lifecycle hook. Switching to postinstall will trigger unnecessary rebuilds on every install, slowing common development workflows like dependency updates and branch switching. The package already handles pre-publish builds via prepublishOnly, making postinstall redundant and inappropriate here.

Restore prepare: pnpm run build to align with npm best practices for published packages.

🤖 Prompt for AI Agents 
In package.json around line 48, restore the lifecycle hook from "postinstall":
"pnpm run build" back to "prepare": "pnpm run build" because prepare runs once
for git-based installs and is the correct hook for published packages; change
the script key to "prepare" with the existing build command so CI and developer
installs don't trigger rebuilds on every pnpm install.

"prepublishOnly": "pnpm run build",
"check:pack-version": "node scripts/pack-version-check.mjs",
"release": "pnpm run release:ci",
Expand Down
11 changes: 11 additions & 0 deletions src/core/init.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -716,6 +716,17 @@ export class InitCommand {
for (const dir of directories) {
await FileSystemUtils.createDirectory(dir);
}

// Create .gitkeep files in empty directories to ensure Git tracks them
const emptyDirectories = [
path.join(openspecPath, 'specs', '.gitkeep'),
Copy link
Contributor

@TabishB TabishB Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if there's a different way to solve this. This makes sense but I'm a reluctant to add in .gitkeep files that users will most likely forget to delete.

Maybe we can look into making init self-healing or finding another way to always ensure we re-create these folders if these are ever missing.

path.join(openspecPath, 'changes', '.gitkeep'),
path.join(openspecPath, 'changes', 'archive', '.gitkeep'),
];

for (const gitkeepPath of emptyDirectories) {
await FileSystemUtils.writeFile(gitkeepPath, '');
}
}

private async generateFiles(
Expand Down
26 changes: 26 additions & 0 deletions test/core/init.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,32 @@ describe('InitCommand', () => {
).toBe(true);
});

it('should create .gitkeep files in empty directories', async () => {
queueSelections('claude', DONE);

await initCommand.execute(testDir);

const openspecPath = path.join(testDir, 'openspec');
expect(await fileExists(path.join(openspecPath, 'specs', '.gitkeep'))).toBe(true);
expect(await fileExists(path.join(openspecPath, 'changes', '.gitkeep'))).toBe(true);
expect(await fileExists(path.join(openspecPath, 'changes', 'archive', '.gitkeep'))).toBe(true);
});

it('should create empty .gitkeep files', async () => {
queueSelections('claude', DONE);

await initCommand.execute(testDir);

const openspecPath = path.join(testDir, 'openspec');
const specsGitkeep = await fs.readFile(path.join(openspecPath, 'specs', '.gitkeep'), 'utf-8');
const changesGitkeep = await fs.readFile(path.join(openspecPath, 'changes', '.gitkeep'), 'utf-8');
const archiveGitkeep = await fs.readFile(path.join(openspecPath, 'changes', 'archive', '.gitkeep'), 'utf-8');

expect(specsGitkeep).toBe('');
expect(changesGitkeep).toBe('');
expect(archiveGitkeep).toBe('');
});

it('should create AGENTS.md and project.md', async () => {
queueSelections('claude', DONE);

Expand Down