🔗

ObsidianとZenn記事リポジトリをGit Submoduleで連携する実践ガイド(導入手順)

に公開

はじめに

私は普段、情報整理やアイデアメモにObsidianを使い、Zennで技術記事を公開しています。
それぞれ別々のGitリポジトリで管理しているのですが、ある時「Obsidianのノート群とZennの記事リポジトリを一つの親リポジトリ内で管理できたら便利だな」と感じ、Git Submoduleを使った連携に挑戦しました。

この記事では、私自身の経験をもとに、Obsidianを親リポジトリ、Zenn記事を子リポジトリとしてGit Submoduleで連携する具体的な方法と注意点を、実践的な視点で詳しく解説します。


なぜこの構成が必要だったのか?

まず、私がこの構成を選んだ理由からお話しします。

  • Obsidianは個人的なメモやドキュメント管理用
    MarkdownファイルをGit管理しつつ、日々のアイデアや学習記録を蓄積しています。
  • Zennは公開用の記事リポジトリ
    Markdownで書いた記事をZennに公開するためのリポジトリが別にあります。
  • 両者を完全に分離しているが、連携も取りたい
    Obsidianのノートは非公開でプライベートな内容が多く、Zennの記事は公開用なので履歴や管理を分けたい。
  • しかし作業効率のために、一つの親リポジトリ内で両方を扱いたい
    例えば、Obsidianで記事の下書きを書きつつ、そのままZennリポジトリに反映させられると便利。

このような背景から、親リポジトリとしてObsidianのノート群を管理し、その中にZennの記事リポジトリをGit Submoduleとして組み込む構成を採用しました。


なぜGit Submoduleを選んだのか?他の方法との比較

この構成を実現する方法は他にもありますが、私がGit Submoduleを選んだ理由は以下の通りです。

方法 メリット デメリット
普通にclone シンプル、初心者でも扱いやすい 親子関係がなく連携が面倒
モノレポ(単一リポジトリ) 管理が一元化できる 公開用と非公開用を分けにくい
Git Subtree 親リポジトリに子リポジトリを統合可能 操作が複雑、履歴管理が難しい
Git Submodule リポジトリの独立性を保ちつつ連携可能 初期設定や運用に慣れが必要

普通にcloneする場合

単純にZennリポジトリを別にcloneして作業しても良いのですが、Obsidianの親リポジトリからは独立しているため、ファイルの連携や同期が面倒です。例えば、ObsidianのノートからZenn記事に移行する際にファイルコピーや手動管理が必要になります。

workspace/ (git)
├── obsidian-notes/ (git)  # Obsidianリポジトリ
└── zenn-articles/ (git)   # 完全に別のリポジトリ

ルートで分離しているので、橋渡しは常に手作業になります。

モノレポ(単一リポジトリ)にまとめる場合

ObsidianノートとZenn記事を同じリポジトリに入れれば管理は楽ですが、公開用の記事とプライベートなノートが混在するため、プライベート情報が誤って公開されるリスクがあります。また、履歴も混ざってしまい管理が煩雑になります。

mono-repo/ (git)
├── obsidian/            # 個人メモ
└── zenn/                # 公開記事

ディレクトリは整理できても履歴や公開範囲の線引きが難しく、push ミスによる漏洩が怖い構造です。

Git Subtree

Git Subtreeは親リポジトリに子リポジトリを統合できる機能ですが、操作が複雑で履歴の管理も難しい印象でした。特に、Zennの記事を頻繁に更新する場合、履歴の分離が曖昧になるため避けました。

obsidian/ (git)
├── notes/
└── zenn_articles/       # subtree で統合。履歴は親側と混在

表面上は 1 つのツリーですが、外部リポジトリの履歴まで親コミットに混ざるため、更新頻度が高いと煩雑になります。

Git Submoduleの選択理由

Git Submoduleは、親リポジトリが子リポジトリの特定コミットを「参照」する形で連携します。
これにより、

  • 子リポジトリは独立して管理できる
  • 履歴も完全に分離される
  • 親リポジトリから子リポジトリのコミットを明示的に管理できる

というメリットがあります。
一方で初期設定や運用に少し癖があるため、慣れるまでは戸惑いますが、使いこなせば非常に便利です。


Git Submoduleとは何か?技術的な仕組み

Git Submoduleは、親リポジトリの中に別のGitリポジトリを「参照」する仕組みです。
具体的には、親リポジトリは子リポジトリの特定コミットのハッシュを記録し、そのコミットをチェックアウトする形になります。

  • 親リポジトリの.gitmodulesファイルに子リポジトリのURLとパスが記録される
  • 親リポジトリの特定コミットは、子リポジトリの特定コミットを指すポインタを持つ
  • 子リポジトリは親リポジトリとは独立したGit管理が可能

このため、親リポジトリをcloneしただけでは子リポジトリの内容は空ですが、git submodule update --init --recursiveコマンドで子リポジトリの内容を取得・同期できます。


具体的なディレクトリ構成例

私の環境では以下のような構成にしています。

obsidian/ (git)             # 親リポジトリ(Obsidianノート)
├── notes/                  # ObsidianのMarkdownノート群
│   ├── daily_note.md
│   └── project_idea.md
├── zenn_articles/ (git)    # 子リポジトリ(Zenn記事)をSubmoduleとして配置
│   ├── articles/
│   │   ├── article1.md
│   │   └── article2.md
│   └── README.md
└── .gitmodules             # Submodule設定ファイル
  • obsidian/が親リポジトリのルートです。
  • notes/はObsidianの個人ノート。
  • zenn_articles/がZenn用の記事リポジトリをSubmoduleとして配置しているディレクトリです。
  • .gitmodulesはSubmoduleの設定情報を管理するファイルです。

導入手順:実際にGit Submoduleを導入する

以下は私が実際に行った手順です。

1. 親リポジトリ(Obsidian)の準備

すでにObsidianのノート群をGit管理している場合は不要ですが、初めての場合は以下のようにします。

cd obsidian
git init
git add notes
git commit -m "Initial commit with Obsidian notes"

2. 子リポジトリ(Zenn記事)の準備

既にZenn用のリポジトリがある場合は、そのURLを控えます。
なければGitHubなどで空のリポジトリを作成してください。

例: https://github.com/username/zenn_articles.git

3. Submoduleとして追加

親リポジトリのルートで以下を実行します。

git submodule add https://github.com/username/zenn_articles.git zenn_articles
  • zenn_articlesは親リポジトリ内の配置ディレクトリ名です。
  • これで.gitmodulesが作成され、Submoduleが追加されます。

4. Submoduleの初期化と更新

git submodule update --init --recursive

このコマンドで子リポジトリの内容が取得されます。

5. 変更をコミットしてプッシュ

git add .gitmodules zenn_articles
git commit -m "Add Zenn articles as submodule"
git push origin main

実際に遭遇したトラブルと対処法

Git Submoduleは便利ですが、私も最初は何度かハマりました。よくあるトラブルと対処法を共有します。

既に存在するディレクトリにSubmoduleを追加しようとするとエラーになる

fatal: destination path 'zenn_articles' already exists and is not an empty directory.
  • 既にzenn_articlesディレクトリが存在している場合、Submodule追加時にエラーになります。
  • 対策としては、事前にディレクトリを空にするか、別名にリネーム・削除しましょう。
mv zenn_articles zenn_articles_backup
git submodule add https://github.com/username/zenn_articles.git zenn_articles

空のリポジトリにSubmoduleを追加した場合、clone時にファイルが取得されない

  • 子リポジトリが空のままだと、cloneしてもファイルが何もありません。
  • README.mdなど最低1ファイルは置くことを推奨します。

.git/modulesディレクトリの管理に注意

  • SubmoduleのGit情報は親リポジトリの.git/modules内に格納されます。
  • 手動でこのディレクトリを削除・移動するとSubmoduleが壊れることがあります。
  • Submoduleを削除するときは、git submodule deinitやgit rmを正しく使いましょう。

clone時にSubmoduleを含めて取得しないと中身が空になる

git clone https://github.com/username/obsidian.git

だけだとSubmoduleの中身は空です。必ず以下のようにします。

git clone --recurse-submodules https://github.com/username/obsidian.git

またはclone後に

git submodule update --init --recursive

を実行してください。


導入後の運用ルールとベストプラクティス

Submoduleは慣れるまで操作ミスによるトラブルが起きやすいので、以下の運用ルールを自分なりに決めています。

  • Submoduleの更新は親リポジトリから明示的に行う
    子リポジトリで記事を書いたら、親リポジトリに戻ってgit add zenn_articlesしてコミットする。
  • clone時は必ず--recurse-submodulesを使う
    チームメンバーにも周知しています。
  • 子リポジトリの管理は子リポジトリ内で完結させる
    例えばzenn_articles内でgit pushを忘れない。
  • Submoduleを削除・移動するときは慎重に
    git submodule deinitや.gitmodulesの編集を正しく行う。
  • READMEなどでSubmoduleの存在と操作方法を明記する
    チーム運用時の混乱を防げます。

この方法が向いている人・向いていない人

向いている人

  • ObsidianのノートとZennの記事を別々のリポジトリで管理したい人
  • 履歴の分離やプライバシーを重視したい人
  • Gitの基本操作に慣れていて、Submoduleの運用に抵抗がない人
  • 複数リポジトリを一つの親ディレクトリでまとめて管理したい人

向いていない人

  • Git操作に慣れていない初心者
  • 単純に記事とノートを一つのリポジトリで管理したい人
  • Submoduleの管理が面倒に感じる人

率直なメリット・デメリット

メリット デメリット
リポジトリの独立性を保てる 初期設定や運用に学習コストがかかる
履歴が完全に分離される Submoduleの更新を忘れると親リポジトリとズレる
親リポジトリから子リポジトリのコミットを明示的に管理できる clone時に--recurse-submodulesを忘れると中身が空になる
チームでの運用ルールを決めれば運用が安定する .git/modulesの管理を誤るとSubmoduleが壊れる

まとめ

Git Submoduleは一見ハードルが高いですが、Obsidianのノート群とZennの記事リポジトリを独立したまま一つの親リポジトリで管理したい場合に最適な手段です。

私自身、実際に導入してからは作業効率が上がり、履歴管理もスッキリしました。
ただし、Submodule特有のトラブルや運用ルールを把握しないと混乱するので、この記事を参考にしながら慎重に導入を検討してください。


この記事がGit Submodule導入の一助になれば幸いです。質問や改善点があればコメントで教えてください!

Discussion