Git その438 - コミットオブジェクトから到達できる最初の参照を表示するコマンドの説明（git describe）

コミットオブジェクトから到達できる最初の参照を表示するコマンドの説明

  「git describe」コマンドは、「コミットオブジェクト」から到達できる最初の参照を表示するコマンドです。


  参照とは「タグ」や「ブランチ」、「HEAD」など、「コミットオブジェクト」を指すものです。
  デフォルトでは、「注釈付きのタグ」のみが検索対象になります。

  参照の検索について 

    まず、検索を開始する「コミットオブジェクト」を指す参照がないかチェックします。
    タグを検索する場合、ユーザーは「軽量タグ」よりも「注釈付きのタグ」を期待するため、「注釈付きのタグ」を優先的に検索します。
    また、より新しい日時に作られたタグを優先します。

    検索を開始する「コミットオブジェクト」を指す参照が見つかれば、ここで検索を終了します。

    検索を開始する「コミットオブジェクト」を指す参照が見つからなかった場合、「親コミットオブジェクト」に向かって検索を行い、参照を検索します。
    参照が見つかれば、その情報を出力して検索を終了します。

コマンドのフォーマット

  コマンドのフォーマットは以下のようになります。


  このコマンドの基本的な使い方は、以下を参考にしてください。

• HEADが指すコミットオブジェクトから到達できる最初の注釈付きのタグを表示する

検索対象に関するオプション

  検索対象に関するオプションです。
  いずれのオプションも省略できます。

  すべての参照を検索対象にする（--all）

    すべての参照を検索対象にします。
   
    このオプションの使用例は、「コミットオブジェクトから到達できる最初の参照を表示する」を参考にしてください。

  タグを検索対象にする（--tags）

    「注釈付きのタグ」と「軽量タグ」を検索対象にします。

    このオプションの使用例は、「コミットオブジェクトから到達できる最初のタグを表示する」を参考にしてください。

  検索対象にする参照を参照名でフィルタリングする（--match）

    検索対象にする参照を参照名でフィルタリングします。
    検索する参照を参照名で絞り込むことができます。

    このオプションの使用例は、「検索対象にする参照を参照名でフィルタリングする」を参考にしてください。

検索に関するオプション

  検索に関するオプションです。
  いずれのオプションも省略できます。

  タグを後方検索する（--contains）

    指定された「コミットオブジェクト」から後方に向かってタグを検索します。

    このオプションの使用例は、「指定されたコミットオブジェクトから後方に向かってタグを検索する」を参考にしてください。

  検索するタグの候補数を指定する（--candidates）

    検索するタグの候補数を指定します。
   
    このオプションの使用例は、「検索するタグの候補数を指定して、コミットオブジェクトから到達できる最初の注釈付きタグを表示する」を参考にしてください。

  検索を開始するコミットオブジェクトの指定（commit-ish）

    検索を開始する「コミットオブジェクト」を指定します。

    このオプションの使用例は、「検索を開始するコミットオブジェクトの指定して、コミットオブジェクトから到達できる最初の注釈付きタグを表示する」を参考にしてください。

  指定したコミットオブジェクトを指す参照を検索する（--exact-match） 

    指定した「コミットオブジェクト」を指す参照を検索します。
    
    このオプションの使用例は、「指定したコミットオブジェクトを指す参照を検索する」を参考にしてください。

  常に最初の親コミットオブジェクトを辿って検索する（--first-parent）

    常に最初の「親コミットオブジェクト」を辿って検索します。
    「マージコミット」では、複数の「親コミットオブジェクト」が存在します。
    このオプションを指定すると、「マージ」した側の「親コミットオブジェクト」のみを辿って検索するようになります。
    
    このオプションの使用例は、「マージされた側の親コミットオブジェクトのみを辿って検索する」を参考にしてください。

情報の出力に関するオプション

  情報の出力に関するオプションです。
  いずれのオプションも省略できます。

  コミットオブジェクトの識別子の文字数を指定する（--abbrev）

    結果に表示する「コミットオブジェクト」の識別子の文字数を指定します。

    このオプションの使用例は、「コミットオブジェクトの識別子の文字数を指定して、コミットオブジェクトから到達できる最初の注釈付きのタグを表示する」を参考にしてください。

  ワーキングツリーがダーティーな時に出力結果にサフックスを追加する（--dirty）

    「ワーキングツリー」の状態が「ダーティー」な時に出力結果にサフックスを追加します。

    このオプションの使用例は、「ワーキングツリーがダーティーな時に出力結果にサフックスを追加して、コミットオブジェクトから到達できる最初の注釈付きのタグを表示する」を参考にしてください。

  検索過程を出力する（--debug）

    検索過程を出力します。

    このオプションの使用例は、「検索過程を出力して、コミットオブジェクトから到達できる最初の注釈付きのタグを表示する」を参考にしてください。

  常にロングフォーマットで表示する（--long）

    常にロングフォーマットで表示します。

    このオプションの使用例は、「コミットオブジェクトから到達できる最初の注釈付きのタグをロングフォーマットで表示する」を参考にしてください。

  参照が見つからなかった時に、コミットオブジェクトの識別子のみを表示する（--always）

    参照が見つからなかった時に、コミットオブジェクトの識別子のみを表示します。
    デフォルトでは、参照が見つからなかった時にエラーメッセージが表示されます。

    このオプションの使用例は、「参照が見つからなかった時に、コミットオブジェクトの識別子のみを表示する」を参考にしてください。