https://github.com/riboseinc/isogit-lfs
LFS helpers on top of Isomorphic Git
https://github.com/riboseinc/isogit-lfs
Last synced: about 1 month ago
JSON representation
LFS helpers on top of Isomorphic Git
- Host: GitHub
- URL: https://github.com/riboseinc/isogit-lfs
- Owner: riboseinc
- License: mit
- Created: 2021-11-25T11:41:43.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-12-04T12:35:44.000Z (6 months ago)
- Last Synced: 2025-04-05T23:32:28.183Z (about 2 months ago)
- Language: TypeScript
- Size: 134 KB
- Stars: 7
- Watchers: 5
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
Aspirationally, a set of helpers
to simplify working with Git LFS through Isomorphic Git.
Currently the API is fairly low-level and verbose,
which could be improved.
However, touching working directory is out of scope.
Callers are free to integrate the library into workflows
based on bare Git repositories or repositories with working directories
depending on their specifics.
NOTE: While Isomorphic Git maintenance status is unclear,
this library is in turn not likely to receive new features.
== Installation
Peer dependencies:
- Isomorphic Git ^1.7.8
- @aws-crypto/sha256-universal ^2.0.0
== Usage
Example of using the library to read from LFS:
```typescript
import { pointsToLFS } from '@riboseinc/isogit-lfs/util.js';
import { readPointer, downloadBlobFromPointer } from '@riboseinc/isogit-lfs';
// We need to know the remote URL of this repository
// in order to request LFS data
// (this relies on Git config just for the sake of example)
const remoteURL = await git.getConfig({ fs, gitdir, path: 'remote.origin.url' });
async function readObject(fs, gitdir, oid, path): Promise {
// 1) Read some blob from the repo
const gitObject = await git.readBlob({ fs, gitdir, oid, filepath: path });
// 2) Check if this blob points to LFS
if (pointsToLFS(gitObject.blob)) {
// If yes, 3) deserialize pointer
const pointer = readPointer({
gitdir,
content: gitObject.blob,
});
// 4) Download or retrieve from cache
return await downloadBlobFromPointer({
fs,
url: remoteURL,
http,
}, pointer);
} else {
// If not, just return the blob straight away
return gitObject.blob;
}
}
```
== API
As of 0.2.0, API offers the following functions
(blobs are Uint8Array instances):
- `downloadBlobFromPointer({ http, headers, url, auth }, lfsPointer) => Promise`
+
where `http` is an `HttpClient` as supported by Isomorphic Git,
URL is repository URL
and `lfsPointer` is an object returned by `readPointer()`.
+
Uses LFS cache (which is hidden in Git repo structure,
under `.git/lfs` for non-bare repositories) if the object had been previously retrieved.
- `uploadBlob({ http, headers, url, auth }, blob) => Promise`
+
where first argument is the same as for the download function,
and returned pointer info can be used to write a pointer file in place
of actual object in Git repository (pass it through `formatPointerInfo()`).
- `readPointer({ gitdir, content }) => Pointer`
+
where `gitdir` behavior mimics that of Isomorphic Git
(for non-bare repositories it’s *not* working directory but the `.git` in it)
and `content` is a `Uint8Array`.
+
Returns an LFS pointer together with Git repo object path of the full blob
(which may or may not be retrieved).
- `readPointerInfo(blob) => PointerInfo`
+
converts a Uint8Array into an LFS pointer structure
sufficient for requesting actual LFS blob.
- `formatPointerInfo(lfsPointerInfo) => Uint8Array`
+
converts pointer info to appropriately formatted blob
suitable to be stored in Git repository in place of actual object data.
- `populateCache(gitdir, ref?) => Promise`
+
where `gitdir` is same as for `readPointer()`
and `ref` should probably be left at the default `"HEAD"`.
+
Attempts to download all LFS objects in the tree of `ref`.
Does not return anything or write anything anywhere
except lets the blobs be cached for subsequently faster invocations
of the download function.
+
NOTE: This particular function is a very tentative piece of API.
Downloads are not particularly optimized, it’s likely quite slow.
- `utils.pointsToLFS({ gitdir, content }) => boolean`
+
where `gitdir` is same as for `readPointer()`
and `content` is data of some object in the repository
as `Uint8Array`.
== Known shortcomings
- The `@aws-crypto/sha256-universal` dependency is suboptimal.
It pulls extra dependencies of its own,
while it’s not that difficult to provide corresponding implementation using subtle crypto
which is compatible between Node and modern browsers.
- Originally written for Node runtime, but should work in browser as of 0.2.0.
- Lacks automated tests.
== Considered within scope
- Implement batch uploads and downloads (parallelise requests? use native batch API?)
- Find a way to generalize UA header handling
- Make it work in browser runtime as well (if feasible?) — should be done in 0.2.0