-
-
Notifications
You must be signed in to change notification settings - Fork 320
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Feature: enable the use of two commands for the `customBinary` Example: ```typescript simpleGit({ binary: 'git' }); // default simpleGit({ binary: ['./local/script/git'] }); // single item array simpleGit({ binary: ['wsl', 'git'] }); // string tuple ``` To avoid accidentally merging dangerous content into the binary - both commands are limited to alphanumeric with a restricted set of special characters `./\-_`. With `allowUnsafeCustomBinary` to ignore the validation of `binary` param inputs
- Loading branch information
Showing
20 changed files
with
288 additions
and
31 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
"simple-git": minor | ||
--- | ||
|
||
Enable the use of a two part custom binary |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,72 @@ | ||
## Custom Binary | ||
|
||
The `simple-git` library relies on `git` being available on the `$PATH` when spawning the child processes | ||
to handle each `git` command. | ||
|
||
```typescript | ||
simpleGit().init(); | ||
``` | ||
|
||
Is equivalent to opening a terminal prompt and typing | ||
|
||
```shell | ||
git init | ||
``` | ||
|
||
### Configuring the binary for a new instance | ||
|
||
When `git` isn't available on the `$PATH`, which can often be the case if you're running in a custom | ||
or virtualised container, the `git` binary can be replaced using the configuration object: | ||
|
||
```typescript | ||
simpleGit({ binary: 'my-custom-git' }); | ||
``` | ||
|
||
For environments where you need even further customisation of the path (for example flatpak or WSL), | ||
the `binary` configuration property can be supplied as an array of up to two strings which will become | ||
the command and first argument of the spawned child processes: | ||
|
||
```typescript | ||
simpleGit({ binary: ['wsl', 'git'] }).init(); | ||
``` | ||
|
||
Is equivalent to: | ||
|
||
```shell | ||
wsl git init | ||
``` | ||
|
||
### Changing the binary on an existing instance | ||
|
||
From v3.24.0 and above, the `simpleGit.customBinary` method supports the same parameter type and can be | ||
used to change the `binary` configuration on an existing `simple-git` instance: | ||
|
||
```typescript | ||
const git = await simpleGit().init(); | ||
git.customBinary('./custom/git').raw('add', '.'); | ||
``` | ||
|
||
Is equivalent to: | ||
|
||
```shell | ||
git init | ||
./custom/git add . | ||
``` | ||
|
||
### Caveats / Security | ||
|
||
To prevent accidentally merging arbitrary code into the spawned child processes, the strings supplied | ||
in the `binary` config are limited to alphanumeric, slashes, dot, hyphen and underscore. Colon is also | ||
permitted when part of a valid windows path (ie: after one letter at the start of the string). | ||
|
||
This protection can be overridden by passing an additional unsafe configuration setting: | ||
|
||
```typescript | ||
// this would normally throw because of the invalid value for `binary` | ||
simpleGit({ | ||
unsafe: { | ||
allowUnsafeCustomBinary: true | ||
}, | ||
binary: '!' | ||
}); | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,56 @@ | ||
import type { SimpleGitOptions } from '../types'; | ||
|
||
import { GitPluginError } from '../errors/git-plugin-error'; | ||
import { asArray } from '../utils'; | ||
import { PluginStore } from './plugin-store'; | ||
|
||
const WRONG_NUMBER_ERR = `Invalid value supplied for custom binary, requires a single string or an array containing either one or two strings`; | ||
const WRONG_CHARS_ERR = `Invalid value supplied for custom binary, restricted characters must be removed or supply the unsafe.allowUnsafeCustomBinary option`; | ||
|
||
function isBadArgument(arg: string) { | ||
return !arg || !/^([a-z]:)?([a-z0-9/.\\_-]+)$/i.test(arg); | ||
} | ||
|
||
function toBinaryConfig( | ||
input: string[], | ||
allowUnsafe: boolean | ||
): { binary: string; prefix?: string } { | ||
if (input.length < 1 || input.length > 2) { | ||
throw new GitPluginError(undefined, 'binary', WRONG_NUMBER_ERR); | ||
} | ||
|
||
const isBad = input.some(isBadArgument); | ||
if (isBad) { | ||
if (allowUnsafe) { | ||
console.warn(WRONG_CHARS_ERR); | ||
} else { | ||
throw new GitPluginError(undefined, 'binary', WRONG_CHARS_ERR); | ||
} | ||
} | ||
|
||
const [binary, prefix] = input; | ||
return { | ||
binary, | ||
prefix, | ||
}; | ||
} | ||
|
||
export function customBinaryPlugin( | ||
plugins: PluginStore, | ||
input: SimpleGitOptions['binary'] = ['git'], | ||
allowUnsafe = false | ||
) { | ||
let config = toBinaryConfig(asArray(input), allowUnsafe); | ||
|
||
plugins.on('binary', (input) => { | ||
config = toBinaryConfig(asArray(input), allowUnsafe); | ||
}); | ||
|
||
plugins.append('spawn.binary', () => { | ||
return config.binary; | ||
}); | ||
|
||
plugins.append('spawn.args', (data) => { | ||
return config.prefix ? [config.prefix, ...data] : data; | ||
}); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.