Azure DevOps CLI 完全ガイド

この記事は Qiita Advent Calender - Azure DevOps の 8 日目の記事です。

Azure DevOps CLI とは

Azure DevOps CLI は、クラウド (SaaS) 版である Azure DevOps Services とオンプレミス版である Azure DevOps Server 2020 で使用することができるコマンドライン ツールです。
Azure CLI 拡張機能として実装されているため、Azure CLI をインスト－ルした状態で以下のコマンドを実行して導入する必要があります。

 az extension add --name azure-devops

Azure DevOps CLI は、Web UI 経由で設定が必要だった管理項目をコマンドラインから実行可能にするだけでなく、パイプライン成果物 (Pipeline Artifacts) のダウンロードなどユーザー向けにも便利な機能を提供します。 また、ユニバーサル パッケージの管理や利用者向けの案内（バナー）表示など Azure DevOps CLI からのみ可能な機能も存在します。

Azure DevOps CLI の概要については、Microsoft Docs に記載があります。

docs.microsoft.com

しかし、残念ながら Azure DevOps CLI が提供するコマンド一覧が俯瞰できるドキュメントがないため、「何ができて、何ができないのかが分かりにくい」という課題がありました。
そこで、本記事では記事投稿 (2020/12/8 ) 時点で実装されているグループとコマンドの一覧を記載し、各コマンドの説明も日本語に翻訳しました。*1
各コマンドの実行方法については、サブグループ単位で対応する公式ドキュメントのリンクを貼り付けていますので、そちらを参照ください。

Azure DevOps CLI コマンド一覧

Azure DevOps CLI 拡張機能をインストールすると Azure CLI のサブ グループとして以下が追加されます。 *2

• az repos (Azure Repos 向け)
• az boards (Azure Boards 向け)
• az pipelines (Azure Pipelines 向け)
• az artifacts (Azure Artifacts 向け)
• az devops (Azure DevOps 全般)

az repos コマンド

Azure Repos を管理します。

グループ名	概要
import	Git リポジトリのインポートを管理します。
policy	ブランチポリシーを管理します。
pr	プル リクエスト (PR) 管理します。
ref	Git リファレンスを管理します。

コマンド名	概要
create	チーム プロジェクトに Git リポジトリを作成します。
delete	チーム プロジェクト内の Git リポジトリを削除します。
list	チーム プロジェクトの Git リポジトリを一覧表示します。
show	チーム プロジェクトの Git リポジトリの詳細を表示します。
update	Git リポジトリを更新します。

docs.microsoft.com

az repos import コマンド

Git リポジトリのインポートを管理します。

コマンド名	概要
create	Git インポート要求を作成します。

docs.microsoft.com

az repos policy コマンド

ブランチ ポリシーを管理します。

グループ名	概要
approver-count	承認者数ポリシーを管理します。
build	ビルド ポリシーを管理します。
case-enforcement	大文字/小文字強制ポリシーを管理します。
comment-required	コメント必須ポリシーを管理します。
file-size	ファイル サイズ ポリシーを管理します。
merge-strategy	マージ戦略ポリシーを管理します。
required-reviewer	必須レビューアー ポリシーを管理します。
work-item-linking	作業項目リンク ポリシーを管理します。

コマンド名	概要
create	構成ファイルを使用してポリシーを作成します。
delete	ポリシーを削除します。
list	プロジェクト内のすべてのポリシーを一覧表示します。
show	ポリシーの詳細を表示します。
update	構成ファイルを使用してポリシーを更新します。

docs.microsoft.com

az repos policy approver-count コマンド

承認者数ポリシーを管理します。

コマンド名	概要
create	承認者数ポリシーを作成します。
update	承認者数のポリシーを更新します。

docs.microsoft.com

az repos policy build コマンド

ビルド ポリシーを管理します。

コマンド名	概要
create	ビルド ポリシーを作成します。
update	ビルド ポリシーを更新します。

docs.microsoft.com

az repos policy case-enforcement コマンド

大文字/小文字強制ポリシーを管理します。

コマンド名	概要
create	大文字/小文字強制ポリシーを作成します。
update	大文字/小文字強制ポリシーを更新します。

docs.microsoft.com

az repos policy comment-required コマンド

コメント必須ポリシーを管理します。

コマンド名	概要
create	コメント必須ポリシーを作成します。
update	コメント必須ポリシーを更新します。

docs.microsoft.com

az repos policy file-size コマンド

ファイル サイズ ポリシーを管理します。

コマンド名	概要
create	ファイル サイズ ポリシーを作成します。
update	ファイル サイズ ポリシーを更新します。

docs.microsoft.com

az repos policy merge-strategy コマンド

マージ戦略ポリシーを管理します。

コマンド名	概要
create	マージ戦略ポリシーを作成します。
update	マージ戦略ポリシーを更新します。

docs.microsoft.com

az repos policy required-reviewer コマンド

必須レビューアー ポリシーを管理します。

コマンド名	概要
create	必須レビューアー ポリシーを作成します。
update	必須レビューアー ポリシーを更新します。

docs.microsoft.com

az repos policy work-item-linking コマンド

作業項目リンク ポリシーを管理します。

コマンド名	概要
create	作業項目リンク ポリシーを作成します。
update	作業項目リンク ポリシーを更新します。

docs.microsoft.com

az repos pr コマンド

プル リクエスト (PR) を管理します。

コマンド名	概要
policy	プル リクエスト (PR) のポリシーを管理します。
reviewer	プル リクエスト (PR) のレビュー担当者を管理します。
work-item	プル リクエスト (PR) に関連付けられている作業項目を管理します。

コマンド名	概要
checkout	ローカルに変更がない場合は、PR 元のブランチをローカルでチェックアウトします。
create	プル リクエストを作成します。
list	プル リクエストを一覧表示します。
set-vote	プル リクエストに投票します。
show	プル リクエストの詳細を取得します。
update	プル リクエストを更新します。

docs.microsoft.com

az repos pr policy コマンド

プル リクエスト (PR) のポリシーを管理します。

コマンド名	概要
list	プル リクエストのポリシーを一覧表示します。
queue	プルリクエストのポリシー評価をキューに配置します。

docs.microsoft.com

az repos pr reviewer コマンド

プル リクエスト (PR) のレビュー担当者を管理します。

コマンド名	概要
add	1 人以上のレビュー担当者をプル リクエストに追加します。
list	プル リクエストのレビュー担当者を一覧表示します。
remove	1人以上のレビュー担当者をプル リクエストから削除します。

docs.microsoft.com

az repos pr work-item コマンド

プル リクエスト (PR) に関連付けられている作業項目を管理します。

コマンド名	概要
add	1つ以上の作業項目をプル リクエストにリンクします。
list	プル リクエストのリンクされた作業項目を一覧表示します。
remove	1つ以上の作業項目をプル リクエストからリンク解除します。

docs.microsoft.com

az repos ref コマンド

Git リファレンスを管理します。

コマンド名	概要
create	参照を作成します。
delete	参照を削除します。
list	参照を一覧表示します。
lock	参照をロックします。
unlock	参照のロックを解除します。

docs.microsoft.com

az boards コマンド

Azure Boards を管理します。

グループ名	概要
area	エリア パスを管理します。
iteration	イテレーションを管理します。
work-item	作業項目を管理します。

コマンド名	概要
query	作業項目の一覧を照会します。

docs.microsoft.com

az boards area コマンド

エリア パス (区分パス) を管理します。

コマンド名	概要
project	プロジェクトの区分を管理します。
team	チームの区分を管理します。

docs.microsoft.com

az boards area project コマンド

プロジェクトの区分を管理します。

コマンド名	概要
create	プロジェクトの区分を作成します。
delete	プロジェクトの区分を削除します。
list	プロジェクトの区分を一覧表示します。
show	プロジェクトの区分の詳細を表示します。
update	プロジェクトの区分を更新します。

docs.microsoft.com

az boards area team コマンド

チームの区分を管理します。

コマンド名	概要
add	チームの区分を追加します。
list	チームの区分を一覧表示します。
remove	チームの区分を削除します。
update	チームの区分を更新します。

docs.microsoft.com

az boards iteration コマンド

イテレーションを管理します。

グループ名	概要
project	プロジェクトのイテレーションを管理します。
team	チームのイテレーションを管理します。

docs.microsoft.com

az boards iteration project コマンド

プロジェクトのイテレーションを管理します。

コマンド名	概要
create	イテレーションを作成します。
delete	イテレーションを削除します。
list	プロジェクトのイテレーションを一覧表示します。
show	プロジェクトのイテレーションの詳細を表示します。
update	プロジェクトイテレーションを更新します。

docs.microsoft.com

az boards iteration team コマンド

チームのイテレーションを管理します。

コマンド名	概要
add	イテレーションをチームに追加します。
list	チームのイテレーションを一覧表示します。
list-work-items	イテレーションの作業項目を一覧表示します。
remove	チームからイテレーションを削除します。
set-backlog-iteration	チームのバックログイテレーションを設定します。
set-default-iteration	チームの既定のイテレーションを設定します。
show-backlog-iteration	チームのバックログ イテレーションを表示します。
show-default-iteration	チームの既定のイテレーションを表示します。

docs.microsoft.com

az boards work-item コマンド

作業項目を管理します。

グループ名	概要
relation	作業項目のリレーションシップを管理します。

コマンド名	概要
create	作業項目を作成します。
delete	作業項目を削除します。
show	作業項目の詳細を表示します。
update	作業項目を更新します。

docs.microsoft.com

az boards work-item relation コマンド

作業項目のリレーションシップを管理します。

コマンド名	概要
add	作業項目にリレーションシップを追加します。
list-type	組織でサポートされている作業項目のリレーションシップの一覧を表示します。
remove	作業項目からリレーションシップを削除します。
show	作業項目を取得し、わかりやすい名前を設定します。

docs.microsoft.com

az pipelines コマンド

Azure Pipelines を管理します。

グループ名	概要
agent	エージェントを管理します。
build	ビルドを管理します。
folder	パイプラインを整理するためのフォルダーを管理します。
pool	エージェント プールを管理します。
queue	エージェント キューを管理します。
release	リリースを管理します。
runs	パイプライン実行を管理します。
variable	パイプライン変数を管理します。
variable-group	変数グループを管理します。

コマンド名	概要
create	新しい Azure Pipeline (YAML ベース) を作成します。
delete	パイプラインを削除します。
list	パイプラインを一覧表示します。
run	パイプラインをキューに配置 (実行) します。
show	パイプラインの詳細を取得します。
update	パイプラインを更新します。

docs.microsoft.com

az pipelines agent コマンド

エージェントを管理します。

コマンド名	概要
list	プール内のエージェントの一覧を取得します。
show	エージェントの詳細を表示します。

docs.microsoft.com

az pipelines build コマンド

ビルドを管理します。

グループ名	概要
definition	ビルド定義を管理します。
tag	ビルド タグを管理します。

コマンド名	概要
list	ビルド結果を一覧表示します。
queue	ビルドを要求 (キュー) します。
show	ビルドの詳細を取得します。

docs.microsoft.com

az pipelines build definition コマンド

ビルド定義を管理します。

コマンド名	概要
list	ビルド定義を一覧表示します。
show	ビルド定義の詳細を取得します。

docs.microsoft.com

az pipelines build tag コマンド

ビルド タグを管理します。

コマンド名	概要
add	ビルドのタグを追加します。
delete	ビルド タグを削除します。
list	ビルドのタグを取得します。

docs.microsoft.com

az pipelines folder コマンド

パイプラインを整理するためのフォルダーを管理します。

コマンド名	概要
create	フォルダーを作成します。
delete	フォルダーを削除します。
list	すべてのフォルダーを一覧表示します。
update	フォルダー名または説明を更新します。

docs.microsoft.com

az pipelines pool コマンド

エージェント プールを管理します。

コマンド名	概要
list	エージェント プールを一覧表示します。
show	エージェント プールの詳細を表示します。

docs.microsoft.com

az pipelines queue コマンド

エージェント キューを管理します。

コマンド名	概要
list	エージェント キューを一覧表示します。
show	エージェント キューの詳細を表示します。

docs.microsoft.com

az pipelines release コマンド

リリースを管理します。

グループ名	概要
definition	リリース定義を管理します。

コマンド名	概要
create	リリースを要求 (作成) します。
list	リリース結果を一覧表示します。
show	リリースの詳細を取得します。

docs.microsoft.com

az pipelines release definition コマンド

リリース定義を管理します。

コマンド名	概要
list	リリース定義を一覧表示します。
show	リリース定義の詳細を取得します。

docs.microsoft.com

az pipelines runs コマンド

パイプライン実行を管理します。

グループ名	概要
artifact	Manage pipeline run artifacts.
tag	Manage pipeline run tags.

コマンド名	概要
list	List the pipeline runs in a project.
show	Show details of a pipeline run.

docs.microsoft.com

az pipelines runs artifact コマンド

パイプライン実行の成果物を管理します。

コマンド名	概要
download	パイプライン成果物をダウンロードします。
list	実行に関連付けられている成果物の一覧を表示します。
upload	パイプライン成果物をアップロードします。

docs.microsoft.com

az pipelines runs tag コマンド

パイプライン実行のタグを管理します。

コマンド名	概要
add	パイプライン実行のタグを追加します。
delete	パイプライン実行タグを削除します。
list	パイプライン実行のタグを取得します。

docs.microsoft.com

az pipelines variable コマンド

パイプライン変数を管理します。

コマンド名	概要
create	パイプラインに変数を追加します。
delete	パイプラインから変数を削除します。
list	パイプライン内の変数の一覧を表示します。
update	パイプラインの変数を更新します。

docs.microsoft.com

az pipelines variable-group コマンド

変数グループを管理します。

グループ名	概要
variable	変数グループ内の変数を管理します。

コマンド名	概要
create	変数グループを作成します。
delete	変数グループを削除します。
list	変数グループを一覧表示します。
show	変数グループの詳細を表示します。
update	変数グループを更新します。

docs.microsoft.com

az pipelines variable-group variable コマンド

変数グループ内の変数を管理します。

コマンド名	概要
create	変数グループに変数を追加します。
delete	変数グループから変数を削除します。
list	変数グループ内の変数の一覧を表示します。
update	変数グループ内の変数を更新します。

docs.microsoft.com

az artifacts コマンド

Azure Artifacts を管理します。

グループ名	概要
universal	ユニバーサル パッケージを管理します。

docs.microsoft.com

az artifacts universal コマンド

ユニバーサル パッケージを管理します。

コマンド名	概要
download	パッケージをダウンロードします。
publish	パッケージをフィードに発行します。

docs.microsoft.com

az devops コマンド

Azure DevOps の組織を管理します。

グループ名	概要
admin	管理操作を管理します。
extension	拡張機能を管理します。
project	チーム プロジェクトを管理します。
security	セキュリティ関連の操作を管理します。
service-endpoint	サービス エンドポイント/接続を管理します。
team	チームを管理します。
user	ユーザーを管理します。
wiki	Wiki を管理します。

コマンド名	概要
configure	Azure DevOps CLIを構成するか、構成を表示します。
invoke	任意の DevOps エリアとリソースの REST API を呼び出します。
login	特定の組織に使用する資格情報 (PAT) を設定します。
logout	すべての組織または特定の組織の資格情報をクリアします。

docs.microsoft.com

az devops admin コマンド

管理操作を管理します。

グループ名	概要
banner	組織のバナーを管理します。

docs.microsoft.com

az devops admin banner コマンド

組織のバナーを管理します。

コマンド名	概要
add	新しいバナーを追加し、すぐに表示します。
list	バナーを一覧表示します。
remove	バナーを削除します。
show	バナーの詳細を表示します。
update	バナーのメッセージ、レベル、または有効期限を更新します。

docs.microsoft.com

az devops extension コマンド

拡張機能を管理します。

コマンド名	概要
disable	拡張機能を無効にします。
enable	拡張機能を有効にします。
install	拡張機能をインストールします。
list	組織にインストールされている拡張機能を一覧表示します。
search	Marketplace から拡張機能を検索します。
show	1つの拡張機能の詳細を取得します。
uninstall	拡張機能をアンインストールします。

docs.microsoft.com

az devops project コマンド

チーム プロジェクトを管理します。

コマンド名	概要
create	チーム プロジェクトを作成します。
delete	チーム プロジェクトを削除します。
list	チーム プロジェクトを一覧表示します。
show	チーム プロジェクトを表示します。

docs.microsoft.com

az devops security コマンド

セキュリティ関連の操作を管理します。

グループ名	概要
group	セキュリティ グループを管理します。
permission	セキュリティ アクセス許可を管理します。

docs.microsoft.com

az devops security group コマンド

セキュリティ グループを管理します。

グループ名	概要
membership	セキュリティ グループのメンバーシップを管理します。

コマンド名	概要
create	新しい Azure DevOps グループを作成します。
delete	Azure DevOps グループを削除します。
list	プロジェクトまたは組織内のすべてのグループを一覧表示します。
show	グループの詳細を表示します。
update	Azure DevOps グループの名前と説明を更新します。

docs.microsoft.com

az devops security group membership コマンド

セキュリティ グループのメンバーシップを管理します。

グループ名	概要
add	メンバーシップを追加します。
list	グループまたはユーザーのメンバーシップを一覧表示します。
remove	メンバーシップを削除します。

docs.microsoft.com

az devops security permission コマンド

セキュリティ アクセス許可を管理します。

グループ名	概要
namespace	セキュリティ名前空間を管理します。

コマンド名	概要
list	特定のユーザー/グループと名前空間のトークンを一覧表示します。
reset	特定のアクセス許可ビットのアクセス許可をリセットします。
reset-all	ユーザー/グループに対するこのトークンのすべてのアクセス許可をクリアします。
show	特定のトークン、名前空間、およびユーザー/グループのアクセス許可を表示します。
update	特定のユーザーまたはグループに許可または拒否アクセス許可を割り当てる。

docs.microsoft.com

az devops security permission namespace コマンド

セキュリティ名前空間を管理します。

コマンド名	概要
list	組織で使用可能なすべての名前空間を一覧表示します。
show	各名前空間で使用できるアクセス許可の詳細を表示します。

docs.microsoft.com

az devops service-endpoint コマンド

サービス エンドポイント/接続を管理します。

グループ名	概要
azurerm	Azure RM サービス エンドポイント/接続を管理します。
github	GitHub サービス エンドポイント/接続を管理します。

コマンド名	概要
create	構成ファイルを使用してサービス エンドポイントを作成します。
delete	サービス エンドポイントを削除します。
list	プロジェクト内のサービス エンドポイントを一覧表示します。
show	サービス エンドポイントの詳細を取得します。
update	サービス エンドポイントを更新します。

docs.microsoft.com

az devops service-endpoint azurerm コマンド

Azure RM サービス エンドポイント/接続を管理します。

コマンド名	概要
create	Azure RM サービス エンドポイントを作成します。

docs.microsoft.com

az devops service-endpoint github コマンド

GitHub サービス エンドポイント/接続を管理します。

コマンド名	概要
create	GitHub サービス エンドポイントを作成します。

docs.microsoft.com

az devops team コマンド

チームを管理します。

コマンド名	概要
create	チームを作成します。
delete	チームを削除します。
list	プロジェクト内のすべてのチームを一覧表示します。
list-member	チームのメンバーを一覧表示します。
show	チームの詳細を表示します。
update	チームの名前や説明を更新します。

docs.microsoft.com

az devops user コマンド

コマンド名	概要
add	Add user.
list	List users in an organization [except for users which are added via AAD groups].
remove	Remove user from an organization.
show	Show user details.
update	Update license type for a user.

docs.microsoft.com

az devops wiki コマンド

Wiki を管理します。

グループ名	概要
page	Wiki のページを管理する

コマンド名	概要
create	Wiki を作成します。
delete	Wiki を削除します。
list	プロジェクトまたは組織内のすべての wiki を一覧表示します。
show	wiki ページを管理します。

docs.microsoft.com

az devops wiki page コマンド

Wiki ページを管理します。

コマンド名	概要
create	新しいページを追加します。
delete	ページを削除します。
show	ページの内容を取得するか、ページを開きます。
update	ページを編集します。

docs.microsoft.com

*1:可能な限り Azure DevOps Server / Team Foundaiton Server 日本語版の用語と統一されるようにしています

*2:Azure Test Plans 向けのコマンドは存在しません

巨大な Git リポジトリで役立つクローンの知識

巨大な Git リポジトリを扱う際に課題となりやすいクローン時間の短縮や、ディスク使用量を削減する方法について解説する。

近年では、様々な理由から巨大な Git リポジトリを扱うケースが増えている。
たとえば、GitHub 上で管理されている 日本語版 Azure Docs のリポジトリ azure-docs.ja-jp では、Azure Docs の日本語記事がすべて含まれているため、4 GB 近い巨大なリポジトリとなっている。

このようなリポジトリに対して貢献したい場合、通常の開発時と同様に完全クローン (Full Clone) する必要は無い。
Git にはシャロー クローン (Shallow Clone)、パーシャル クローン (Partial Clone) といった機能に加えて、スパース チェックアウト (Sparse Checkout) という便利な機能を備えているので、これらの機能を使用するとよい。

実験と結果

どの程度の効果が見込まれるのかは実際のリポジトリを例にしたほうがわかりやすい。
そこで、GitHub 上で管理されている日本語版 Azure Docs のリポジトリを使って実験を行った。

github.com

各方法でクローンした場合の処理時間とディスク使用量の比較表を以下に示す。

なお、実行時間についてはハードウェアの構成やネットワーク状況によっても大きくことなることに加えて、スパース チェックアウトの場合はチェックアウト処理は含んでいないのであくまで参考値として扱ってほしい (それでも爆速/省容量であることがわかるはずだ)。

	Full	Shallow (depth=1)	Partial (blobless)	Partial (treeless)	Sparse	Partial+Sparse
実行時間	04:26.5	00:56.4	01:54.1	01:19.6	03:02.4	00:10.9
Full Clone との比較	100%	472%	233%	335%	146%	2440%
ディスク使用量 (bytes)	3,836,788,432	1,051,743,115	1,181,308,994	1,063,763,634	3,179,861,292	128,503,442
Full Clone との比較	100%	27%	31%	28%	83%	3%

続いて、各方法と実際の実行方法と結果について見ていく。

完全クローン (Full Clone)

単純に git clone を実行すると、完全なクローンがローカルに作成される。

git clone https://github.com/MicrosoftDocs/azure-docs.ja-jp.git full

実行結果を以下に示す。

Cloning into 'full'...
remote: Enumerating objects: 968479, done.
remote: Counting objects: 100% (67154/67154), done.
remote: Compressing objects: 100% (32479/32479), done.
remote: Total 968479 (delta 43253), reused 56056 (delta 34042), pack-reused 901325
Receiving objects: 100% (968479/968479), 2.93 GiB | 14.55 MiB/s, done.
Resolving deltas: 100% (810289/810289), done.
Updating files: 100% (24894/24894), done.

参考情報として、Git-Sizer による分析結果を以下に示す。

Processing blobs: 611123
Processing trees: 329734
Processing commits: 27622
Matching commits to trees: 27622
Processing annotated tags: 0
Processing references: 41
| Name                         | Value     | Level of concern               |
| ---------------------------- | --------- | ------------------------------ |
| Overall repository size      |           |                                |
| * Blobs                      |           |                                |
|   * Total size               |  13.4 GiB | *                              |
|                              |           |                                |
| Biggest objects              |           |                                |
| * Trees                      |           |                                |
|   * Maximum entries      [1] |  1.72 k   | *                              |
| * Blobs                      |           |                                |
|   * Maximum size         [2] |  34.0 MiB | ***                            |
|                              |           |                                |
| Biggest checkouts            |           |                                |
| * Number of directories  [3] |  4.58 k   | **                             |
| * Maximum path length    [3] |   196 B   | *                              |
| * Total size of files    [4] |  1.64 GiB | *                              |

[1]  73096cbd631076a715fc9f97908869d8c7e5fd7c (053c624595ab0dc29c3181d5580999ededb65514:includes)
[2]  bedffc08616540404d9e6275a11a5751688b43dd (refs/remotes/origin/repo_sync_working_branch:articles/search/media/search-create-service-portal/AnimatedGif-AzureSearch.gif)
[3]  249165cef1d1a8ed4fbd9378524786374437c773 (cb3e7bb5b27eb350d9934bab302e5ce4918a1ab2^{tree})
[4]  d63a1d9a82f8008c7ebf935bd0c5f2cd14538ffd (d143e24c40ed15e40065f382d89e6803c40530bd^{tree})

シャロー クローン (Shallow Clone)

シャロー (Shallow) とは "浅い" を意味し、指定した履歴数分だけの浅いクローンがローカルに作成できる。 たとえば、リポジトリ内で管理されているフォルダやファイルには幅広くアクセスしたいが、履歴情報は直近のみでよい、といったような場合に便利なオプションといえる。

下記の場合、--depth 1 を指定して履歴情報として最新のみを保持したクローンを作成している。

git clone --depth 1 https://github.com/MicrosoftDocs/azure-docs.ja-jp.git shallow

実行結果を以下に示す。

Cloning into 'shallow'...
remote: Enumerating objects: 26823, done.
remote: Counting objects: 100% (26823/26823), done.
remote: Compressing objects: 100% (23953/23953), done.
remote: Total 26823 (delta 3879), reused 8600 (delta 2570), pack-reused 0
Receiving objects: 100% (26823/26823), 384.99 MiB | 21.46 MiB/s, done.
Resolving deltas: 100% (3879/3879), done.
Updating files: 100% (24894/24894), done.

パーシャル クローン (Partial Clone)

パーシャル (Partial) とは "部分的" を意味し、クローン時にツリーやブロブなどの情報の一部の情報を除外してクローンすることができる。 パーシャル クローンを利用した省スペースなクローンは以下の 2 種類に分類される。

• ブロブレス クローン (Blobless Clone)
• ツリーレス クローン (Treeless Clone)

ブロブレス クローン (Blobless Clone)

ブロブレス クローンはコミットとツリーを取得し、ブロブは必要に応じて取得する方式である。
正確には、HEAD のみブロブが取得され、履歴上のブロブは git diff などのコマンドによって必要になった際に取得される。最新のファイルはビルドなどで必要とするが、履歴上のファイルは必要に応じて取得したいといった開発用途で使えるオプションである。

git clone --filter=blob:none https://github.com/MicrosoftDocs/azure-docs.ja-jp.git blobless

実行結果を以下に示す。

Cloning into 'blobless'...
remote: Enumerating objects: 357356, done.
remote: Counting objects: 100% (30851/30851), done.
remote: Compressing objects: 100% (12095/12095), done.
Rremote: Total 357356 (delta 25309), reused 23517 (delta 18123), pack-reused 326505
), 109.79 MiB | 24.34 MiB/s
Receiving objects: 100% (357356/357356), 112.84 MiB | 24.55 MiB/s, done.
Resolving deltas: 100% (299963/299963), done.
remote: Enumerating objects: 24817, done.
remote: Counting objects: 100% (20056/20056), done.
remote: Compressing objects: 100% (17677/17677), done.
remote: Total 24817 (delta 3698), reused 2523 (delta 2379), pack-reused 4761 eceiving objects: 100% (24817/24817), 380.85 MiB | 7.55 MiB/s
Receiving objects: 100% (24817/24817), 384.11 MiB | 9.52 MiB/s, done.
Resolving deltas: 100% (3853/3853), done.
Updating files: 100% (24894/24894), done.

ツリーレス クローン (Treeless Clone)

ツリーレス クローンはコミットのみを取得し、ツリーとブロブは必要に応じて取得する方式である。
HEAD のブロブが取得されるので最新のコードをビルドする際には便利だが、git log のようなコマンドで履歴を参照すると、ツリーの情報取得が開始されてしまうため、開発時の用途には不向きなオプションといえる。 逆に、自動ビルド時のようにコミット履歴やツリーなどを参照せず、最新のファイルのみを取得したい場合に便利なオプションといえる。

git clone --filter=tree:0 https://github.com/MicrosoftDocs/azure-docs.ja-jp.git treeless

実行結果を以下に示す。

Cloning into 'treeless'...
remote: Enumerating objects: 27622, done.
remote: Counting objects: 100% (1483/1483), done.
remote: Compressing objects: 100% (1474/1474), done.
remote: Total 27622 (delta 9), reused 1402 (delta 9), pack-reused 26139
Receiving objects: 100% (27622/27622), 8.72 MiB | 12.15 MiB/s, done.
Resolving deltas: 100% (1597/1597), done.
remote: Enumerating objects: 2005, done.
remote: Counting objects: 100% (895/895), done.
remote: Compressing objects: 100% (893/893), done.
remote: Total 2005 (delta 1), reused 65 (delta 1), pack-reused 1110
Receiving objects: 100% (2005/2005), 935.11 KiB | 3.64 MiB/s, done.
Resolving deltas: 100% (1/1), done.
remote: Enumerating objects: 24817, done.
remote: Counting objects: 100% (19924/19924), done.
remote: Compressing objects: 100% (17535/17535), done.
remote: Total 24817 (delta 3665), reused 2533 (delta 2389), pack-reused 4893 eceiving objects: 100% (24817/24817), 381.3Receiving objects: 100% (24817/24817), 384.13 MiB | 17.86 MiB/s, done.

Resolving deltas: 100% (3845/3845), done.
Updating files: 100% (24894/24894), done.

スパース チェックアウト (Sparse Checkout)

スパース (Sparse) とは「わずかに」を意味し、スパース チェックアウトを使用することで特定のディレクトリおよびファイルのみをチェックアウト対象にすることができる。
スパース チェックアウトを利用するには、--sparse オプションを使用する。また、そのままではクローン時に自動的にチェックアウトが行われてしまうため --no-checkout オプションを指定して、無効にしておくとよい。

git clone --sparse --no-checkout https://github.com/MicrosoftDocs/azure-docs.ja-jp.git sparse

実行例を以下に示す。

Cloning into 'sparse'...
remote: Enumerating objects: 968479, done.
remote: Counting objects: 100% (67154/67154), done.
remote: Compressing objects: 100% (32441/32441), done.
remote: Total 968479 (delta 43273), reused 56078 (delta 34080), pack-reused 901325 eceiving objects: 100% (968479/968479Receiving objects: 100% (968479/968479), 2.94 GiB | 20.81 MiB/s, done.

Resolving deltas: 100% (810293/810293), done.

その後、git sparse-checkout コマンドで実際に必要なフォルダを指定し、チェックアウトを行う。
articles/devops-project のみを対象とする例を以下に示す。

git sparse-checkout set articles/devops-project
git checkout

実行結果を以下に示す。

remote: Enumerating objects: 45, done.
remote: Counting objects: 100% (18/18), done.
remote: Compressing objects: 100% (18/18), done.
remote: Total 45 (delta 12), reused 0 (delta 0), pack-reused 27 eceiving objects:  91% (41/45)
Receiving objects: 100% (45/45), 2.13 MiB | 10.01 MiB/s, done.
Resolving deltas: 100% (12/12), done.
remote: Enumerating objects: 1, done.
remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 1
Receiving objects: 100% (1/1), 279 bytes | 279.00 KiB/s, done.
Updating files: 100% (48/48), done.
Your branch is up to date with 'origin/master'.

ブロブレス クローンとスパース チェックアウトの組み合わせ

最初の表で示したとおり、実はスパースチェックアウトだけを使用すると、ブロブやツリーなどの過去情報を取得してしまうため、完全クローンに近い実行時間とディスク容量が必要となる。

このため、一般的には上記のブロブレス クローンと組み合わせ、過去のブロブは取得せずに必要なファイルのみスパース チェックアウトするのがよい。

git clone --filter=blob:none --sparse --no-checkout https://github.com/MicrosoftDocs/azure-docs.ja-jp.git blobless+sparse

実行結果を以下に示す。

Cloning into 'blobless+sparse'...
remote: Enumerating objects: 357356, done.
remote: Counting objects: 100% (30851/30851), done.
remote: Compressing objects: 100% (12094/12094), done.
remote: Total 357356 (delta 25298), reused 23528 (delta 18124), pack-reused 326505
Receiving objects: 100% (357356/357356), 112.98 MiB | 24.98 MiB/s, done.
Resolving deltas: 100% (300023/300023), done.

備忘録

この記事は以下の時点での azure-docs.ja-jp リポジトリを対象にした。

github.com

実験用バッチ スクリプト

計測用に作ったバッチ ファイルを以下に示す。

@ECHO OFF

ECHO ::: FULL CLONE :::
ECHO %TIME%
git clone https://github.com/MicrosoftDocs/azure-docs.ja-jp.git full
ECHO %TIME%

ECHO ::: SHALLOW CLONE :::
ECHO %TIME%
git clone --depth 1 https://github.com/MicrosoftDocs/azure-docs.ja-jp.git shallow
ECHO %TIME%

ECHO ::: BLOBLESS CLONE :::
ECHO %TIME%
git clone --filter=blob:none https://github.com/MicrosoftDocs/azure-docs.ja-jp.git blobless
ECHO %TIME%

ECHO ::: TREELESS CLONE :::
ECHO %TIME%
git clone --filter=tree:0 https://github.com/MicrosoftDocs/azure-docs.ja-jp.git treeless
ECHO %TIME%

ECHO ::: SPARSE CLONE :::
ECHO %TIME%
git clone --sparse --no-checkout https://github.com/MicrosoftDocs/azure-docs.ja-jp.git sparse
ECHO %TIME%

ECHO ::: BLOBLESS+SPARSE CLONE :::
ECHO %TIME%
git clone --filter=blob:none --sparse --no-checkout https://github.com/MicrosoftDocs/azure-docs.ja-jp.git blobless+sparse
ECHO %TIME%

参考情報

• Git clone: データで見るクローンの仕組み - GitHubブログ
• パーシャルクローンとシャロークローンを活用しよう - GitHubブログ

GitHub のように Azure Repos のリポジトリを Visual Studio Code で開く

Visual Studio Code for Web (vscode.dev) が登場したことにより、気軽に Visual Studio Code がオンライン上で使えるようになった。

code.visualstudio.com

しかも、記事の記載にもあるように vscode.dev を URL の先頭に付加することで、Azure Repos のリポジトリも開けるようになった。 詳しくは、@kkamegawa さんの記事を参照。

kkamegawa.hatenablog.jp

が...「GitHub はリポジトリ画面で ". (ピリオド) " を押すだけでエディター画面に遷移してくれるのになぁ」という声が聞こえてきたので、お昼休みの時間を使ってにユーザー スクリプトを書いてみた。

// ==UserScript==
// @name         New Userscript
// @namespace    https://azukipochette.hatenablog.com/
// @version      0.1
// @description  Launch Visual Studio Code Web from Azure DevOps Repos pages.
// @author       AzukiPochette
// @match        https://dev.azure.com/*/_git/*
// @icon         https://www.google.com/s2/favicons?domain=tampermonkey.net
// @grant        none
// ==/UserScript==

(function () {
    'use strict';
    document.addEventListener('keydown', (e) => {
        if (e.code == 'Period') {
            let re = new RegExp('https?://(dev.azure.com/[^?]+)')
            window.location.href = `https://vscode.dev/${re.exec(document.URL)[1]}`
        }
    });
})();

ユーザースクリプトの実行には、使用しているブラウザーに応じた拡張機能が必要となる。
代表的な拡張機能のリンクは以下の通り。（Microsoft Edge + Tempermonkey 向けに実装したが、他の拡張機能でも互換性があるはず）

Microsoft Edge / Google Chrome 向け

www.tampermonkey.net

Mozilla Firefox 向け

addons.mozilla.org

既知の問題

コードを見てもらうと分かるが、以下の問題については対処していない。

• TFVC では実行できない
• 旧バージョンの URL である "<組織名>.visualstudio.com" を使っている場合は動かない
• リポジトリ上でコード編集を動作させた場合、文字として "." すると画面遷移してしまう（機能干渉）*1

Enjoy!

*1:編集時に URL などに編集中だと判断できる明確な特徴がなかったので、諦めた。

PowerShell を使って Markdown を GitHub 風の HTML ファイルに変換する

TL;DR *1

PowerShell 6 以降で、下記のコマンドのように実行すればよい。

$mdfile = 'C:\path\to\yourmarkdownfile.md'
ConvertTo-Html -Body ('<div class="markdown-body">' + (ConvertFrom-Markdown -Path $mdfile).Html + '</div>')  -Head '<link rel="stylesheet" href="https://github.com/sindresorhus/github-markdown-css/blob/main/github-markdown.css">' | Out-File -FilePath out.html

おまけ (雑談)

皆さんは何でメモを書いているだろうか。私は最近もっぱら Markdown である。
Visual Studio Code は標準でプレビュー表示できるし、Pandoc によって Markdown は PowerPoint にも Word ファイルにもなる。
Pandoc は様々なドキュメントを相互に変換する非常に野心的なプロジェクトで、細かい部分で物足りないことも多いが大変便利なツールである。

pandoc.org

だが、実行環境の準備が 辛すぎる 。

私たちが望んでいることは単純明快である。Markdown ファイルを非エンジニアな人に見せて「拡張子 md って何のアプリで開くんですか？」とか「開いたら所々よく分からない文字が書いてあるんだけど」と言わわれずに、誰でも簡単に読めるファイルに変換したいのである。それなのに、HTML ファイルに変換するだけで、(Pandoc の場合) Haskell の環境整備が必要だったり、Markdown Parser なライブラリを使ったツールを作らなければならないなんて 辛すぎる 。

そんなある日、PowerShell の Microsoft Docs を眺めていたら、ConvertFrom-Markdown なるコマンドレットを見つけた。

docs.microsoft.com

しかも、このコマンドレットは PowerShell 6 以降で標準搭載されており、必要なときに気軽に変換できる *2。

更に、この変換は内部的に Markdig という OSS ライブラリを使っているらしく、"Markdown" 仕様だけではなく "CommonMark" 仕様にも対応している。*3
なので、表や注釈といった表現もしっかり変換してくれる。

github.com

ConvertFrom-Markdown は Html プロパティなどを持つオブジェクトを返すが、Html プロパティの中身は Markdown で記述された HTML タグだけを持っている。
最近の Web ブラウザはとても賢いので、そのまま不完全な HTML ファイルとして出力しても表示はできるが、正しい HTML ファイルとして出力するなら次のように記述することになる。

ConvertTo-Html -Body (ConvertFrom-Markdown -Path $mdfile).Html | Out-File -FilePath out.html

これで出力すると HTML ファイルにはなるが、見た目がシンプルすぎて物足りない。
開発者視点で最も見慣れている且つオシャレな Markdown の表示は GitHub だろうということで、GitHub の Markdown のスタイルシートを使うことにする。

とはいっても、GitHub 社は直接 Markdown 用の CSS ファイルを提供していない。だが、同じことを思う人は既にたくさんいて、GitHub のスタイルシートの Markdown 部分を抜いているリポジトリが GitHub 上に公開されている。*4

github.com

このプロジェクトのファイルを直接参照してもよいが、表示は速いに越したことがないので CDN (Content Delivery Network) 上のファイルを使う。今回は Cloudflare 社が提供している cdnjs 上にあるファイルを使用する。

cdnjs.com

では、これをスタイルシートとしてヘッダーに追記すれば終わりか...と思うかもしれないがそうではない。
CSS の中身を見てみると、次のように記載されていることがわかる（一部のみ抜粋）。

.markdown-body details,
.markdown-body figcaption,
.markdown-body figure {
  display: block;
}

.markdown-body summary {
  display: list-item;
}

つまり、markdown-body クラスの範囲になければならない。 ということで、ConvertFrom-Markdown で変換した HTML タグを <div class="markdown-body> と </div> で囲む。
こうして完成したのが、最初に表示した以下のコードである。

$mdfile = 'C:\path\to\yourmarkdownfile.md'
ConvertTo-Html -Body ('<div class="markdown-body">' + (ConvertFrom-Markdown -Path $mdfile).Html + '</div>')  -Head '<link rel="stylesheet" href="https://github.com/sindresorhus/github-markdown-css/blob/main/github-markdown.css">' | Out-File -FilePath out.html

Enjoy!

*1:"Too Long Don't Read" の略で、「長すぎて読めないよ」 というが転じて「要約」として用いられている言葉らしい。

*2:PowerShell を入れなければならないじゃないか、というツッコミは私には聞こえない

*3: 私の記憶による歴史の話 : Markdown は かの John Gruber が作成したものでテキストで見やすくリッチな表現ができるので人気が出た。しかし John Gruber が作った仕様では表現力が物足りないと思ったものたちが「方言(Flavor)」として拡張し始めた。代表的なものに GitHub Flavored Markdown (GFM) がある。このように様々な方言ができたせいで、互換性に問題が出てしまい混乱した。そこで Markdown を標準化するために John Gruber に相談を持ちかけたが、John Gruber は自分が決めた仕様で十分だと取り合わなかったため、Markdown ではなく CommonMark として仕様をまとめたのである。つまり John Gruber 的には Markdown は彼が決めた Markdown であるが、私たちが知っている Markdown は CommonMark な部分も多分に含んでいるということである。曖昧な記憶なので、間違っていたら正解を教えてください。

*4:この記事を記述している時点で 5.8k スター...とんでもない需要だ

開発環境にインストールされている Visual Studio のバージョンをコマンドラインで取得する

Visual Studio 2017 以降のバージョンでは、同一マシンに安全に Visual Studio を複数バージョンインストールことができるようになった一方で、どの場所にどの Visual Studio がインストールされているのかが把握しにくいという新しい管理上の問題を生んでいる。その問題を解決するために提供されているツールが vswhere コマンドである。

vswhere コマンドは、Visual Studio Installer の中にバンドルされているが、GitHub からも入手することができる。

github.com

vswhere を使ってインストールされているバージョンを取得する例を以下に示す。

(& $(Join-Path ${Env:ProgramFiles(x86)} 'Microsoft Visual Studio\Installer\vswhere.exe') -prerelease -format json | ConvertFrom-Json).catalog.productDisplayVersion

実行結果の例を以下に示す。

16.11.5
17.0.0 Preview 6.0

なお、PowerShell で ConvertFrom-Json で変換しなくても -property オプションを指定すれば、指定した情報だけを取得できる。

 & $(Join-Path ${Env:ProgramFiles(x86)} 'Microsoft Visual Studio\Installer\vswhere.exe') -prerelease -property catalog_productDisplayVersion

ただし、この方法の場合、複数のプロパティを取得したいということはできない (そういう "仕様" のようだ)。

github.com

補足

上記の例で、-prelease オプションを付けている理由は、vswhere は既定でリリース済みのプロダクトのみを表示するという仕様になっているためである (未リリースである Visual Studio Preview が表示されない)。
さらに混乱しやすいのが -all オプションで、このオプションは Preview リリースは含まない。-all オプションを付けると不完全なインストールになっているものであっても表示するという意味合いとなる。

Windows Installer (MSI) 形式のファイルをインストールせずに展開する方法

Windows Installer (*.msi 形式) のファイルをインストールせずに展開するには Windows Installer 向けのコマンドライン ツールである msiexec を使用する。

docs.microsoft.com

このツールには管理者用モードと呼ばれる /a オプションがあり、このオプションを使うことで特定の場所に展開することができる。
実行例を以下に示す。

msiexec /a setup.msi targetdir="C:\path\to\extractdir" /qn

WinDbgX をインストールした環境でも旧バージョンの WinDbg を起動したい

WinDbg vNext こと WinDbgX をインストールすると、旧バージョンの WinDbg を起動しても自動的に WinDbgX が起動するようになる。*1

WinDbg を使いたい場合は下記のレジストリを有効にすることで、リダイレクトを止めることができる。

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windbg]
"ShouldRedirectToWinDbgNext"=dword:00000000

*1:正確には、WinDbg.exe がレジストリを確認して、リダイレクトが有効だと WinDbgX を起動して自身は終了する実装になっている