This is a JavaScript in-browser git client running on the Puter filesystem, using [isomorphic-git](https://isomorphic-git.org).
It aims to match `git`'s interface, so that running a command behaves the same way as it would there.
Of course, `git` has a large variety of subcommands and options, some of which are obscure, so many will be missing.
Consider adding them if you are interested! :^)
While this is built for Puter, the only Puter-specific parts are:
-`src/filesystem.js` which integrates with Puter's filesystem.
-`src/main.js` which uses the Puter SDK to connect to the parent Phoenix shell.
By modifying these, and the values in `config/`, you should be able to port it to other environments.
## Subcommand structure
The `git` CLI is structured as a series of sub-commands - `git branch` has nothing in common with `git version`, for example. Each of these is modelled as its own file in `src/subcommands`, and should export a default object with the following structure:
```js
export default {
// The subcommand's name
name: 'help',
// A string or array of strings, for how the subcommand is run. Shown in the help.
usage: [
'git help [-a|--all]',
'git help <command>',
],
// A description, shown in the help.
description: `Display help information for git itself, or a subcommand.`,
// Arguments object, passed to `parseArgs()`
args: {
allowPositionals: true,
options: {
all: {
// The one deviation from parseArgs() is that each option gets a description,
// which is shown in the help output.
description: 'List all available subcommands.',
type: 'boolean',
}
},
},
// Function to actually run the subcommand.
// The return value can be a posix-style exit code, or a plain `return` as a shorthand for 0.
// Throwing errors is allowed.
// Throwing the special `SHOW_USAGE` value defined in `src/help.js` can be used to print the command usage text.
execute: async (ctx) => {
// ctx has the following structure:
ctx = {
io: {
stdout, // Function that takes a string, and prints it to stdout
stderr, // Function that takes a string, and prints it to stderr
},
fs, // A filesystem implementation, for isomorphic-git
args, // An object returned from `parseArgs()`.
env, // Object containing environment variables, such as PWD for the current working directory.
}
}
}
```
These are them listed in `src/subcommands/__exports__.js`, which can be automatically generated by running `packages/phoenix/tools/gen.js packages/git/src/subcommands` from the Puter repo root. But it's not hard to modify manually.
## Common patterns
### Shared options
It's common in a few places that options are shared between commands, for example options related to formatting commits are shared by `git log` and `git show`.
In these cases, those options are defined in an object in `src/format.js` with an accompanying function to process their results into a more convenient format.
For example, `diff_formatting_options` and `process_diff_formatting_options(options)`:
Some of the options are shorthands for others; some "imply" another; and some are set by default under certain conditions.
All this is handled in one place instead of in each subcommand that needs them.
### Repo root
Since the `git` command may be run from a repository, a subdirectory, or a non-repository, you can locate the git directory like so:
The `dir` and `gitdir` variables can then be passed to isomorphic-git methods that expect them.
If no repository is found, this will throw an error, which is then printed to stderr.
(isomorphic-git's `git.findRoot()` does not implement checks for a `.git` text file that points to an alternative directory that git's metadata is stored in. We should maybe upstream this.)
## Isomorphic-git
The library we use for most interaction with git's files is [isomorphic-git](https://isomorphic-git.org).
It handles most of the basics, but because we want to do everything that [git](https://git-scm.com) does, a lot has to
be implemented manually. For example, it has a `git.add()` method for adding files, but whereas `git add deleted_file`
will stage that deletion, `git.add({ filepath: 'deleted_file', ... })` will complain that the file does not exist. So
our implementation of `git add` manually iterates the changed files and either calls `git.add()` or `git.remove()` as
appropriate.
### Troubleshooting tips:
- File paths given to isomorphic-git need to be relative to the repo root. Absolute paths often silently do nothing!
