# @hulla/gittar

> Copy a repository folder into a starter project, with a separate cache and an explicit refresh policy.

`@hulla/gittar` downloads a repository's files over HTTPS and extracts them into a cache. Use it in a Bun script to fetch a starter project or a collection of templates.

You get the files at one revision, without a `.git` directory or commit history.

**Interactive example: **Edit the download options, copy a starter, and customize it. Use another destination to copy from the untouched template cache.

A local filesystem model shows separate editable project copies and an unchanged cached template. No repository is downloaded or files written.

```ts
import gittar from '@hulla/gittar'

const snapshot = await gittar({
  url: 'hulladev/gittar',
  branch: 'master',
  subpath: 'src',
  update: 'commit',
  outDir: './my-starter',
})
```

[Build the working example](https://hulla.dev/guides/gittar/quick-start.md)

## Start with a working copy

[Build a template downloader](https://hulla.dev/guides/gittar/quick-start.md) that copies a repository to a local folder, then run it again to observe the cache.

```ts
import gittar from '@hulla/gittar'

const snapshot = await gittar({
  url: 'hulladev/gittar',
  branch: 'master',
  outDir: './downloaded-template',
})

console.log(snapshot.files.length, snapshot.fromCache)
```

The full repository goes into the cache. A separate `outDir` receives a copy. Add a [`subpath`](https://hulla.dev/docs/gittar/caching.md#copy-a-folder) when you only need one directory.

> **Note: Bun is required**
>
> Extraction and copying use Bun APIs and system commands. Run these scripts with Bun in an environment with `tar`, `cp`, and `mkdir`. The default commit check also uses Git.

## Choose a cache policy

| Policy             | What a later call does                                                             |
| ------------------ | ---------------------------------------------------------------------------------- |
| `commit` (default) | Checks the remote branch and downloads if its commit changed.                      |
| `always`           | Downloads again, even when cached files exist.                                     |
| `never`            | Uses existing cached files without checking the remote. Downloads on a cache miss. |

Read [Caching and copying](https://hulla.dev/docs/gittar/caching.md) before building an updater. Use the [reference](https://hulla.dev/docs/gittar/reference.md) to look up options, returned metadata, and error types.