> ## 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.

# repo.headFile()

> Inspect file metadata without downloading the file body.

> [!WARNING]
>
> This page documents the earlier Code Storage SDKs: `@pierre/storage`, `pierre-storage`, and
> `code-storage-go`. New code uses the [Pierre SDK](https://code.storage/docs/sdks.md). To move code to the new SDK, use the
> [`pierre-migrate`
> skill](https://github.com/pierrecomputer/skills/tree/main/skills/pierre-migrate).

```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)
```

## Options

**path** `string` *required*

Path to the file within the repository.

**ref** `string`

Branch name, tag, or commit SHA. Defaults to the default branch.

**ephemeral** `boolean`

When `true`, resolves the ref under the ephemeral namespace.

**ephemeralBase** `boolean`

When `true`, resolves the base branch under the ephemeral namespace. TypeScript: `ephemeralBase`;
Python: `ephemeral_base`; Go: `EphemeralBase`.

**headers.range** `string`

HTTP `Range` header, such as `bytes=0-1023`. TypeScript/Python: `range`; Go: `Range`.

**headers.ifMatch** `string`

HTTP `If-Match` header. TypeScript: `ifMatch`; Python: `if_match`; Go: `IfMatch`.

**headers.ifNoneMatch** `string`

HTTP `If-None-Match` header. TypeScript: `ifNoneMatch`; Python: `if_none_match`; Go:
`IfNoneMatch`.

**headers.ifModifiedSince** `string`

HTTP `If-Modified-Since` header. TypeScript: `ifModifiedSince`; Python: `if_modified_since`; Go:
`IfModifiedSince`.

**headers.ifUnmodifiedSince** `string`

HTTP `If-Unmodified-Since` header. TypeScript: `ifUnmodifiedSince`; Python: `if_unmodified_since`;
Go: `IfUnmodifiedSince`.

**headers.ifRange** `string`

HTTP `If-Range` header. TypeScript: `ifRange`; Python: `if_range`; Go: `IfRange`.

**ttl** `number`

Token TTL in seconds.

## 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.

**status** `number`

HTTP response status. Python: `status_code`; Go: `StatusCode`.

**blobSha** `string`

Blob SHA for the file. Python: `blob_sha`; Go: `BlobSHA`.

**lastCommitSha** `string`

SHA of the most recent commit that modified the file. Python: `last_commit_sha`; Go:
`LastCommitSHA`.

**size** `number`

Content length in bytes when the server provides it.

**etag** `string`

ETag returned by the file endpoint. Go: `ETag`.

**lastModified** `Date | datetime | time.Time`

Parsed `Last-Modified` timestamp. Python: `last_modified`; Go: `LastModified`.

**rawLastModified** `string`

Raw `Last-Modified` header. Python: `raw_last_modified`; Go: `RawLastModified`.

**acceptRanges** `string`

`Accept-Ranges` header, when present. Python: `accept_ranges`; Go: `AcceptRanges`.

**contentRange** `string`

`Content-Range` header, when present. Python: `content_range`; Go: `ContentRange`.

**contentType** `string`

`Content-Type` header, when present. Python: `content_type`; Go: `ContentType`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.