git-copy-file-folder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hh lohmann <hh.lohmann@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+###### npm-package
+
+# Copy file / folder from Git repo without cloning
+
+Copy a file or folder from a Git repo instead of cloning, i.e. without a connection to the source
+
+Changes in the original repo will not affect the copy of the file / folder and vice versa.
+
+Helpful to reuse specific contents of another repo in a current one without mixing both repos.
+
+*[hh lohmann <hh.lohmann@gmail.com>](mailto:hh.lohmann@gmail.com?subject=git-copy-file-folder)*
+
+<!-- see https://hh-lohmann.github.io/github-readme-pages-switch -->
+<p align="center" id="github_readme_pages_switch" style="display:none;">
+  <b><i>This page may be displayed more optimal in its
+  <a href="https://hh-lohmann.github.io/git-copy-file-folder">GitHub Pages view</a>
+  </i></b>
+</p>
+
+
+## Caution
+
+  * Does not check if a file / folder with the same name already exists in your target - this is up to you, especially in case you explicitly want to overwrite / reset existing files (cf. [Details](#details))
+
+
+## Synopsis
+
+```js
+  import { gitCopyFileFolder } from 'git-copy-file-folder'
+
+  gitCopyFileFolder( sourceRepo, fileOrFolder)
+
+  gitCopyFileFolder( sourceRepo, fileOrFolder, targetPath )
+```
+
+
+## Parameters
+
+### sourceRepo
+URL of the repo from which **[fileOrFolder](#fileorfolder)** should be copied
+
+### fileOrFolder
+Name / path for the file / folder to be copied from the **[sourceRepo](#sourcerepo)**
+  * Interpreted relative to the source repo's root, i.e. `src/index.js` of repo `x` would be `x/src/index.js`
+
+### targetPath
+Optional: Existing path to which **[fileOrFolder](#fileorfolder)** should be copied to
+  * Default: current folder
+
+
+## Returns
+
+  * `true` on success, `false` else
+
+
+## Examples
+
+```js
+  gitCopyFileFolder(
+    'https://github.com/acmecorp/solve-all-problems',
+    'secretsolutions'
+  )
+
+  gitCopyFileFolder(
+    'https://github.com/acmecorp/solve-all-problems',
+    'secretsolutions/solution-42.js',
+    'ripped-stuff/acme/'
+  )
+```
+
+
+## Installation
+
+Pick for your preferred package manager:
+
+```shell
+  npm i git-copy-file-folder
+```
+
+```shell
+  pnpm i git-copy-file-folder
+```
+
+```shell
+  bun i git-copy-file-folder
+```
+
+```shell
+  # For Yarn you should double check docs for your and / or
+  # current Yarn version, newer versions do not treat `i package_name`
+  # as an alias for `add ...` and exclude global installations
+  yarn add git-copy-file-folder
+```
+
+
+## Details
+
+  * Only one file / folder per call (multiple files / folders or globbing goes beyond the current time budget for this project)
+
+  * Does not check if a file / folder with the same name already exists in your target before probably overwriting it, partly for simplicity, partly to give surrounding code full control about e.g. deciding if overwriting an old version with a newer one or a diverged / corrupted version with the original one may be explicitly intended. 
+
+  * Copying takes place via a temporary [sparse clone](#git-clone-sparse) and a [sparse-checkout](#git-sparse-checkout) there (deleted after copying the file / folder requested)
+
+
+## Tests
+
+  * Code tests to be run with Node.js / Bun available in [Source Code](#source-code)
+
+
+## Source Code
+
+  * GitHub: <https://github.com/hh-lohmann/git-copy-file-folder>
+
+
+## License
+
+  * See LICENSE file included here and in [Source Code](#source-code)
+
+
+## References
+
+### Git: clone sparse
+  * <https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---sparse>
+
+### Git: sparse-checkout
+  * <https://git-scm.com/docs/git-sparse-checkout>
+
+
+<!-- see https://hh-lohmann.github.io/html-endspacer -->
+<p id="endspacer" data-version="0.2.0" title="Endspacer - helps to align scrolling and positioning link targets | Scroll up to content or click / touch to jump to page top" align="center"><a href="#top"><img alt="Endspacer: './markdown-assets/endspacer.png' missing - see https://hh-lohmann.github.io/html-endspacer" src="./markdown-assets/endspacer.png" height="1000" width="100%"><br>[top]</a></p>

package/index.js

@@ -0,0 +1,128 @@
+// @ts-check
+
+import {basename} from 'node:path';
+import {cpSync,existsSync,rmSync,statSync} from 'node:fs';
+import {spawnSync} from 'node:child_process';
+import {tmpdir} from 'node:os';
+import pkg from './package.json' with { type: "json" };
+
+/** @import {_CheckArgsGitCopyFileFolder,_CleanUpBeforeExit,_CopyFileFolder,GitCopyFileFolder} from './types.d.ts' */
+
+/** @type {_CheckArgsGitCopyFileFolder} */
+const _checkArgsGitCopyFileFolder=function(passedArgs,errPrefix){
+  if(passedArgs.length<2) throw TypeError(`${errPrefix}not enough arguments`);
+  if(passedArgs.length>3) throw TypeError(`${errPrefix}too many arguments`);
+  ['sourceRepo','fileOrFolder','targetPath'].forEach((value,i)=>{
+    if(i===passedArgs.length) return;
+    if(typeof passedArgs[i]!=='string'||passedArgs[i]==='') throw TypeError(`${errPrefix}${value} must be a non-empty string`);
+  })
+  return true;
+}
+
+/** Check if Git is available
+ * @type {(errPrefix:string)=>boolean}
+ */
+const _checkGit=function(errPrefix){
+  if(spawnSync('git',['--version']).pid) return true;
+  throw ReferenceError(`${errPrefix}Could not call Git - check installation and / or PATH environment variable`);
+}
+
+/** Check if target path exists
+ * @type {(namePath:string,errPrefix:string)=>boolean}
+ */
+const _checkTargetExists=function(namePath,errPrefix){
+  if(existsSync(namePath)) return true;
+  throw ReferenceError(`${errPrefix}Target path "${namePath}" does not exist`);
+}
+
+/** Check if repo to copy from is reachable
+ *  - NB: not necessarily "does not exist", may be no connection / rights etc.
+ * @type {(url:string,errPrefix:string)=>boolean}
+ */
+const _checkSourceRepoReachable=function(url,errPrefix){
+  if(spawnSync('git',['ls-remote',url]).status===0) return true;
+  throw ReferenceError(`${errPrefix}Source repo "${url}" not reachable - you may check spelling / access rights / connectivity`);
+}
+
+/** @type {_CleanUpBeforeExit} */
+const _cleanUpBeforeExit={
+  _errPrefix: '_cleanUpBeforeExit: ',
+  _toDelete: {},
+  _pushToDeleteList(list='',entry='',context){
+    if(!context) throw SyntaxError(`${this._errPrefix}"context" has to be defined`);
+    if(!Object.hasOwn(this._toDelete,context)){this._toDelete[context]={files:[],folders:[]}}
+    this._toDelete[context][list].push(entry);
+  },
+  addDeleteFile(namePath='',context){
+    if(namePath==='') return;
+    this._pushToDeleteList('files',namePath,context);
+  },
+  addDeleteFolder(namePath='',context){
+    if(namePath==='') return;
+    this._pushToDeleteList('folders',namePath,context);
+  },
+  clean(context){
+    if(!context) throw SyntaxError(`${this._errPrefix}"context" has to be defined`);
+    if(!Object.hasOwn(this._toDelete,context)) return;
+    Object.keys(this._toDelete[context]).forEach(value=>{
+      while(this._toDelete[context][value].length!==0){
+        const myDeleteNext=this._toDelete[context][value].pop();
+        if(!myDeleteNext) return;
+        if(!existsSync(myDeleteNext)) throw Error(`${this._errPrefix}"${myDeleteNext}" not found - please check if previous steps were interrupted`);
+        try{
+          rmSync(myDeleteNext,{recursive:true});
+        }
+        catch(err){
+          throw Error(`${this._errPrefix}"${myDeleteNext}" could not be deleted - please check for possible corruption`);
+        }
+      }
+    })
+  }
+}
+
+/** Create temporary sparse clone for repo to copy from
+ * @type {(source:string,target:string,errPrefix:string)=>boolean}
+ */
+const _cloneRepoTempSparseDepth1NoBlobs=function(source,target,errPrefix){
+  if(spawnSync('git',['clone','--sparse','--depth=1','--filter=blob:none',source,target]).status===0) return true;
+  throw Error(`${errPrefix}Cloning failed (reason unknown)`);
+}
+
+/** @type {_CopyFileFolder} */
+const _copyFileFolder=function(fileOrFolder,targetPath,sourceRepoName,tempSparseRepo,errPrefix,cleanUpContext){
+  const normalizeNamePath=function(namePath=''){
+    if(namePath.slice(0,1)==='/') return namePath.slice(1);
+    if(namePath.slice(0,2)==='./') return namePath.slice(2);
+    return namePath;
+  }
+  const normalizeTarget=function(source=''){
+    if(statSync(source).isDirectory()) return targetPath+'/'+fileOrFolder;
+    return targetPath+'/'+basename(fileOrFolder);
+  }
+  fileOrFolder=normalizeNamePath(fileOrFolder);
+  spawnSync('git',['sparse-checkout','add','./'+fileOrFolder],{cwd:tempSparseRepo});
+  const source=tempSparseRepo+'/'+fileOrFolder;
+  if(!existsSync(source)){
+    _cleanUpBeforeExit.clean(cleanUpContext);
+    throw ReferenceError(`${errPrefix}File / folder "${fileOrFolder}" not available in repo "${sourceRepoName}"- you may check spelling / source repo`);
+  }
+  const target=normalizeTarget(source);
+  cpSync(source,target,{recursive:true});
+  return true;
+}
+
+/** @type {GitCopyFileFolder} */
+export const gitCopyFileFolder=function(sourceRepo,fileOrFolder,targetPath='.'){
+  const _myCleanUpBeforeExitContext=crypto.randomUUID();
+  const _errPrefix=pkg.name+': ';
+  _checkGit(_errPrefix);
+  _checkArgsGitCopyFileFolder(arguments,_errPrefix);
+  _checkSourceRepoReachable(sourceRepo,_errPrefix);
+  _checkTargetExists(targetPath,_errPrefix);
+  const tempClonePath=`${tmpdir()}/random_${crypto.randomUUID().split('-')[0]}`;
+  _cleanUpBeforeExit.addDeleteFolder(tempClonePath,_myCleanUpBeforeExitContext);
+  _cloneRepoTempSparseDepth1NoBlobs(sourceRepo,tempClonePath,_errPrefix);
+  _copyFileFolder(fileOrFolder,targetPath,sourceRepo,tempClonePath,_errPrefix,_myCleanUpBeforeExitContext)
+  _cleanUpBeforeExit.clean(_myCleanUpBeforeExitContext);
+  return true;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "git-copy-file-folder",
+  "description": "Copy a file or folder from a Git repo instead of cloning, i.e. without a connection to the source",
+  "keywords": [],
+  "author": {
+    "name": "hh lohmann",
+    "email": "hh.lohmann@gmail.com"
+  },
+  "version": "1.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hh-lohmann/git-copy-file-folder.git"
+  },
+  "bugs": "https://github.com/hh-lohmann/git-copy-file-folder/issues",
+  "homepage": "https://hh-lohmann.github.io/git-copy-file-folder",
+  "type": "module",
+  "exports": {
+    "types": "./types.d.ts",
+    "default": "./index.js"
+  },
+  "scripts": {
+    "test": "node --test ./tests/**/*.test.*"
+  },
+  "dependencies": {
+    "node-test-bootstrap": "github:hh-lohmann/node-test-bootstrap"
+  }
+}

package/types.d.ts

@@ -0,0 +1,46 @@
+/** Check given arguments for gitCopyFileFolder
+ *  - Signature of gitCopyFileFolder is addressed internally
+ */
+export type _CheckArgsGitCopyFileFolder=(passedArgs:IArguments,errPrefix:string)=>boolean;
+
+
+/** Method object: Clean up runtime artifacts before exiting
+ *  - "context" to distnguish possible multiple calls of a 'git-copy-file-folder' import in the same parent file
+ * @method addDeleteFile(namePath,context) - Add "namePath" to list of files to be deleted in "context"
+ * @method addDeleteFolder(namePath,context) - Add "namePath" to list of folders to be deleted in "context"
+ * @method clean(context) - Run clean up for "context"
+ * @type {object}
+ */
+export type  _CleanUpBeforeExit={
+  _errPrefix:string,
+  _toDelete:{[key:string]:{[key:string]:string[]}},
+  _pushToDeleteList:(list:string,entry:string,context:string)=>void,
+  addDeleteFile:(namePath:string,context:string)=>void,
+  addDeleteFolder:(namePath:string,context:string)=>void,
+  clean:(context:string)=>void
+}
+
+/** Copy file / folder from temporary sparse repo to target
+ * @example _copyFileFolder=function( 'src/', '../todo', '/tmp/sparse-source' )
+ * @param fileOrFolder - Name / path for file / folder to copy
+ * @param targetPath - Path to copy to, default: current dir
+ * @param sourceRepoName - Name of source repo to copy from
+ * @param tempSparseRepo - Temporary sparse repo to copy from
+ * @param errPrefix - Prefix for error messages
+ * @param cleanUpContext - context for _cleanUpBeforeExit()
+ * @returns true on success
+ */
+export type _CopyFileFolder=(fileOrFolder:string,targetPath:string,sourceRepoName:string,tempSparseRepo:string,errPrefix:string,cleanUpContext:string)=>boolean;
+
+
+/** Clone repo to new one with no connections to the original
+ *  - New repo will have an empty history and no remotes, everything
+ *    else will be as in the original
+ * @example gitCopyFileFolder('https://github.com/x-y/z','myRepo')
+ * @param sourceRepo - URL of the repo to copy from
+ * @param fileOrFolder - Name / path for repo to create
+ * @param [targetPath] - Optional: Branch name for new repo, default: 'main'
+ * @returns `true` on success, `false` else
+ */
+export const gitCopyFileFolder:GitCopyFileFolder;
+export type GitCopyFileFolder=(sourceRepo:string,fileOrFolder:string,targetPath?:string)=>boolean;