Git guide

そこで、あなたは貢献者になることを決めました (ありがとう！) 、そして git でいくつかの問題を抱えています。このガイドでは、リポジトリで使用する git の慣習とプラクティスの一部をカバーします。

基本的なワークフロー

Gitおよび/またはオープンソースプロジェクトを完全に初めて使用している場合は、このガイドが便利であることがあります: fork-commit-merge 。基本的なオープンソースワークフローを介してステップバイステップを使用します。

また、 official documentation と official reference manual を使用して、 git に詳細に移動することもできます。

Git LFSで画像を設定する

git lfs (大ファイルストレージ) は、リポジトリ内の大きなファイルの管理に役立つ git 拡張機能です。

「git」はプロジェクトの履歴全体を保存します。リポジトリをクローンするときは、そのリポジトリにあるファイルのすべてのバージョンをダウンロードする必要があります。ご想像のとおり、数回変更された大きなファイルを扱っている場合、この歴史のサイズは大規模になる可能性があります。

これは、Git LFSが登場する場所です。LFSには独自のストレージおよび参照システムがあります。ファイルがLFSに追加されると、プロジェクトファイルのリファレンスに置き換えられ、特定のコミットにアクセスするために checkout コマンドを実行した場合にのみダウンロードされます。これは、その履歴全体ではなく、大きなファイルのバージョンを1つだけダウンロードする必要があることを意味します。

プロジェクトでGit LFSを使用して、画像やその他の大きなファイルを保存しています。リポジトリをセットアップするには、最初に download and install Git LFS する必要があります。または、パッケージマネージャーを使用することもできます。次に、2つのコマンドを実行します。

git lfs install
git lfs pull

レポに画像を追加する必要がある場合、プロセスは git で通常のコミットを作成することに非常に似ています。最初に、ファイルシステムの適切なルートに画像を追加します。たとえば、今読んでいるページに画像を追加する場合、 website/src/content/docs/developer-guide/ フォルダーに移動します。その後、次のコマンドを実行する必要があります。

git add src/content/docs/developer-guide/picture.png
git commit -m “Added picture.png”

ご覧のとおり、このファイルをLFSに追加する必要があることに言及する必要はありません。 git はファイル拡張子を自動的に検出し、LFSによって追跡される場合、LFSによって処理されます。

あなたのコミットに署名する方法

gitを使用すると、コミットしたいユーザー名と電子メールアドレスを使用できます。小さなチーム、または閉鎖プロジェクトでは、これは問題ではありません。ただし、オープンソースの作業では、混乱を引き起こす可能性があります。

ありがたいことに、コミットに署名して身元を確認する方法はいくつかあります。プロジェクトのセキュリティを改善するのに役立つため、リポジトリに署名する必要があります。

コミットに署名する方法の詳細については、 official GitHub documentation on the topic をご覧ください。

コミット前のフックをスキップする

事前コミットとコミットフックを使用して、糸くず、テスト、その他の種類のチェックを実行します。これらのテストをスキップするには、 --no-verify flag、またはその速記 -n を使用できます。

git commit --no-verify -m “message”

--no-verify faは、 git push コマンドでも利用でき、同じ機能を提供します。

ただし、これらのテストはローカルでのみスキップされることに留意することが重要であり、フラグは一般に開発をスピードアップするために使用されます。PRを作成したら、すべてのテストが正常に完了することを確認する必要があります。

Good Practices

Git Rebase

オープンソースプロジェクトに貢献すると、PRまたはブランチとアップストリームコードの間の競合に遭遇する可能性があります。これは通常、コミットがコードベースの古いバージョンで行われ、他の貢献者によって新しい変更が実装されている場合に発生します。

git rebase コマンドを使用すると、ブランチをリポジトリの歴史に沿って移動し、それに基づいているコミットを変更できます。これにより、最新のコミットにブランチを作成できます。これのコマンドは次のとおりです。

git rebase origin/main

origin/main は ratatui/main を使用して最新でなければならないことに注意することが重要です。これは、 setting ratatui/main as the upstream for your repo で、またはGithubインターフェイスを介して、さまざまな方法で実行できます。

Squashing commits

理論的には、リベッシングは非常に簡単です。ただし、ブランチをリベースする前に解決する必要があるコンフリクトに遭遇する場合があります。リベースコンフリクトの主な原因の1つは、ブランチの歴史に多くの小さなコミットが存在することです。これは、スカッシングコミットが役立つ場所です。

コミットをスカッシュするには、 -i フラグを使用してインタラクティブなリベースを実行する必要があります。

最初に正しい枝にいることを確認してください。

git checkout your-branch

その後:

git rebase -i HEAD~x

このシナリオでは、 HEAD は your-branch の最新のコミットを指し、 x はブランチにあるコミットの数を表します。この数値を見つけるには、実行する必要があります。

git log origin/main..HEAD

このコマンドは、ブランチで行われたコミットのみを確認できるため有用です。

インタラクティブリベースコマンドを実行すると、 git はすべてのコミットを含むファイルを返します。

pick f7bae90 commit-4
pick 6b70439 commit-5

# Rebase ff5e017..6b70439 onto ff5e017 (2 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor

このファイルには、すべてのコミットが表示され、「pick」という言葉が前に表示されます。コミットを組み合わせるために、最初の単語を除くすべての「pick」の単語を「squash」に変更します。

ファイルを保存して閉じた後、新しいファイルを組み合わせたすべてのコミットメッセージで開きます。ここでしなければならないのは、新しいコミットメッセージを書くことだけです。これにより、コミットを押しつぶし、新しいコミットメッセージが生成されます。

これは一般的に多くのプロジェクトで役立つ優れたコーディングプラクティスですが、Ratatuiにとっては、PRが合併されたときにすべてのコミットを自動的にリバースして押し込むことを選択しました。

rebase コマンドの詳細については、 its entry in the reference guide へのリンクを次に示します。また、この tutorial をチェックして、追加のヘルプをご覧ください。

git commit

競合を引き起こす多くの小規模なコミットを回避する別の方法は、 git commit --amend コマンドを使用することです。たとえば、ファイルに小さな変更を加えたり、コミットメッセージの間違いを犯したりすると、 --amend を使用してクイック修正を行うことができます。

--amend を使用してコミットメッセージを変更するには、 -m フラグを追加するだけです。

git commit --amend -m "updated commit message”

以前のコミットに追加のファイルを追加するには、最初にステージを上げてから git commit --amend コマンドを実行する必要があります。 --no-edit フラグを使用して、コミットメッセージを変更せずにコミットを修正できます。

git add newfile.rs
git commit --amend --no-edit

--amend を使用する場合は注意してください。実際にはまったく新しいコミットが作成されるため、修正する予定のコミットを置き換えます。これは、ブランチの歴史を変更するため、公共のコミットで使用すると混乱する効果をもたらす可能性があります。自分で取り組んでいるブランチでのみ --amend を使用してください。

commit については、 here もご覧ください。

Git Push

アップストリームの問題を解決する

リポジトリをフォークすると、次のコマンドを使用して多くの問題を回避できます。

git remote add upstream https://github.com/ratatui/ratatui.git

メインリポジトリの変更でブランチを最新に保つには、単に実行してください。

git fetch upstream

remote add upstream コマンドは、フォークへの参照として元のリポジトリを追加します。これは、定期的に毎日または複数の更新を受けるプロジェクトに取り組む場合に役立ちます。ただし、短いプロジェクトの場合、アップストリームを追加する必要はありません。

問題は、プッシュ時に問題に遭遇する可能性があることです。この状況では、非常に便利なソリューションがあります

• push コマンドの -u フラグ。このフラグは、アップストリームをリポジトリに自動的に追加し、プッシュで通過します。私たちのプロジェクトでは、これは cargo-make を実行してWebサイトを構築する場合の問題になる可能性があります。

プッシュ時に上流の問題に遭遇した場合は、次のコマンドを試してください。

git push -u origin your-branch

-f フラグ

PRで問題が発生した場合、それらを解決するために git push -f を使用しないでください。

-f フラグは、 --force の速記であり、ローカルマシンで見つからないコミットを削除することにより、リポジトリの履歴を書き直します。このフラグでプッシュされたリポジトリをマージしようとすると、多くの解決不可能な対立が得られます。

push については、here もご覧ください。