バージョン管理

Gitでのレビュー、コミット、同期、ブランチ、スタッシュ、競合解決、取り消し、チャットのチェックポイント。

Embedrには日常的なGitのワークフローが組み込まれています。変更のレビュー、コミットや修正(amend)、リモートとの同期、ブランチの切り替えとマージ、競合の解決、スタッシュ、変更の破棄、取り消しができます。ターミナルを使わずに、普段のGit作業をひととおりこなせます。

リベース、チェリーピック、リバート、タグ、blame、bisect、サブモジュール、Git LFS、ワークツリー、ファイルの一部(ハンク)だけのステージはアプリにはありません。これらはターミナルでGitを使ってください。

Gitの場所

場所 用途
下部ツールバーのブランチボタン Git menu を開きます。変更、コミット、同期、マージの競合、ブランチを扱います。現在のブランチと、追加・削除された行数が表示されます。
Review Changes タブ 変更したすべての内容の差分。ファイルごとに破棄ボタンがあります。
History & remotes(Git menuの下部) Version Control ウィンドウを開きます。ファイル単位のステージ、コミット履歴、コミットの復元、ブランチの管理、リモート、スタッシュを扱います。

リポジトリを始める

プロジェクトがまだGitリポジトリでない場合、ブランチボタンは Initialize Git と表示されます。開いて Initialize Repository をクリックします。Embedrはリポジトリを作成し、Embedrプロジェクトに適した既定の .gitignore を追加して、最初のコミットを作ります。フォルダにコミットのないリポジトリがすでにある場合は、最初のコミットだけを作ります。

コミット

Git menuの Changes ヘッダーには、変更されたファイル数か Clean が表示されます。

  1. Review をクリックして Review Changes タブを開き、差分を読みます。
  2. Commit message (⌘Enter)... にメッセージを入力するか、Generate をクリックして変更内容からメッセージを書かせます。
  3. Commit をクリックするか、Cmd/Ctrl+Enter を押します。

Git menuの Commit は、すべての変更をステージしてコミットします。一部のファイルだけをコミットするには、Version Controlウィンドウを使います(ファイルを1つずつステージするを参照)。

コミットすると、短いハッシュとともにトーストで通知されます。追加できなかったファイルがある場合、トーストに Commit created with skipped files と表示され、そのファイル名が示されます。

直前のコミットを修正する

メッセージ欄の下にある Amend last commit にチェックを入れると、現在の変更を直前のコミットにまとめます。チェックボックスの横にそのコミットの件名が表示され、編集できます。ボタンは Amend に変わります。

ファイルを1つずつステージする

Version Controlウィンドウ(History & remotes)の Changes ビューでは、ファイルがステージ済みと未ステージに分かれて表示されます。

  • ファイルのステージボタン(Stage Changes / Unstage Changes)をクリックして移動します。
  • Stage All Changes、Unstage All Changes、Discard All Changes は一覧全体に作用します。
  • Commit staged(または Cmd/Ctrl+Enter)で、ステージしたものだけをコミットします。

変更をレビューする

Review Changes は、Git menuの Review ボタンか、タブバーの + メニューから開きます。ステージ済み・未ステージを問わず、変更されたすべてのファイルの差分が表示され、各ファイルに破棄ボタンがあります。コミットの前、特にエージェントの実行後は、次の点をレビューしてください。

  • ピン番号やペリフェラルの割り当ての変更
  • 削除されたセットアップコード
  • 新たに追加されたブロッキングな遅延
  • platformio.ini や embedr.yaml の依存関係の変更
  • コミットすべきでない生成ファイル

変更を破棄する

破棄すると、ファイルは最後のコミットの状態に戻ります。Embedrは必ず先に確認し、失われる内容を示します。

  • 1ファイル:Review Changes またはVersion Controlウィンドウで、その行の破棄ボタンを使います。
  • すべて:Git menuの ... メニュー(More change actions)にある Discard all changes… を使います。

一度もコミットされていないファイルは削除され、確認画面に復元できないことが表示されます。.gitignore に記載されたファイルには一切触れません。

直前のコミットを取り消す

... メニューの Undo last commit は、直前のコミットを取り消し、その変更をステージした状態で残します。修正してからもう一度コミットできます。

取り消しと修正(amend)は、プッシュされていないコミットにだけ使えます。次の場合は使えません。

状況 表示される理由
コミットがリモートにある This commit is already pushed.
マージが進行中 Complete or abort the merge first.
最初のコミットの取り消し The first commit cannot be undone.
マージコミットの取り消し A merge commit cannot be undone here.

リモートと同期する

コミット欄の下の同期の行には、ブランチと、プッシュするコミット数 ↑、プルするコミット数 ↓、そしてメインボタンが1つ表示されます。

ボタン 表示される場合 動作
Sync ブランチがリモートブランチを追跡している プルしてからプッシュします。
Publish branch ブランチがこのコンピューターにしかない プッシュして、リモートを追跡するよう設定します。

Pull、Push、Fetch を個別に実行するには、ボタンの横のメニュー(More sync actions)を使います。Git menuを開くと、最大5分に1回、裏でフェッチも行われるため、遅れているコミット数は最新に保たれます。

プルは常にマージで行われ、リベースはしません。プルで競合が起きた場合は、競合を解決するを参照してください。

プロジェクトにリモートがない場合、この行には Add a remote under History & remotes to sync. と表示されます。Version Controlウィンドウの Branches → Remote & Sync で追加します。リモート名(origin など)とリポジトリのURLを入力し、Update / Add Remote をクリックします。フェッチ、プル、プッシュの前にリモートを保存してください。同じセクションに Fetch、Pull、Push、Remove があります。

リモートへのサインイン

デスクトップでは、コンピューターにGitがインストールされていればEmbedrはそれを使うため、SSH鍵、認証情報ヘルパー、キーチェーンがターミナルと同じように機能します。Embedrが見えないパスワード入力を待つことはありません。

リモートがアクセスを拒否した場合、Git menuで Access token(ホストが必要とする場合はユーザー名も)を求められ、Try again で再試行します。

  • HTTPSのリモートでは、Remember for host on this computer にチェックを入れると、トークンがシステムのキーチェーンで暗号化されて保存されます。保存先はこのコンピューターのユーザーアカウントで、プロジェクト内には保存されません。
  • Remote & Sync の Forget saved token で削除できます。
  • Gitがインストールされていなくても、Embedrは動作しますが、すべてのリモートにHTTPSのURLとトークンが必要です。

アカウントのパスワードではなく、リポジトリの読み書き権限を持つ個人アクセストークンを使ってください。

ブランチ

Git menuにはローカルブランチが一覧表示され、現在のブランチにチェックが付きます。Search branches... で一覧を絞り込めます。

  • ブランチをクリックすると切り替わります。上書きされてしまう未コミットの変更がある場合、Embedrはそれを持っていくか確認します。持っていく場合は、変更をスタッシュし、切り替えてから、新しいブランチに適用します。きれいに適用できなかった場合は、Review migrated changes トーストで確認すべき点が示されます。この方法で作られたスタッシュはスタッシュの一覧に表示されます。
  • On remote の下のブランチはリモートにしかありません。クリックすると、それを追跡するローカルブランチが作成されます。
  • New Branch... は現在の位置からブランチを作成し、切り替えます。

Version Controlウィンドウの Branches には、Create Branch、Switch コントロール、Manage があります。Manage でブランチを選び、Merge into current branch または Delete Branch を選びます。どちらも確認を求められます。

競合を解決する

マージやプルがあなたのブランチと同じ行を変更している場合、失敗せずに競合で停止します。Git menuのコミット欄が Merge in progress に置き換わり、競合している各ファイルが Changed on both sides、Deleted here, changed on the other side、Changed here, deleted on the other side のいずれかの説明とともに一覧表示されます。

各ファイルについて:

ボタン 効果
Keep mine 自分のブランチの版を残します。
Use theirs 取り込む側の版を使います。
Keep deleted / Delete it どちらかの側でファイルが削除された場合に表示されます。
Resolved 自分でファイルを編集した場合に、そのままの状態でステージします。競合マーカー(<<<<<<<)が残っている間は拒否されます。

ファイル名をクリックすると、エディタで開きます。

Resolve with agent は、競合しているファイルの一覧をチャットに送り、両方の意図を保ち、競合マーカーをすべて取り除き、プロジェクトがまだビルドできることを確認するよう、コミットはせずにエージェントに依頼します。その後、あなたがレビューしてマージを完了します。

すべてのファイルを解決したら、Complete merge をクリックしてコミットします。Abort merge は、確認の後、すでに解決した競合も含めて、ファイルをマージ開始前の状態に戻します。

スタッシュ

スタッシュは、未コミットの変更を脇に置き、ファイルを最後のコミットの状態に戻します。

  • Git menuの ... メニューにある Stash changes は、すぐにスタッシュします。
  • Version Controlウィンドウの Branches → Stashes には、任意のメモ(What are you setting aside? (optional))付きの Stash current changes と Stash ボタンがあり、その下にスタッシュの一覧が、元のブランチと日時とともに表示されます。

各スタッシュには次のボタンがあります。

ボタン 効果
Pop 変更を適用し、スタッシュを削除します。
Apply 変更を適用し、スタッシュを残します。
ゴミ箱アイコン(Drop this stash) 確認の後、スタッシュを削除します。

スタッシュの適用で競合が起きた場合、Git menuに Stash applied with conflicts と表示され、スタッシュは残ります。Keep committed、Use stashed、Resolved でファイルを解決します。その後に完了させる操作はありません。

履歴とコミットの復元

Version Controlウィンドウの Changes ビューでは、作業中の変更の下にコミット履歴が表示されます。コミットを選ぶと、そのコミットで変更されたファイルと差分が表示されます。Restore files は、確認の後、現在のブランチ上でプロジェクトのファイルをそのコミットの状態に戻します。現在のステージ済み・未ステージの変更は上書きされます。そのコミットより後に追加されたファイルは削除され、Gitが追跡していないファイルはそのまま残ります。

リポジトリをクローンする

デスクトップのホームページで Clone Repository をクリックします。

  1. Repository URL(https://github.com/owner/repo.git または git@github.com:owner/repo.git)を貼り付けます。
  2. Clone into で親フォルダを選びます。プロジェクトフォルダにはリポジトリ名が付きます。
  3. ホストが求める場合は、Access token とユーザー名を入力します。
  4. Clone をクリックします。完了すると、プロジェクトが開きます。

チャットのチェックポイント

チェックポイントはGitとは別の仕組みです。Enable Chat Checkpoints(Settings → General、既定でオン)がオンの場合、エージェントにメッセージを送るたびに、その前にEmbedrがプロジェクトのファイルのスナップショットを取ります。スナップショットはプロジェクトの外に保存され、コミットは作られません。

元に戻すには、チャットの以前の自分のメッセージで Restore checkpoint and edit message をクリックします。確認の後、ファイルがスナップショットの状態に戻り、そのスレッドのそれ以降のメッセージはすべて削除され、あなたのメッセージが入力欄に戻されるので、編集して再送信できます。

エージェントの1ターンをすばやく取り消すにはチェックポイントを使います。残して共有したい履歴にはコミットを使います。

デスクトップとブラウザ

機能 デスクトップ ブラウザ
コミット、修正(amend)、レビュー、破棄、取り消し、ブランチ、マージ、競合、スタッシュ 対応 対応
リモート Gitで到達できる任意のリモート(SSHまたはHTTPS) GitHub、GitLab、BitbucketのHTTPSリポジトリ
認証情報 インストール済みのGitの鍵とヘルパー。トークンを記憶可能 リモートが必要とするたびにトークンを入力
新規(未追跡)ファイルのスタッシュ 対応(Gitがインストールされている場合) 非対応:新規ファイルはそのまま残ります
リポジトリのクローン 対応 非対応

ハードウェアプロジェクトでコミットするもの

設計を記述するファイルをコミットします。

  • ファームウェアのソース(src/、include/、lib/)
  • embedr.yaml と platformio.ini
  • ハードウェアのソース:pcb/ の .zen ファイルと、KiCadのプロジェクト、回路図、基板のファイル
  • mechanical/ 以下の機構設計のソース
  • 残しておきたいデータシートのメモ、配線のドキュメント、仕様書

ビルドの出力とローカルの状態は除外します。新しいリポジトリの .gitignore では、すでに除外されています。

# PlatformIO
.pio/
# Embedr local state
.embedr/
.embedr_chat/
.embedr-board/
# KiCad local state and backups
*.kicad_prl
*-backups/
fp-info-cache
# Secrets
.env
.env.*

エージェントとのよい進め方:

  1. クリーンな作業ツリーから始めます(Git menuに Clean と表示されます)。
  2. 範囲を絞った変更を1つ依頼します。
  3. エージェントにビルドかチェックを実行させます。
  4. Review Changes を開いて差分を読みます。
  5. 何をなぜ変えたかがわかるメッセージでコミットします。

差分が大きすぎてレビューできない場合は、依頼の範囲が広すぎたということです。