Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

`completion install zsh` writes `~/.zshrc` when `$ZDOTDIR` is set, so zsh never loads the completions

オープン 初心者向け
  • 何か問題がありますか？
#2,138 コメント 0 件 リアクション 1 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

@clay-good がすでに取り組んでいます。

2026年10月29日 から。

  • #2172 @clay-good による — オープン

評価

難易度
2/5
見積もり時間
1〜3時間
初心者へのやさしさ
75/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
typescript, zsh
領域
cli

調査の方向性

src/core/completions/installers/zsh-installer.tsを読み、特にgetZshrcPath()と、それを使用するインストール、アンインストール、手動手順の各パスを確認してください。インストーラーのテストを確認し、一時的なHOMEとZDOTDIRを使って再現してください。インストールとアンインストールが${ZDOTDIR:-$HOME}/.zshrcを対象とし、そのパスを報告し、ZDOTDIRが設定されていない場合は既存のfallbackが維持されれば完了です。

索引モデルが issue の本文から書いたものです。

説明

What you were trying to do

I was setting up tab completion for OpenSpec in zsh. My zsh config lives in ~/.config/zsh: ~/.zshenv exports ZDOTDIR="$HOME/.config/zsh".

This is a common XDG-style layout. It is also the default in Home Manager when xdg.enable is on and home.stateVersion is 26.05 or later: programs.zsh.dotDir defaults to ~/.config/zsh and is exported as ZDOTDIR. So new Home Manager setups with XDG enabled are affected too.

What happened
$ openspec completion install zsh
✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

The installer created a new ~/.zshrc containing the # OPENSPEC:START … # OPENSPEC:END block. My real config, $ZDOTDIR/.zshrc, was not touched. zsh only reads ~/.zshrc when ZDOTDIR is unset (zsh manual: Startup/Shutdown Files). So the block is never loaded, _openspec never gets on fpath, and completion silently doesn't work even though the install reported success.

openspec completion uninstall zsh has the same problem: it only looks in ~/.zshrc.

What you expected instead

The block goes into the file zsh actually reads, ${ZDOTDIR:-$HOME}/.zshrc. Uninstall removes it from the same file, and the messages name that file.

Minimal steps to reproduce

These steps use a throwaway HOME, so they don't touch your real config:

TMPHOME=$(mktemp -d)
mkdir -p "$TMPHOME/.config/zsh"
echo '# my zshrc' > "$TMPHOME/.config/zsh/.zshrc"

HOME="$TMPHOME" ZDOTDIR="$TMPHOME/.config/zsh" openspec completion install zsh

ls -A "$TMPHOME"                  # a new .zshrc appears in HOME
cat "$TMPHOME/.config/zsh/.zshrc" # still just "# my zshrc", no OPENSPEC block
HOME="$TMPHOME" ZDOTDIR="$TMPHOME/.config/zsh" zsh -i -c 'whence -v _openspec'
# _openspec not found

With the fix described below, the last command prints _openspec is an autoload shell function from …/.zsh/completions/_openspec.

OpenSpec version

1.14.3 (also reproduces on main at c04f30e5)

Coding agent and model

None. This is plain CLI usage.

OS and Node version

macOS 26 (Darwin 25.5.0, arm64), zsh 5.9, Node 24.21.0

Where it comes from, and an offer to fix it

getZshrcPath() in src/core/completions/installers/zsh-installer.ts builds the path from $HOME only. Install, uninstall and the manual instructions all go through it.

I have a small fix with regression tests:

  • It resolves the path from $ZDOTDIR and falls back to $HOME. Output is identical when ZDOTDIR is unset.
  • The new tests fail on main and pass with the change. The full suite, tsc and lint are green.

I'd be glad to open a PR if you'd like me to.

A few things I checked or wasn't sure about:

  • IDE terminals. VS Code's zsh shell integration points ZDOTDIR at its own directory during startup, then restores the user's value (USER_ZDOTDIR) before the prompt. So a command typed in the terminal sees the right ZDOTDIR.
  • Read-only .zshrc. Under Home Manager, $ZDOTDIR/.zshrc is usually a read-only symlink into the Nix store. With the fix, the installer's existing write check catches that: it leaves the file alone and prints the manual instructions for the correct path. Today it reports "configured successfully" and drops a stray ~/.zshrc instead.
  • Script location. I kept the completion script itself in ~/.zsh/completions to keep the change small. People who set ZDOTDIR often prefer nothing new in $HOME, so I can move it under $ZDOTDIR if you prefer.
  • The spec. The cli-completion spec names ~/.zshrc literally. If you'd rather update the spec wording too, I'm happy to follow the feature flow.
  • Tests. The installer tests would also need to clear ZDOTDIR the way they already clear ZSH. Otherwise, on a machine with ZDOTDIR set, the suite would edit the developer's real .zshrc once the fix lands.

I found this while reading the installer code with Claude Code (Claude Opus 5.5), which also ran the reproduction above on my machine. I reviewed the report and the fix.

主要言語
TypeScript
スター
73k
フォーク
5k
平均マージ
2日 12時間
マージ済み PR（30日）
54

環境構築

Codespaces で開く

このプロジェクトの開発コンテナを、あなたの GitHub アカウントでブラウザ上に起動します。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

Fission-AI/OpenSpec のほかの issue

Fission-AI/OpenSpec の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。