Cách tích hợp wiki GitHub vào dự án chính

Question

Tôi muốn giữ tất cả mã nguồn và tài liệu của mình trong một kho lưu trữ git duy nhất. Tôi đã có các trang github tích hợp vào dự án chính của tôi và bây giờ tôi muốn làm điều tương tự với wiki github.

Tôi biết rằng github wiki là các kho lưu trữ git đơn giản. Kế hoạch của tôi là thêm wiki làm điều khiển từ xa vào repo chính của tôi và giữ mọi thứ ở một nơi. Tuy nhiên trong wiki repo tất cả mọi thứ là trong thư mục gốc và do đó sẽ lộn xộn dự án chính của tôi.

Có ai đã thử điều này trước đây không? cách tốt nhất để xử lý này là gì?

Answer 1

Bạn muốn thêm wiki dưới dạng submodule. Cùng một Wiki git repo được kết nối như một remote, nhưng trong một thư mục con với thư mục .git của nó.

git submodule add git://github.com/you/proj.wiki 

Trong thư mục gốc của repo chính của bạn để thêm repo wiki làm mô-đun con trong wiki/dir.

Answer 2

Bạn có thể tạo một submodule với repo wiki trong đó hoặc thực hiện tìm nạp thông thường và chuyển đổi chi nhánh qua lại.

Answer 3

Tôi thấy điều này khá tẻ nhạt - theo ý kiến ​​của tôi, github wikis nên là chi nhánh của kho lưu trữ chính, hoặc ít nhất nó sẽ có thể làm cho rằng một lựa chọn.

Tuy nhiên, tôi tin rằng giải pháp tốt nhất là chỉ cần di chuyển wiki vào kho chính, nói trong docs/ hoặc wiki, sử dụng một subtree merge. Ví dụ: giả sử kho lưu trữ của bạn là you/proj, wiki của bạn sẽ là: git://github.com/you/proj.wiki. Sau đó, để hợp nhất nó trong repo chính của bạn, bạn sẽ làm gì:

git clone git://github.com/you/proj 
cd proj 
git remote add -f wiki git://github.com/you/proj.wiki 
git merge -s ours --no-commit --allow-unrelated wiki/master 
git read-tree --prefix=wiki/ -u wiki/master 
git commit -m "Github wiki subtree merged in wiki/" 

Bạn thậm chí có thể giữ cho wiki làm việc trên một bên để chào đón những đóng góp nào đó, nhưng sau đó bác sĩ thú y chúng vào tài liệu chính của bạn như bạn thấy phù hợp. Để kết hợp các thay đổi mới trong sau khi xem xét, bạn sẽ làm gì:

git pull -s subtree wiki master 

Thật không may, kết hợp thay đổi cách khác là hơi phức tạp hơn, và dù sao, có lẽ bạn nên làm điều này như là một điều một thời gian, sau đó đóng wiki, hoặc chuyển hướng đến nguồn repo ...

Hơn nữa, một cảnh báo chính của phương pháp này là git log wiki/Home.md (ví dụ) không thực sự hiển thị lịch sử từ trang wiki. Lịch sử là ở đó, nhưng bằng cách nào đó, git-log không theo dõi được. Đây là một known limitation liên quan đến git subtrees. Một giải pháp khác để khắc phục điều này là thực hiện filter-branch và hợp nhất thường xuyên, một lần để giữ lịch sử.

Đối với tôi, lợi thế chính của việc có wiki như một phần của cây nguồn chính là yêu cầu kéo và thay đổi có thể được phối hợp trên mã và tài liệu. Nó cũng làm cho nó trivially đơn giản để tàu tài liệu với mã của bạn thay vì giả định mọi người sẽ chỉ đọc nó trực tuyến ...