### Install and Run Development Server

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/examples/react-wasm/README.md

Use these commands to install project dependencies and start the development server for the React WASM example.

```bash
npm install
npm run dev
```

--------------------------------

### Development Setup

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/README.md

Standard commands for setting up the development environment for Icechunk JS. Includes installation, building, and testing.

```bash
cd icechunk-js
yarn install
yarn build
yarn test
```

--------------------------------

### Install Dependencies

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/examples/node-cli/README.md

Run this command to install project dependencies before using the CLI.

```bash
npm install
```

--------------------------------

### Vite WASM Setup with npm

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/icechunk-js.md

Install necessary plugins for using the WASM build with Vite. This setup is required for bundlers like Vite to handle WASM modules correctly.

```bash
npm install vite-plugin-wasm vite-plugin-top-level-await
```

--------------------------------

### Start MkDocs Development Server

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Run this command to start the MkDocs development server with live reload enabled. The server will be accessible at http://127.0.0.1:8000.

```bash
just docs-serve
```

--------------------------------

### Setup Benchmark Datasets

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/benchmarks/README.md

Run this command to create benchmark datasets. Use `--force-setup=False` to avoid re-creating datasets if possible.

```sh
pytest -nauto -m setup_benchmarks benchmarks/
```

```sh
pytest -nauto -m setup_benchmarks --force-setup=False benchmarks/
```

--------------------------------

### Install Pre-commit

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Install the pre-commit tool using pip. This is a prerequisite for using the pre-commit hooks.

```bash
pip install pre-commit
```

--------------------------------

### Install Icechunk for Default Platform

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/icechunk-js.md

Installs the @earthmover/icechunk package and zarrita for your default platform.

```bash
npm install @earthmover/icechunk zarrita
```

--------------------------------

### Install Dev Dependencies with uv

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/CONTRIBUTING.md

Installs all development dependencies, including test dependencies, mypy, ruff, and maturin, using uv.

```bash
docker compose up -d

uv sync
```

--------------------------------

### Install Just Command Runner

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Install the 'just' command runner, used for build tasks and pre-commit hooks in the Rust development workflow. Installation methods vary by package manager.

```bash
cargo install just
```

--------------------------------

### Install Icechunk using pip

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/getting-started/quickstart.md

Install the Icechunk library using pip. This is the standard method for Python package installation.

```bash
python -m pip install icechunk
```

--------------------------------

### Install VirtualiZarr, Icechunk, and fsspec

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/virtual.md

Install the necessary libraries for creating and managing virtual datasets with Icechunk. Ensure you are using version 2.4.0 or later for VirtualiZarr.

```shell
pip install "virtualizarr>=2.4.0" icechunk fsspec s3fs
```

--------------------------------

### Benchmark Write Performance with Hyperfine

Source: https://github.com/earth-mover/icechunk/blob/main/design-docs/008-no-copy-serialization-formats.md

This command benchmarks the write performance of the `multithreaded_get_chunk_refs` example using `hyperfine`. It includes setup to clean the target directory and specifies one warmup run.

```sh
nix run nixpkgs#hyperfine -- \
  --prepare 'rm -rf /tmp/test-perf' \
  --warmup 1 \
  'cargo run --release --example multithreaded_get_chunk_refs -- --write /tmp/test-perf'
```

--------------------------------

### Install Pre-commit Git Hooks

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Install the pre-commit git hooks. This ensures that checks are run automatically before each commit.

```bash
pre-commit install
```

--------------------------------

### Create Initial Experiment Structure

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/moving-nodes.md

Initializes a repository and creates a group for an experiment, including arrays for results and configuration. This setup is used to demonstrate moving a group with its children.

```python
repo = ic.Repository.create(ic.in_memory_storage())
session = repo.writable_session("main")
root = zarr.group(session.store)
root.create_group("experiments/exp001")
root.create_array("experiments/exp001/results", shape=(10,), dtype="f4")
root.create_array("experiments/exp001/config", shape=(5,), dtype="i4")
session.commit("Create experiment")

print("Before:")
print(root.tree())
```

--------------------------------

### Docker Compose for Object Store Testing

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Start local S3 and Azure compatible object stores using Docker Compose. Run this command from the repository root to start containers in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Create Default RepositoryConfig

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/configuration.md

Instantiate a `RepositoryConfig` object with default settings. This is a convenient starting point for configuring a new repository.

```python
import icechunk as ic

config = ic.config.RepositoryConfig.default()
```

--------------------------------

### Install Icechunk and Virtualizarr

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/zarr.md

Install the necessary libraries for virtual ingestion. Ensure you have `virtualizarr` version 2.5.1 or later for full compatibility, especially with sharded v3 arrays.

```shell
pip install "virtualizarr>=2.5.1" icechunk
```

--------------------------------

### Development Setup for WASM Target

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/README.md

Commands for building and testing the WASM target during development. Requires specific environment variables and tools like LLVM.

```bash
# Requires brew install llvm and env vars (see docs/docs/contributing.md)
yarn build --target wasm32-wasip1-threads
NAPI_RS_FORCE_WASI=1 yarn test
```

--------------------------------

### Load and Split Xarray Tutorial Data

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/xarray.md

Download the RASM tutorial dataset from Xarray and split it into two parts for separate storage. Requires 'pooch' and 'netCDF4' to be installed.

```python
ds = xr.tutorial.open_dataset('rasm')

ds1 = ds.isel(time=slice(None, 18))  # part 1
ds2 = ds.isel(time=slice(18, None))  # part 2
```

--------------------------------

### Pre-commit Hooks - Full CI Checks

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Run the full Continuous Integration checks, which include all tests and examples. This is the most comprehensive check.

```bash
just pre-commit-ci
```

--------------------------------

### Create and Commit to In-Memory Repository

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/README.md

Example of creating a new in-memory repository, a writable session, and committing changes using the zarrita library.

```typescript
import { Repository, Storage } from '@earthmover/icechunk'
import * as zarr from 'zarrita'

const storage = await Storage.newInMemory()
const repo = await Repository.create(storage)

const session = await repo.writableSession('main')
const store = session.store

// zarrita uses the store directly via duck-typing
const root = zarr.root(store)
const arr = await zarr.create(root.resolve('/foo'), {
    shape: [100], dtype: '<i4', chunks: [10],
})

const snapshotId = await session.commit('Create foo array')
```

--------------------------------

### Configure Preloading with OR Conditions

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/performance.md

Combine multiple preload conditions using `ManifestPreloadCondition.or_conditions`. This example preloads manifests matching the name "x" OR whose path contains "y".

```python
preload_config = ic.config.ManifestPreloadConfig(
    preload_if=ic.config.ManifestPreloadCondition.or_conditions(
        [
            ic.config.ManifestPreloadCondition.name_matches("^x$"),
            ic.config.ManifestPreloadCondition.path_matches("y"),
        ]
    ),
)
```

--------------------------------

### Configure Mold Linker for Faster Builds

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

On Linux, configure your Cargo configuration to use the mold linker for significantly faster incremental builds. This requires installing mold first.

```toml
[target.x86_64-unknown-linux-gnu]
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

[target.aarch64-unknown-linux-gnu]
rustflags = ["-C", "link-arg=-fuse-ld=mold"]
```

--------------------------------

### Configure Manifest Preloading by Name

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/performance.md

Use `ManifestPreloadConfig` to specify the `ic.RepositoryConfig.manifest.preload` field. This example preloads manifests whose names match the regex "^x$".

```python
preload_config = ic.config.ManifestPreloadConfig(
    preload_if=ic.config.ManifestPreloadCondition.name_matches("^x$"),  # preload all manifests with the name "x"
)

repo_config = ic.config.RepositoryConfig(
    manifest=ic.config.ManifestConfig(
        preload=preload_config,
    )
)
```

--------------------------------

### Build Documentation

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/README.md

Execute this command to build the static documentation files. The output will be placed in the `docs/.site` directory.

```bash
pixi run docs-build
```

--------------------------------

### Initialize Icechunk Store and Repository

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/dask.md

Set up a local filesystem storage and create a new Icechunk repository. This is the initial step before performing any writes.

```python
import icechunk as ic
import tempfile

# initialize the icechunk store
storage = ic.local_filesystem_storage(tempfile.TemporaryDirectory().name)
repo = ic.Repository.create(storage)
session = repo.writable_session("main")
```

--------------------------------

### Get Icechunk User Agent String

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/understanding/faq.md

Retrieve the exact user agent string for your installed Icechunk version. This header is automatically set and cannot be overridden.

```python
import icechunk
icechunk.user_agent()
# 'icechunk-rust-2.0.0'
```

--------------------------------

### Create and Open Icechunk Repositories

Source: https://context7.com/earth-mover/icechunk/llms.txt

Demonstrates creating new repositories or opening existing ones on various storage backends like S3, GCS, Azure Blob Storage, and local file systems. Also shows opening a repository over HTTP for read-only access.

```python
import icechunk as ic
import zarr

# --- Create on S3 (credentials from environment) ---
storage = ic.s3_storage(bucket="my-bucket", prefix="datasets/climate", from_env=True)
repo = ic.Repository.create(storage)

# --- Create on GCS ---
storage = ic.gcs_storage(bucket="my-bucket", prefix="datasets/climate", from_env=True)
repo = ic.Repository.create(storage)

# --- Create on Azure Blob Storage ---
storage = ic.azure_storage(
    account_name="myaccount",
    container="my-container",
    prefix="datasets/climate",
    account_key="my-account-key",
)
repo = ic.Repository.create(storage)

# --- Create on local filesystem ---
storage = ic.local_filesystem_storage("/data/my-repo")
repo = ic.Repository.create(storage)

# --- In-memory (for testing only) ---
repo = ic.Repository.create(ic.in_memory_storage())

# --- Open an existing repo ---
repo = ic.Repository.open(ic.s3_storage(bucket="my-bucket", prefix="datasets/climate", from_env=True))

# --- Open over HTTP (read-only) ---
repo = ic.Repository.open(ic.http_storage("https://example.com/path/to/repo"))
```

--------------------------------

### Test with Upstream Development Dependencies

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Install nightly wheels for upstream packages (zarr, xarray, dask, distributed) using uv by setting specific environment variables and index strategies. Then run the test suite.

```bash
export UV_INDEX="https://pypi.anaconda.org/scientific-python-nightly-wheels/simple/"
export UV_PRERELEASE=allow
uv sync --group test \
  --resolution highest \
  --index-strategy unsafe-best-match

# Run tests
uv run pytest
```

--------------------------------

### Install Cargo-Deny

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Install 'cargo-deny', a tool used for code quality checks in the Rust development workflow. It can be installed using 'cargo install'.

```bash
cargo install cargo-deny
```

--------------------------------

### Initialize icechunk Repository

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/index.md

Demonstrates how to import the icechunk package and create a Repository instance using an S3 storage backend. The `from_env=True` argument indicates that credentials should be loaded from environment variables.

```python
import icechunk as ic

# Top-level: Repository, storage factories, exceptions, utilities
repo = ic.Repository.create(ic.s3_storage(bucket="my-bucket", prefix="my-prefix", from_env=True))

# Submodules for everything else
config = ic.config.RepositoryConfig(...)
solver = ic.conflicts.BasicConflictSolver(...)
```

--------------------------------

### Zarr Key Examples

Source: https://github.com/earth-mover/icechunk/blob/main/README.md

Illustrates the typical keys generated by Zarr for metadata and chunk data in a hierarchical store structure. These keys map directly to files or object keys in standard Zarr implementations.

```text
mygroup/zarr.json
mygroup/myarray/zarr.json
mygroup/myarray/c/0/0
mygroup/myarray/c/0/1
```

--------------------------------

### Install Cargo-Nextest

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Install 'cargo-nextest', a tool used for running tests in the Rust development workflow. Installation can be done via 'cargo install' or package managers.

```bash
cargo install cargo-nextest
```

--------------------------------

### Initialize Repository and Add Data

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/understanding/version-control.md

Set up a new Icechunk repository, add attributes to the root group, and create a dataset. This serves as a base for demonstrating conflict resolution.

```python
import icechunk as ic
import numpy as np
import zarr

repo = ic.Repository.create(ic.in_memory_storage())
session = repo.writable_session("main")
root = zarr.create_group(session.store)
root.attrs["foo"] = "bar"
root.create_dataset("data", shape=(10, 10), chunks=(1, 1), dtype=np.int32)
print(session.commit(message="Add foo attribute and data array"))
```

--------------------------------

### Install Icechunk using conda

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/getting-started/quickstart.md

Install the Icechunk library using conda, typically from the conda-forge channel. This is an alternative installation method.

```bash
conda install -c conda-forge icechunk
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/README.md

Run this command to serve the documentation locally. Use the `--dirty` flag to only rebuild changed files, though a restart might be needed for changes in `mkdocs.yaml`.

```bash
pixi run docs-serve
```

--------------------------------

### Install Icechunk Explicitly for WASM

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/icechunk-js.md

Installs the @earthmover/icechunk package with WASM architecture and zarrita.

```bash
npm install @earthmover/icechunk --cpu=wasm32 zarrita
```

--------------------------------

### Create Icechunk Repository (Local)

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/xarray.md

Set up a temporary directory for local file system storage and create an Icechunk repository.

```python
import tempfile
storage_config = ic.local_filesystem_storage(tempfile.TemporaryDirectory().name)
repo = ic.Repository.create(storage_config)
```

--------------------------------

### Create Repository and Write Data

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/icechunk-js.md

Demonstrates how to create an in-memory repository, open a writable session, and write data to a Zarr array.

```APIDOC
## Create Repository and Write Data

### Description
Creates an in-memory repository, opens a writable session on the main branch, and writes data to a Zarr array. Finally, it commits the changes.

### Method
```typescript
Repository.create(storage: Storage)
repository.writableSession(branch: string)
zarr.root(store: Store)
zarr.create(parent: Group | Root, options?: CreateOptions)
zarr.set(array: Array, selection: Selection | null, value: SetValue)
session.commit(message: string)
```

### Parameters

#### `Repository.create`
- **storage** (Storage) - The storage backend to use for the repository.

#### `writableSession`
- **branch** (string) - The name of the branch to open a writable session on.

#### `zarr.create` (for group)
- **parent** (Group | Root) - The parent group or root to create the new group within.
- **options** (CreateOptions) - Optional configuration for creating the group.

#### `zarr.create` (for array)
- **parent** (Group | Root) - The parent group or root to create the new array within.
- **options** (CreateOptions) - Configuration for creating the array, including shape, chunk_shape, and data_type.

#### `zarr.set`
- **array** (Array) - The Zarr array to write data to.
- **selection** (Selection | null) - The slice or indices to write data to. `null` writes to the entire array.
- **value** (SetValue) - An object containing the data to write, along with its shape and stride.

#### `session.commit`
- **message** (string) - A message describing the commit.

### Request Example
```typescript
import { Repository, Storage } from '@earthmover/icechunk'
import * as zarr from 'zarrita'

// Create an in-memory repository
const storage = await Storage.newInMemory()
const repo = await Repository.create(storage)

// Open a writable session on the main branch
const session = await repo.writableSession('main')
const store = session.store
const root = zarr.root(store)

// Create a root group
const group = await zarr.create(root)

// Create a float32 array
const arr = await zarr.create(root.resolve('/temperature'), {
  shape: [4],
  chunk_shape: [4],
  data_type: 'float32',
})

// Write data
await zarr.set(arr, null, {
  data: new Float32Array([1.5, 2.5, 3.5, 4.5]),
  shape: [4],
  stride: [1],
})

// Commit changes
const snapshotId = await session.commit('Add temperature array')
```

### Response

#### Success Response
- **snapshotId** (string) - The ID of the newly created commit snapshot.

#### Response Example
```json
{
  "snapshotId": "<commit-hash>"
}
```
```

--------------------------------

### Initialize Icechunk Repository and Session

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/understanding/parallel.md

Sets up an Icechunk repository using a temporary directory and creates a writable session for the 'main' branch. This is the initial step before performing any writes.

```python
import xarray as xr
import tempfile
import icechunk as ic

ds = xr.tutorial.open_dataset("rasm").isel(time=slice(24))
repo = ic.Repository.create(ic.local_filesystem_storage(tempfile.TemporaryDirectory().name))
session = repo.writable_session("main")
```

--------------------------------

### Install Xarray

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/xarray.md

Ensure Xarray version 2025.1.1 or higher is installed for compatibility with Icechunk.

```shell
pip install "xarray>=2025.1.1"
```

--------------------------------

### Create Repository and Initial Structure

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/moving-nodes.md

Sets up an in-memory repository, creates a writable session, and initializes a Zarr group with an array containing random data. This is a prerequisite for demonstrating node operations.

```python
import icechunk as ic
import zarr
import numpy as np

# Create a repository with some data
repo = ic.Repository.create(ic.in_memory_storage())
session = repo.writable_session("main")
root = zarr.group(session.store)
root.create_group("data/raw")
arr = root.create_array("data/raw/temperature", shape=(100,), dtype="f4")
arr[:] = np.random.randn(100)
session.commit("Initial structure")

print("Before:")
print(root.tree())
```

--------------------------------

### Open Repository with Preload Configuration

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/performance.md

Pass the configured `RepositoryConfig` to `Repository.open` or `Repository.create` to apply the preload settings.

```python
repo = ic.Repository.open(..., config=repo_config)
```

--------------------------------

### Install Dev Dependencies with pip

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/CONTRIBUTING.md

Installs maturin and development dependencies, including test, mypy, and ruff, using pip.

```bash
pip install maturin
pip install --group dev
```

--------------------------------

### Compare Benchmarks Across Multiple Stores

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/benchmarks/README.md

Run a specific benchmark (`test_write_simple`) and compare its performance across multiple storage backends (s3, s3_ob, gcs). The `--skip-setup` flag prevents re-running the setup process.

```sh
python benchmarks/runner.py --skip-setup --pytest '-k test_write_simple' --where 's3|s3_ob|gcs' main
```

--------------------------------

### Install Icechunk JS with WASM

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/README.md

Install the package with the `--cpu=wasm32` flag to obtain the WASM binary. This is required for browser usage.

```bash
npm install @earthmover/icechunk --cpu=wasm32
```

--------------------------------

### Install Icechunk JS

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/README.md

Install the Icechunk JS library using npm. For browser usage with WASM, specify the wasm package.

```bash
npm install @earthmover/icechunk@alpha
```

--------------------------------

### Create Repository with Default Config

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/performance.md

Initializes a new repository with a default manifest splitting configuration. Note that any config passed to Repository.create is persisted to disk.

```python
repo = ic.Repository.create(storage, config=repo_config)
```

--------------------------------

### Storage Backends (Node.js)

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/icechunk-js.md

Illustrates how to initialize various storage backends for Node.js environments, including local filesystem, S3, GCS, Azure Blob Storage, R2, Tigris, and HTTP.

```APIDOC
## Storage Backends (Node.js)

### Description
This section details the initialization of different storage backends available in Node.js environments. These include local file system access, cloud object storage services, and network-based storage.

### Methods

#### `Storage.newLocalFilesystem`
- **path** (string) - The root path for the local filesystem repository.

#### `Storage.newS3`
- **bucket** (string) - The name of the S3 bucket.
- **prefix** (string) - The prefix within the bucket to use for the repository.
- **credentials** (object) - AWS credentials.
- **options** (object) - Optional S3 configuration.

#### `Storage.newGcs`
- **bucket** (string) - The name of the GCS bucket.
- **prefix** (string) - The prefix within the bucket to use for the repository.
- **credentials** (object) - Google Cloud credentials.
- **config** (object) - Optional GCS configuration.

#### `Storage.newAzureBlob`
- **account** (string) - The Azure storage account name.
- **container** (string) - The name of the blob container.
- **prefix** (string) - The prefix within the container to use for the repository.
- **credentials** (object) - Azure credentials.
- **config** (object) - Optional Azure Blob Storage configuration.

#### `Storage.newR2`
- **bucket** (string) - The name of the R2 bucket.
- **prefix** (string) - The prefix within the bucket to use for the repository.
- **accountId** (string) - The Cloudflare account ID.
- **credentials** (object) - R2 credentials.
- **options** (object) - Optional R2 configuration.

#### `Storage.newTigris`
- **bucket** (string) - The name of the Tigris bucket (if applicable).
- **prefix** (string) - The prefix within the bucket to use for the repository.
- **credentials** (object) - Tigris credentials.
- **options** (object) - Optional Tigris configuration.

#### `Storage.newHttp`
- **url** (string) - The base URL for the read-only HTTP repository.

### Request Example
```typescript
import { Storage } from '@earthmover/icechunk'

// Local filesystem
const local = await Storage.newLocalFilesystem('/path/to/repo')

// Amazon S3
const s3 = Storage.newS3('my-bucket', 'my-prefix', credentials, options)

// Google Cloud Storage
const gcs = Storage.newGcs('my-bucket', 'my-prefix', credentials, config)

// Azure Blob Storage
const azure = await Storage.newAzureBlob('account', 'container', 'prefix', credentials, config)

// Cloudflare R2
const r2 = Storage.newR2('my-bucket', 'my-prefix', accountId, credentials, options)

// Tigris
const tigris = Storage.newTigris('my-bucket', 'my-prefix', credentials, options)

// HTTP (read-only)
const http = Storage.newHttp('https://example.com/repo')
```
```

--------------------------------

### VCC Configuration Example

Source: https://github.com/earth-mover/icechunk/blob/main/design-docs/014-virtual-chunk-ref-efficiency.md

Example of how a Virtual Chunk Container (VCC) is defined in the repository configuration, including its name, URL prefix, and store details.

```yaml
  s3:
    name: my-virtual-icechunk
    url_prefix: s3://testbucket/my-repo/chunks
    store: !s3_compatible
      region: us-east-1
      anonymous: false
```

--------------------------------

### Initialize Icechunk Repository

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/ingestion/glad-ingest.ipynb

Create a new Icechunk repository. This is the first step in setting up the storage for your data.

```python
import icechunk as ic

repo = ic.Repository.create(storage)
```

--------------------------------

### Repository Creation

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/index.md

Demonstrates how to create a new Repository instance using a storage factory, such as S3 storage, and configure it to load credentials from environment variables.

```APIDOC
## `icechunk.Repository.create`

### Description
Creates a new repository instance with the specified storage backend.

### Method
`Repository.create(storage)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import icechunk as ic

# Example using S3 storage
repo = ic.Repository.create(ic.s3_storage(bucket="my-bucket", prefix="my-prefix", from_env=True))
```

### Response
#### Success Response (200)
- **Repository** (object) - An instance of the Repository class.
```

--------------------------------

### Install Renamed Icechunk v1 with Pixi

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Use pixi to synchronize development dependencies, including installing a renamed version of icechunk v1 for cross-version compatibility testing.

```bash
pixi run third-wheel sync -v
```

--------------------------------

### Build Static MkDocs Site

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Execute this command to build the static version of the documentation site. The output will be placed in the `docs/.site` directory.

```bash
just docs-build
```

--------------------------------

### Create and Write to Icechunk Store

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/CONTRIBUTING.md

Demonstrates how to create a new icechunk repository, open a writable session, and create a zarr array within the store.

```python
from icechunk import Repository, IcechunkStore, StorageConfig
from zarr import Array, Group

storage = StorageConfig.memory("test")
repo = Repository.open_or_create(storage=storage)

# create a session for writing to the store
session = repo.writable_session(branch="main")

root = Group.from_store(store=session.store(), zarr_format=zarr_format)
foo = root.create_array("foo", shape=(100,), chunks=(10,), dtype="i4")
```

--------------------------------

### Install Renamed Icechunk v1 with uv

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/contributing.md

Navigate to 'icechunk-python' and use uv to synchronize development dependencies, including installing a renamed version of icechunk v1 for cross-version compatibility testing.

```bash
cd icechunk-python
uv run third-wheel sync -v
```

--------------------------------

### Open Repository with Custom Manifest Splitting

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/performance.md

Opens an existing repository with a new manifest splitting configuration where 5 chunk references are grouped into a single manifest. The repository's manifest configuration is then printed.

```python
split_config = ic.config.ManifestSplittingConfig.from_dict(
    {ic.config.ManifestSplitCondition.AnyArray(): {ic.config.ManifestSplitDimCondition.Any(): 5}}
)
repo_config = ic.config.RepositoryConfig(manifest=ic.config.ManifestConfig(splitting=split_config))
new_repo = ic.Repository.open(storage, config=repo_config)
print(new_repo.config.manifest)
```

--------------------------------

### Set up Object Store Registry

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/virtual.md

Create an ObjectStoreRegistry with an obstore store for accessing remote S3 buckets. Specify the bucket URL and region.

```python
from obstore.store import from_url
from obspec_utils.registry import ObjectStoreRegistry

bucket = "s3://noaa-cdr-sea-surface-temp-optimum-interpolation-pds/"
store = from_url(bucket, region="us-east-1", skip_signature=True)
registry = ObjectStoreRegistry({bucket: store})
```

--------------------------------

### Rolling Time Window Example

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/moving-chunks.md

Conceptual example of implementing a rolling time window for sensor data. It outlines the steps to discard the oldest day's data and make room for new readings using `shift_array`.

```python
arr = zarr.open_array(store=session.store, path="sensors/temperature")
chunk_offset = (-1,)

# Compute the element-space shift from the chunk offset and chunk shape
element_shift = tuple(o * c for o, c in zip(chunk_offset, arr.chunks))
# element_shift = (-24,) — the shift in element space

# Shift left by 1 chunk, discarding the oldest
session.shift_array("/sensors/temperature", chunk_offset)
```

--------------------------------

### Open a Repository Instance

Source: https://github.com/earth-mover/icechunk/blob/main/design-docs/003-python-instantiation-api.md

Class method to open an existing repository. Requires object store configuration and optionally accepts store credentials, repository configuration, and virtual chunk credentials.

```python
from typing import Mapping

# Assuming ObjectStoreConfig and ObjectStoreCredentials are defined elsewhere

class Repository:
    @classmethod
    def open(
        store: ObjectStoreConfig,
        store_credentials: ObjectStoreCredentials = FromEnvCredentials,
        config: RepositoryConfig | None = None,
        virtual_chunk_credentials: Mapping[str, ObjectStoreCredentials] | None = None
    ) -> Repository:
      ... 
```

--------------------------------

### supported_spec_versions

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/index.md

Lists all specification versions that the current icechunk installation supports.

```APIDOC
## `icechunk.supported_spec_versions`

### Description
Lists supported spec versions.

### Method
`supported_spec_versions()`

### Parameters
None

### Request Example
```python
import icechunk as ic

versions = ic.supported_spec_versions()
print(versions)
```

### Response
#### Success Response (200)
- **versions** (list[str]) - A list of supported spec version strings.
```

--------------------------------

### Create a Branch

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/getting-started/howto.md

Create a new branch starting from a specific snapshot ID.

```python
repo.create_branch("dev", snapshot_id=snapshot_id)
```

--------------------------------

### Create Icechunk Repository

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/examples/node-cli/README.md

Use this command to create a new Icechunk repository with sample data.

```bash
node --experimental-strip-types main.ts create ./my-repo
```

--------------------------------

### Get Repository Configuration Property

Source: https://github.com/earth-mover/icechunk/blob/main/design-docs/003-python-instantiation-api.md

Property to access the current runtime configuration of the repository.

```python
@property
    def config(self) -> RepositoryConfig:
      ... 
```

--------------------------------

### Distributed Writes with Multiprocessing

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/understanding/parallel.md

This Python script demonstrates how to perform distributed writes to an icechunk repository using the `multiprocessing` module. It sets the start method to 'forkserver' to avoid deadlocks and includes a worker function that retries writes upon encountering `ConflictError`. The main function initializes the repository and dataset, starts worker processes, and then verifies the results.

```python
import multiprocessing as mp
import icechunk as ic
import zarr
import tempfile

def get_storage():
    return ic.local_filesystem_storage(tempfile.TemporaryDirectory().name)

def worker(i):
    print(f"Stated worker {i}")
    storage = get_storage()
    repo = ic.Repository.open(storage)
    # keep trying until it succeeds
    while True:
        try:
            session = repo.writable_session("main")
            z = zarr.open(session.store, mode="r+")
            print(f"Opened store for {i} | {dict(z.attrs)}")
            a = z.attrs.get("done", [])
            a.append(i)
            z.attrs["done"] = a
            session.commit(f"wrote from worker {i}")
            break
        except ic.ConflictError:
            print(f"Conflict for {i}, retrying")
            pass

def main():
    # This is necessary on linux systems
    mp.set_start_method('forkserver')
    storage = get_storage()
    repo = ic.Repository.create(storage)
    session = repo.writable_session("main")

    zarr.create(
        shape=(10, 10),
        chunks=(5, 5),
        store=session.store,
        overwrite=True,
    )
    session.commit("initialized dataset")

    p1 = mp.Process(target=worker, args=(1,))
    p2 = mp.Process(target=worker, args=(2,))
    p1.start()
    p2.start()
    p1.join()
    p2.join()

    session = repo.readonly_session(branch="main")
    z = zarr.open(session.store, mode="r")
    print(z.attrs["done"])
    print(list(repo.ancestry(branch="main")))


if __name__ == "__main__":
    main()

```

--------------------------------

### Open Repository and Restore Config

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/performance.md

Opens a repository and demonstrates that the persisted configuration is automatically restored. This ensures consistency when reopening a repository.

```python
print(ic.Repository.open(storage).config.manifest)
```

--------------------------------

### Reference File Format (JSON)

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/spec-v1.md

Example of a JSON file representing a branch or tag reference, containing a snapshot ID.

```json
{"snapshot":"VY76P925PRY57WFEK410"}
```

--------------------------------

### Manual Test Profiling Setup

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk/benches/README.md

Manually set up profiling for tests when direct profiling commands are not available. This involves compiling the test with `--no-run` and then using `xcrun xctrace record` to launch the compiled executable with specific arguments.

```sh
$ cargo test --package icechunk --test test_large_manifests --profile bench --no-run

$ xcrun xctrace record \
    --template 'Allocations' \
    --output test_large_manifests_alloc2.trace \
    --launch -- \
    target/perf/deps/test_large_manifests-f2bc61fc2535fa95 \
    test_write_large_number_of_refs
```

--------------------------------

### Version Control Operations

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/reference/icechunk-js.md

Provides examples for managing branches, tags, viewing commit history, and comparing differences between branches.

```APIDOC
## Version Control Operations

### Description
This section covers essential version control functionalities including creating and listing branches and tags, retrieving commit history, and calculating differences between branches.

### Methods

#### Create Branch
```typescript
repo.createBranch(name: string, snapshotId: string)
```
- **name** (string) - The name for the new branch.
- **snapshotId** (string) - The ID of the snapshot to base the new branch on.

#### List Branches
```typescript
repo.listBranches()
```
- Returns a list of available branches.

#### Create Tag
```typescript
repo.createTag(name: string, snapshotId: string)
```
- **name** (string) - The name for the new tag.
- **snapshotId** (string) - The ID of the snapshot to tag.

#### List Tags
```typescript
repo.listTags()
```
- Returns a list of available tags.

#### Get Ancestry (Commit History)
```typescript
repo.ancestry(options: { branch: string })
```
- **options.branch** (string) - The branch to retrieve the history for.
- Returns an array of snapshot objects, each with an `id` and `message`.

#### Diff
```typescript
repo.diff(options: { fromBranch: string, toBranch: string })
```
- **options.fromBranch** (string) - The starting branch for the comparison.
- **options.toBranch** (string) - The ending branch for the comparison.
- Returns a diff object containing `newArrays`, `updatedArrays`, etc.

### Request Example
```typescript
// Create a branch from the current snapshot
await repo.createBranch('dev', snapshotId)

// List branches
const branches = await repo.listBranches()

// Create a tag
await repo.createTag('v1.0', snapshotId)

// List tags
const tags = await repo.listTags()

// Get commit history
const history = await repo.ancestry({ branch: 'main' })
for (const snapshot of history) {
  console.log(`${snapshot.id} ${snapshot.message}`)
}

// Get diff between branches
const diff = await repo.diff({
  fromBranch: 'main',
  toBranch: 'dev',
})
console.log('New arrays:', diff.newArrays)
console.log('Updated arrays:', diff.updatedArrays)
```

### Response

#### Success Response
- **branches** (Array<string>) - List of branch names.
- **tags** (Array<string>) - List of tag names.
- **history** (Array<Snapshot>) - Array of commit snapshots.
- **diff** (Diff) - Object detailing differences between branches.

#### Response Example
```json
{
  "branches": ["main", "dev"],
  "tags": ["v1.0"],
  "history": [
    {
      "id": "<commit-hash-1>",
      "message": "Add temperature array"
    },
    {
      "id": "<commit-hash-2>",
      "message": "Initial commit"
    }
  ],
  "diff": {
    "newArrays": [],
    "updatedArrays": ["/temperature"]
  }
}
```
```

--------------------------------

### Write Data to Zarr Array

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/getting-started/quickstart.md

Write data to the created Zarr array. This example sets all elements of the array to 1.

```python
array[:] = 1
```

--------------------------------

### Get Zarr Async Concurrency

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/performance.md

Retrieves the current value of the zarr async.concurrency configuration parameter. The default value is 10.

```python
import zarr
print(zarr.config.get("async.concurrency"))
```

--------------------------------

### Implement Custom Storage Backend

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-js/README.md

Provides an example of implementing a custom storage backend in JavaScript using `Storage.newCustom()`. This is useful for WASM builds or environments where built-in backends are not suitable. Callbacks follow the Node.js error-first convention.

```typescript
const storage = Storage.newCustom({
  canWrite: async (_err, ) => true,
  getObjectRange: async (_err, { path, rangeStart, rangeEnd }) => {
    const headers: Record<string, string> = {}
    if (rangeStart != null && rangeEnd != null) {
      headers['Range'] = `bytes=${rangeStart}-${rangeEnd - 1}`
    }
    const resp = await fetch(`https://my-bucket.example.com/${path}`, { headers })
    return { data: new Uint8Array(await resp.arrayBuffer()), version: { etag: resp.headers.get('etag') ?? undefined } }
  },
  putObject: async (_err, { path, data, contentType }) => { /* ... */ },
  copyObject: async (_err, { from, to }) => { /* ... */ },
  listObjects: async (_err, prefix) => { /* return [{ id, createdAt, sizeBytes }] */ },
  deleteBatch: async (_err, { prefix, batch }) => { /* return { deletedObjects, deletedBytes } */ },
  getObjectLastModified: async (_err, path) => { /* return Date */ },
  getObjectConditional: async (_err, { path, previousVersion }) => { /* ... */ },
})
```

--------------------------------

### Commit Changes and Get Snapshot

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/xarray.md

Commit the staged data to the Icechunk repository and retrieve the snapshot ID of the first commit.

```python
first_snapshot = session.commit("add RASM data to store")
print(first_snapshot)
```

--------------------------------

### Repository Creation and Opening

Source: https://context7.com/earth-mover/icechunk/llms.txt

Demonstrates how to create a new Icechunk repository or open an existing one on various storage backends like S3, GCS, Azure Blob Storage, local filesystem, and in-memory. It also shows how to open a repository over HTTP in read-only mode.

```APIDOC
## Repository Creation and Opening

`icechunk.Repository.create` / `icechunk.Repository.open` — create a new repository or open an existing one on any supported storage backend.

```python
import icechunk as ic
import zarr

# --- Create on S3 (credentials from environment) ---
storage = ic.s3_storage(bucket="my-bucket", prefix="datasets/climate", from_env=True)
repo = ic.Repository.create(storage)

# --- Create on GCS ---
storage = ic.gcs_storage(bucket="my-bucket", prefix="datasets/climate", from_env=True)
repo = ic.Repository.create(storage)

# --- Create on Azure Blob Storage ---
storage = ic.azure_storage(
    account_name="myaccount",
    container="my-container",
    prefix="datasets/climate",
    account_key="my-account-key",
)
repo = ic.Repository.create(storage)

# --- Create on local filesystem ---
storage = ic.local_filesystem_storage("/data/my-repo")
repo = ic.Repository.create(storage)

# --- In-memory (for testing only) ---
repo = ic.Repository.create(ic.in_memory_storage())

# --- Open an existing repo ---
repo = ic.Repository.open(ic.s3_storage(bucket="my-bucket", prefix="datasets/climate", from_env=True))

# --- Open over HTTP (read-only) ---
repo = ic.Repository.open(ic.http_storage("https://example.com/path/to/repo"))
```
```

--------------------------------

### Custom Exception Handling for Commit Conflicts

Source: https://github.com/earth-mover/icechunk/blob/main/design-docs/002-rebase-commit-improvements.md

Provides an example of catching `ConflictError` and accessing parent information for detailed error reporting.

```python
try:
    commit_id = session.commit("yay")
except ConflictError as e:
    # just an example of what we could pull for data, the message would be more informative
    print(f"Commit failed: expected parent: {e.expected_parent}, actual parent: {e.actual_parent}")
```

--------------------------------

### Use Repository.create_async in Python

Source: https://github.com/earth-mover/icechunk/blob/main/Changelog.md

Demonstrates the usage of the asynchronous create method for a repository. This is useful for operations requiring optimal concurrency, especially when interacting with multiple repositories or sessions.

```python
Repository.create_async()
```

--------------------------------

### Run All Benchmarks

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk/benches/README.md

Execute all benchmarks defined in the project. This is the default command for running the benchmark suite.

```sh
cargo bench
```

--------------------------------

### Open Virtual Datasets

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-python/docs/docs/guides/virtual.md

Create virtual datasets from a list of URLs using the specified registry and parser. This step may take time as it fetches metadata.

```python
from virtualizarr import open_virtual_dataset

virtual_datasets =[
    open_virtual_dataset(url, registry=registry, parser=HDFParser())
    for url in oisst_files
]
```

--------------------------------

### ChunkIndexRange Structure

Source: https://github.com/earth-mover/icechunk/blob/main/icechunk-format/src/flatbuffers/README.md

Specifies a range of chunk indices, including a start index and an exclusive end index. This is a packed struct of 8 bytes.

```text
+--------------------+
| from: u32          |
| to: u32            |
+--------------------+

```