如何添加 git repo 作为其自身的子模块？ （或者：如何以编程方式生成 GitHub Pages？）

Question

我想开始为我的项目网站使用 GitHub Pages。这仅需要存储库中名为 gh-pages 的分支（子树），并提供其内容。问题是网站的一部分（手册、更改日志、下载页面...）是由构建系统自动生成的，所以我想找到将这些更改提交到 gh-pages 的最佳方法。 code> 分支，而主存储库保留在 master （或任何地方）。

要提交到 gh-pages 分支，我可以编写一个脚本，将存储库克隆到临时目录中，进行修改，提交它们，然后将它们推回主存储库。但这听起来像是一个容易出错的过程，所以我希望有一种更简单的方法。

一位朋友建议我可以将 gh-pages 分支作为子模块添加到主存储库中。我做了一个小实验，但不太有效：

$ git init main
Initialized empty Git repository in /tmp/main/.git/
$ cd main
$ touch main.txt
$ git add .
$ git commit -m'Initial commit in main branch.'
[master (root-commit) 1c52a4e] Initial commit in main branch.
 0 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 main.txt
$ git symbolic-ref HEAD refs/heads/gh-pages
$ rm .git/index
$ git clean -fdx
Removing main.txt
$ touch index.html
$ git add .
$ git commit -m'Initial commit in website branch.'
[gh-pages (root-commit) 94b10f2] Initial commit in website branch.
 0 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 index.html
$ git checkout master
Switched to branch 'master'
$ git submodule add -b gh-pages . gh-pages
repo URL: '.' must be absolute or begin with ./|../
$ git submodule add -b gh-pages ./ gh-pages
remote (origin) does not have a url defined in .git/config

我对子模块很陌生；当然，我已经读过一些书，但我不明白这种行为。为什么需要 origin 遥控器？理想情况下，我希望子模块始终引用它所在的存储库，因此它不应该引用 origin 或任何其他遥控器。如果有人克隆存储库并运行 git submodule init ； git submodule update，理想情况下它应该从新克隆的存储库中提取。

是否可以添加存储库作为其自身的子模块？值得吗？有什么我需要注意的陷阱吗？有更好的方法来实现我想要的吗？

Answer 1

在这种情况下，行为似乎是 git 试图将原始存储库的起源设置为子模块的起源。 git submodule 手册页证实了这一点，其中显示[我的重点]：

<存储库>;是新子模块的原始存储库的 URL。这可以是绝对 URL，或者（如果以 ./ 或 ../ 开头）相对于超级项目的原始存储库的位置。

对我来说似乎不错的解决方法是执行以下操作：

# Define origin to be the absolute path to this repository - we'll remove
# this later:
$ cd /tmp/main/
$ git remote add origin /tmp/main/

# Now add the submodule:
$ git submodule add -b gh-pages ./ gh-pages
Initialized empty Git repository in /tmp/main/gh-pages/.git/
Branch gh-pages set up to track remote branch gh-pages from origin.

# Now .gitmodules looks sensible:
$ cat .gitmodules 
[submodule "gh-pages"]
    path = gh-pages
    url = ./

# However, the origin for the submodule isn't what we want:
$ cd gh-pages
$ git remote -v
origin  /tmp/main/ (fetch)
origin  /tmp/main/ (push)

# So remove it and add the right origin (just ".."):
$ git remote rm origin
$ git remote add origin ..

# Change back to the main repository and commit:
$ cd ..
$ git commit -m "Added the gh-pages branch as a submodule of this repository"
[master 6849d53] Added the gh-pages branch as a submodule of this repository
 2 files changed, 4 insertions(+), 0 deletions(-)
 create mode 100644 .gitmodules
 create mode 160000 gh-pages

这似乎工作正常 - 如果我更改为另一个目录并执行以下操作：

$ cd /var/tmp
$ git clone --recursive /tmp/main/

...子模块已正确更新和初始化。 （更新：尽管正如您在下面的评论中指出的那样，子模块中的 origin 将设置为您克隆的 URL，而不是 ..）

至于这是否是一个好主意：我曾经参与过一个项目，该项目过去使用了类似的设置，但后来放弃了它。然而，这样做的原因是（a）主存储库中的替代分支非常巨大，即使对于不需要子模块的人来说，存储库也会变得臃肿；（b）它导致了混乱对于那些不确定发生了什么的人。

然而，对于您的用例，我认为这是一个相当简洁的解决方案:)

Answer 2

使用 Git 子模块 生成 GitHub Pages就是使用Git Subtree 合并策略。 有很多网站 展示了如何执行此操作 和 争论 /2012/04/28/why-your-company-shouldnt-use-git-submodules/" rel="nofollow noreferrer">子模块与子树合并。甚至还有一个新的 git-subtree 命令 可能会也可能不会随您的 Git 版本一起安装。 IMO 您真正需要了解的唯一事情就是这两点。

• 子树合并策略在合并时匹配两个存储库/分支的树（git 的目录树概念），以便无关的文件和分支被合并。文件夹不会被合并，只会合并相关的树。这正是您想要的 Github Pages，因为它位于一个孤立分支中，它与您的主分支具有完全不同的树。

• 一般来说，子树合并具有简化的工作流程，并且比子模块丢失修订的机会更少。

以下是如何在 Github Pages 中使用子树合并策略：

1. 如果您在本地或远程存储库中没有名为 gh-pages 的分支，则使用 -- 创建一个分支orphan 标志，使其为空。 Github 有手动创建 Github 页面的说明。。如果您使用自动页面生成，那么您可以可以跳过此步骤，但将本文其他地方的本地分支 gh-pages 替换为远程分支 origin/gh-pages，否则本地获取远程分支。 注意：您可以跳过创建 .nojekyll 文件，但必须从孤立分支中删除所有文件并提交它，否则不会创建该文件。

   <前><代码>。 $ (master) git checkout --orphan gh-pages
   。 $ (gh-pages) git rm -rf.
   。 $（gh-pages）回显>> .nojekyll
   。 $ (gh-pages) git add .nojekyll
   。 $ (gh-pages) git commit -m "创建 github 页面，忽略 jekyll"

   如果您的主分支的子树中已经有文档，您可以将其拉入并使用 git-read-tree 现在，但你必须了解树。想必您可以首先使用 git-write-tree 它将输出当前索引中由 --prefix 标志命名的树的 SHA-1。然后使用 -u 标志通过主分支的更改来更新 gh-pages 分支并提交更改。

   <前><代码>。 $ (master) git write-tree --prefix=docs/_build/html master
   abcdefghijklmnopqrstuvwxyz1234567890abcd
   。 $ (主) git checkout gh-pages
   。 $ (gh-pages) git 读取树 abcdefghijklmnopqrstuvwxyz1234567890abcd
   。 $ (gh-pages) git commit -m "从主文档更新 gh-pages html"

2. 签出 master 并使用 git-read-tree 将 gh-pages 分支的工作副本复制到 中的某个路径>master，EG：./docs/_build/html。如果合并成功，-u 标志会更新工作副本中的文件。如果 gh-pages 分支中没有您想要合并回 master 的文件，则此步骤可能是不必要的，但如果有，它可能有助于子树合并策略确定您在哪棵树中文件是。与往常一样，Git 不会让您合并已存在的文件或存储库中存在未提交的更改。如果您想将使用自动页面生成创建的页面合并回不同的树，例如 master 分支中的 docs，请使用此步骤。不要忘记将新文件提交到您的 master 分支。

   <前><代码>。 $（gh-pages）git checkout master
   。 $ (master) git read-tree --prefix=docs/_build/html -u gh-pages
   。 $ (master) git commit -m "将 gh-pages 树读入 master at ./docs/_build/html"

3. 通过您喜欢的任何方式更改您的文档并生成一些 html。 EG：Jekyll，Pelican 或 Sphinx< /a>. 注意：如果您不使用 Jekyll，并且需要下划线文件夹/文件，例如：*.css 或 *.js 文件，然后确保添加一个名为 .nojekyll 的文件到您的 html 目录。

   ./docs $ (master) sphinx-quickstart
   ...
   ./docs $ (master) 制作 html
   ./docs/_build/html $(master) echo >>> .nojekyll
   

4. 使用子树合并策略（-s subtree）更新您的 gh-pages 分支，压缩所有提交，以便您的Github 页面历史记录未被污染 (--squash)，并等到合并后提交，以便您可以查看 (--no-commit)。注意：当您签出 gh-pages 分支时，文件和文件将被删除。主文件夹中的文件夹可能会保持为未跟踪，只需忽略它们并专注于索引中实际的内容即可。注意：如果 master 中有任何未提交或未存储的修改，Git 将不会检出 gh-pages。

   <前><代码>。 $ (主) git checkout origin/gh-pages
   。 $ (gh-pages) git merge --no-commit --squash -s 子树主控

   Git 使用子树合并策略对要合并的树进行最佳猜测，但是，如果没有太多内容，你最好明确告诉 Git 要合并哪棵树。

   <前><代码>。 $ (gh-pages) git merge --no-commit --squash -s recursive -Xsubtree=docs/_build/html/ master

5. 检查您的更改并提交。合并会为您生成一条消息，其中包含正在合并的所有提交的简短日志。

   <前><代码>。 $ (gh-pages) git 提交

6. 推送您的 gh-pages 分支会部署您的 GitHub Pages 网站。

   <前><代码>。 $ (gh-pages) git Push 原点 gh-pages

7. 返回master。

   <前><代码>。 $（gh-pages）git checkout master

8. 如果您出于某种原因需要从 gh-pages 中提取更改，请以相反的方向使用子树合并策略。 EG git merge --squash --no-commit -s subtree gh-pages

9. 要对与树匹配的两个分支进行比较，请使用 diff-tree

   <前><代码>。 $ git diff-tree master gh-pages git diff-tree master gh-pages

10. 将其放入脚本或提交后挂钩中，该挂钩在您编辑文档或将其添加到Makefile 用于生成 html，瞧！ 以编程方式生成 GitHub 页面。