ログ出力機能（verbose/debugモード）の追加

[devgamesan]

概要

現在の git-ssh-sync は基本的な進捗メッセージとエラーメッセージのみを出力しており、トラブルシューティッグ時に詳細な情報が不足しています。ログ出力機能（verbose/debugモード）を追加して、運用性とデバッグ効率を向上させます。

現状

あるもの:

• 基本的な進捗メッセージ（プロジェクト名、ブランチ名、同期方向）
• エラー発生時の詳細なエラーメッセージ
• Rich による整形された出力

ないもの:

• Gitコマンドの実行内容（git fetch, git push など）
• SSH接続の詳細
• 処理の進行状況の詳細
• デバッグレベルの情報（実行コマンド、戻り値、stderr など）

コード内では verbose 引数が用意されていますが、CLIから制御する方法がありません。

提案する実装

1. ログレベルの導入

Python の logging モジュール + Rich の統合で、以下のログレベルを導入：

レベル	用途	出力内容の例
DEBUG	実行されたGit/SSHコマンド、戻り値、stderr	Executing: git fetch origin
INFO	デフォルト。処理の進捗、成功メッセージ	Fetching from origin...
WARNING	回復可能な問題	Branch has diverged, manual merge required
ERROR	失敗、処理続行不可能	SSH connection failed

2. CLIオプションの追加

# 標準出力（INFOレベル）
git-ssh-sync pull myproject

# 詳細出力（DEBUGレベル）
git-ssh-sync pull myproject --verbose

# デバッグ出力（最も詳細）
git-ssh-sync pull myproject --debug

3. 実装構成

• git_ssh_sync/logger.py を新規作成
• Rich の Console と logging を統合
• グローバルな logger インスタンスを提供
• 既存の console.print() を適宜ログ出力に置き換え

利点

1. トラブルシューティングの効率化
   SSH接続エラー、Git操作失敗時の原因特定が容易になります。

2. doctor コマンドの強化
   診断情報の詳細化により、問題の早期発見が可能になります。

3. 複雑な同期フローの可視化
   pull/push/checkout の各ステップでの進捗確認ができます。

4. 運用上の可観測性向上
   ユーザーが何が起きているか理解しやすくなります。

関連ファイル

• src/git_ssh_sync/cli.py
• src/git_ssh_sync/git.py
• src/git_ssh_sync/ssh.py
• src/git_ssh_sync/sync.py
• src/git_ssh_sync/doctor.py

優先度

中程度 - 既存機能で問題ありませんが、運用性向上のため早期導入が望ましいです。

[devgamesan]

Plan for Issue #51: ログ出力機能（verbose/debugモード）の追加

1. 目的

git-ssh-sync に Python 標準 logging モジュールと RichHandler を統合し、以下の機能を実現する：

• ログレベルによる出力制御（DEBUG, INFO, WARNING, ERROR）
• CLI オプションによるログレベル制御（--verbose, --debug）
• Git/SSH コマンド実行の詳細ログ
• doctor コマンドのログ出力強化
• ログファイルへの出力

2. ベースブランチ

develop

3. 設計判断（ユーザー確認済み）

項目	選択	理由
ログファイル配置	デフォルトで保存（固定パス）	~/.cache/git-ssh-sync/logs/ に保存
コマンドログレベル	DEBUG レベル	トラブルシューティング用途
console.print()	維持しつつ logger でも記録	ユーザー体験を維持
doctor 強化範囲	基本的な進捗と結果のみ	実装コストと整合性

4. 実装方針

4.1 アーキテクチャ

CLI (cli.py)
  ↓ --verbose/--debug
logging_config.py (logger 設定)
  ↓
各モジュール (git.py, ssh.py, doctor.py, sync.py)
  ↓
RichHandler → Console / File

4.2 ログレベル体系

オプション	ログレベル	標準出力	ログファイル
デフォルト	WARNING	エラーと警告のみ	全レベル
--verbose, -v	INFO	進捗メッセージ	全レベル
--debug, -d	DEBUG	全デバッグ情報	全レベル

4.3 ログメッセージの言語

英語（既存コードベースとの整合性）

5. 実装ステップ

Step 1: logging_config.py の新規作成

ファイル: src/git_ssh_sync/logging_config.py

内容:

• RichHandler を使用した logger 設定
• setup_logging() 関数：ログレベル、ログファイルパスを受け取り、logger を設定
• グローバルな logger インスタンスの提供
• ログファイルのデフォルトパス：~/.cache/git-ssh-sync/logs/git-ssh-sync.log

依存: なし

---

Step 2: cli.py の修正

ファイル: src/git_ssh_sync/cli.py

変更内容:

1. Typer コールバックへのグローバルオプション追加:

   verbose: Annotated[bool, typer.Option("--verbose", "-v", help="詳細出力を有効にする")] = False
   debug: Annotated[bool, typer.Option("--debug", "-d", help="デバッグ出力を有効にする")] = False
   log_file: Annotated[str | None, typer.Option("--log-file", help="ログファイルの出力先")] = None

2. callback() 関数内で setup_logging() を呼び出し:

   if debug:
       level = "DEBUG"
   elif verbose:
       level = "INFO"
   else:
       level = "WARNING"
   
   setup_logging(level=level, log_file=log_file)

依存: Step 1

---

Step 3: git.py の修正

ファイル: src/git_ssh_sync/git.py

変更内容:

1. logging_config から logger をインポート
2. _run_command() 関数に以下のログ出力を追加:

   logger.debug(f"Executing: {format_command(command_tuple)}")
   logger.debug(f"Return code: {completed.returncode}")
   if completed.stderr:
       logger.debug(f"Stderr: {completed.stderr.strip()}")

3. 既存の verbose 引数による出力は維持（後方互換性）

依存: Step 1

---

Step 4: ssh.py の修正

ファイル: src/git_ssh_sync/ssh.py

変更内容:

1. logging_config から logger をインポート
2. run_ssh(), run_remote_git() 関数に以下のログ出力を追加:

   logger.debug(f"SSH command: {target} {remote_command}")
   logger.debug(f"Return code: {result.returncode}")
   if result.stderr:
       logger.debug(f"Stderr: {result.stderr.strip()}")

3. 既存の verbose 引数による出力は維持（後方互換性）

依存: Step 1

---

Step 5: sync.py の修正

ファイル: src/git_ssh_sync/sync.py

変更内容:

1. logging_config から logger をインポート
2. 既存の console.print() を維持しつつ、以下の logger 呼び出しを追加:

   logger.info(f"Pulling project '{project}' branch '{selected_branch}'")
   logger.info(f"Pushing project '{project}' branch '{selected_branch}'")
   logger.info(f"Checking out branch '{branch}' for project '{project}'")

依存: Step 1

---

Step 6: doctor.py の修正

ファイル: src/git_ssh_sync/doctor.py

変更内容:

1. logging_config から logger をインポート
2. 基本的な進捗メッセージをログ出力:

   logger.info("Running local command checks...")
   logger.info("Checking gateway repository...")
   logger.info("Checking SSH connection...")
   logger.info("Checking development environment...")

3. エラー発生時の詳細ログ:

   logger.error(f"Local command check failed: {check.message}")
   logger.debug(f"Environment: {check.environment}")
   logger.debug(f"Next action: {check.next_action}")

依存: Step 1

---

Step 7: テストの実装

ファイル: tests/test_logging_config.py（新規）

内容:

• setup_logging() の単体テスト
• ログレベル設定のテスト
• ログファイル出力のテスト

ファイル: 既存テストの修正

• tests/test_git.py: verbose 出力の検証方法を調整
• tests/test_cli.py: 新しい CLI オプションのテスト追加

---

Step 8: ドキュメントの更新

ファイル: README.md

変更内容:

• --verbose, --debug, --log-file オプションの説明追加
• ログ出力の使用例追加

ファイル: CLAUDE.md（必要に応じて）

変更内容:

• ログ機能に関する開発者向けドキュメント追加

---

6. 重要ファイル

実装において最も重要な5つのファイル：

1. src/git_ssh_sync/logging_config.py - 新規作成、logging 基盤
2. src/git_ssh_sync/cli.py - CLI オプション追加、ログ統合
3. src/git_ssh_sync/git.py - Git コマンド実行のログ出力
4. src/git_ssh_sync/ssh.py - SSH コマンド実行のログ出力
5. src/git_ssh_sync/doctor.py - doctor コマンドのログ強化

---

7. 後方互換性

✅ 互換性が保たれる点

• 既存の console.print() は維持される
• 新しい CLI オプションはデフォルトで無効
• 既存の API は変更なし

⚠️ 注意が必要な点

• 既存テストの一部修正が必要（verbose 出力の検証方法）
• ログファイルがデフォルトで保存されるようになる

---

8. テスト方針

8.1 単体テスト

• logging_config.py: ログレベル設定、ログファイル出力のテスト
• CLI オプション: --verbose, --debug, --log-file のテスト

8.2 統合テスト

• git.py, ssh.py: ログ出力が正しく記録されるか
• doctor.py: 進捗メッセージが正しくログ出力されるか

8.3 手動テスト

# デフォルト（WARNING 以上のみ）
git-ssh-sync pull myproject

# INFO レベル（進捗メッセージ）
git-ssh-sync pull myproject --verbose

# DEBUG レベル（全デバッグ情報）
git-ssh-sync pull myproject --debug

# ログファイル指定
git-ssh-sync pull myproject --verbose --log-file /tmp/my-sync.log

# doctor コマンド
git-ssh-sync doctor myproject --verbose

---

9. 想定される影響範囲

変更対象ファイル

• 新規作成: src/git_ssh_sync/logging_config.py, tests/test_logging_config.py
• 修正: src/git_ssh_sync/cli.py, src/git_ssh_sync/git.py, src/git_ssh_sync/ssh.py, src/git_ssh_sync/sync.py, src/git_ssh_sync/doctor.py
• テスト修正: tests/test_git.py, tests/test_cli.py
• ドキュメント: README.md

ユーザーへの影響

• 新しい CLI オプションが利用可能になる
• ログファイルがデフォルトで ~/.cache/git-ssh-sync/logs/ に保存される
• 運用性とトラブルシューティング効率が向上

---

10. 確認したい点

全ての設計判断点はユーザー確認済みです。

[devgamesan]

Implementation completed! 🎉

Pull Request #54 has been created and all CI checks have passed.

What's Implemented

• ✅ Python logging module integration with RichHandler
• ✅ CLI options: , ,
• ✅ Detailed logging for Git/SSH command execution
• ✅ Info logging for pull/push/checkout operations
• ✅ Enhanced logging for doctor command
• ✅ Automatic log file creation at ~/.cache/git-ssh-sync/logs/git-ssh-sync.log
• ✅ Comprehensive test coverage (87 tests passing)
• ✅ Documentation updates in README.md and README.ja.md

Test Results

uv run pytest
# 87 passed in 0.28s

CI Status

✅ All GitHub Actions checks passed

Usage

# Verbose output
git-ssh-sync pull myproject --verbose

# Debug output
git-ssh-sync pull myproject --debug

# Custom log file
git-ssh-sync push myproject --log-file /tmp/sync.log

# Doctor with debug info
git-ssh-sync doctor myproject --debug

Please review PR #54 for detailed changes.