> ## Documentation Index
> Fetch the complete documentation index at: https://code.storage/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# headFile()

> Inspect file metadata without downloading the file body.

<CodeGroup>
  ```typescript TypeScript theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  const metadata = await repo.headFile({
    path: 'README.md',
    ref: 'main',
  });
  console.log(metadata.status, metadata.etag, metadata.size, metadata.lastCommitSha);

  const ranged = await repo.headFile({
    path: 'README.md',
    headers: { range: 'bytes=0-1023' },
  });
  console.log(ranged.status, ranged.contentRange);

  const cached = await repo.headFile({
    path: 'README.md',
    headers: { ifNoneMatch: '"abc123"' },
  });
  console.log(cached.status);
  ```

  ```python Python theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  metadata = await repo.head_file(
      path="README.md",
      ref="main",
  )
  print(metadata["status_code"], metadata.get("etag"), metadata.get("size"))

  ranged = await repo.head_file(
      path="README.md",
      headers={"range": "bytes=0-1023"},
  )
  print(ranged["status_code"], ranged.get("content_range"))

  cached = await repo.head_file(
      path="README.md",
      headers={"if_none_match": '"abc123"'},
  )
  print(cached["status_code"])
  ```

  ```go Go theme={null} theme={"theme":{"light":"github-light","dark":"min-dark"}}
  metadata, err := repo.HeadFile(context.Background(), storage.HeadFileOptions{
  	Path: "README.md",
  	Ref:  "main",
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(metadata.StatusCode, metadata.ETag, metadata.Size)

  ranged, err := repo.HeadFile(context.Background(), storage.HeadFileOptions{
  	Path: "README.md",
  	Headers: storage.FileRequestHeaders{
  		Range: "bytes=0-1023",
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(ranged.StatusCode, ranged.ContentRange)

  cached, err := repo.HeadFile(context.Background(), storage.HeadFileOptions{
  	Path: "README.md",
  	Headers: storage.FileRequestHeaders{
  		IfNoneMatch: `"abc123"`,
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(cached.StatusCode)
  ```
</CodeGroup>

## Options

<ParamField path="path" type="string" required>
  Path to the file within the repository.
</ParamField>

<ParamField path="ref" type="string">
  Branch name, tag, or commit SHA. Defaults to the default branch.
</ParamField>

<ParamField path="ephemeral" type="boolean">
  When `true`, resolves the ref under the ephemeral namespace.
</ParamField>

<ParamField path="ephemeralBase" type="boolean">
  When `true`, resolves the base branch under the ephemeral namespace. TypeScript: `ephemeralBase`;
  Python: `ephemeral_base`; Go: `EphemeralBase`.
</ParamField>

<ParamField path="headers.range" type="string">
  HTTP `Range` header, such as `bytes=0-1023`. TypeScript/Python: `range`; Go: `Range`.
</ParamField>

<ParamField path="headers.ifMatch" type="string">
  HTTP `If-Match` header. TypeScript: `ifMatch`; Python: `if_match`; Go: `IfMatch`.
</ParamField>

<ParamField path="headers.ifNoneMatch" type="string">
  HTTP `If-None-Match` header. TypeScript: `ifNoneMatch`; Python: `if_none_match`; Go:
  `IfNoneMatch`.
</ParamField>

<ParamField path="headers.ifModifiedSince" type="string">
  HTTP `If-Modified-Since` header. TypeScript: `ifModifiedSince`; Python: `if_modified_since`; Go:
  `IfModifiedSince`.
</ParamField>

<ParamField path="headers.ifUnmodifiedSince" type="string">
  HTTP `If-Unmodified-Since` header. TypeScript: `ifUnmodifiedSince`; Python: `if_unmodified_since`;
  Go: `IfUnmodifiedSince`.
</ParamField>

<ParamField path="headers.ifRange" type="string">
  HTTP `If-Range` header. TypeScript: `ifRange`; Python: `if_range`; Go: `IfRange`.
</ParamField>

<ParamField path="ttl" type="number">
  Token TTL in seconds.
</ParamField>

## Response

`headFile()` returns parsed metadata from `HEAD /repos/file`. Range and conditional outcomes with
status `206`, `304`, `412`, and `416` are surfaced as SDK results.

<ResponseField name="status" type="number">
  HTTP response status. Python: `status_code`; Go: `StatusCode`.
</ResponseField>

<ResponseField name="blobSha" type="string">
  Blob SHA for the file. Python: `blob_sha`; Go: `BlobSHA`.
</ResponseField>

<ResponseField name="lastCommitSha" type="string">
  SHA of the most recent commit that modified the file. Python: `last_commit_sha`; Go:
  `LastCommitSHA`.
</ResponseField>

<ResponseField name="size" type="number">
  Content length in bytes when the server provides it.
</ResponseField>

<ResponseField name="etag" type="string">
  ETag returned by the file endpoint. Go: `ETag`.
</ResponseField>

<ResponseField name="lastModified" type="Date | datetime | time.Time">
  Parsed `Last-Modified` timestamp. Python: `last_modified`; Go: `LastModified`.
</ResponseField>

<ResponseField name="rawLastModified" type="string">
  Raw `Last-Modified` header. Python: `raw_last_modified`; Go: `RawLastModified`.
</ResponseField>

<ResponseField name="acceptRanges" type="string">
  `Accept-Ranges` header, when present. Python: `accept_ranges`; Go: `AcceptRanges`.
</ResponseField>

<ResponseField name="contentRange" type="string">
  `Content-Range` header, when present. Python: `content_range`; Go: `ContentRange`.
</ResponseField>

<ResponseField name="contentType" type="string">
  `Content-Type` header, when present. Python: `content_type`; Go: `ContentType`.
</ResponseField>