oneRepo API: git

Special handlers for managing complex queries and manipulation of the git repository’s state.

Classes

StagingWorkflow

Constructors

new StagingWorkflow()

new StagingWorkflow(options): StagingWorkflow

Parameters:

Parameter	Type	Description
`options`	{ `graph`: `Graph`; `logger`: `Logger`; }	-
`options.graph`	`Graph`	The repository Graph
`options.logger`	`Logger`	Logger instance to use for all actions

Returns: StagingWorkflow
Defined in: modules/git/src/workflow.ts

Methods

restoreUnstaged()

restoreUnstaged(): Promise<void>

Restores the unstaged changes previously backed up by `saveUnstaged()`.

This command will go through a series of attempts to ressurect upon failure, eventually throwing an error if unstaged changes cannot be reapplied.

Returns: Promise<void>
Defined in: modules/git/src/workflow.ts

saveUnstaged()

saveUnstaged(): Promise<void>

Backup any unstaged changes, whether that’s full files or parts of files. This will result in the git status only including what was already in the stage. All other changes will be backed up to:

A patch file in the .git/ directory
A git stash

To restore the unstaged changes, call `restoreUnstaged()`.

Returns: Promise<void>
Defined in: modules/git/src/workflow.ts

Type Aliases

ModifiedBaseOptions<ByStatus>

type ModifiedBaseOptions<ByStatus>: {
  allStatus: boolean;
  byStatus: ByStatus;
};

Type Parameters

Type Parameter	Default type
`ByStatus` extends `boolean`	`false`

Type declaration

allStatus?

optional allStatus: boolean;

By default, this function will not return deleted and unmerged files unless either allStatus or byStatus is set to true

byStatus?

optional byStatus: ByStatus;

Return modified files categorized by the type of modification (added, deleted, modified, etc)

Defined in: modules/git/src/index.ts

ModifiedByStatus

type ModifiedByStatus: {
  added: string[];
  copied: string[];
  deleted: string[];
  fileTypeChanged: string[];
  modified: string[];
  renamed: string[];
  unknown: string[];
  unmerged: string[];
};

This type defines the different statuses of files when running a git-diff. More information around the file statuses can be found in the official git documentation for git-diff.

Type declaration

added

added: string[];

Git status A: addition of a file

copied

copied: string[];

Git status C: copy of a file into a new one

deleted

deleted: string[];

Git status D: deletion of a file

fileTypeChanged

fileTypeChanged: string[];

Git status T: change in the type of the file (regular file, symbolic link or submodule)

modified

modified: string[];

Git status M: modification of the contents or mode of a file

renamed

renamed: string[];

Git status R: renaming of a file

unknown

unknown: string[];

Git status X: addition of a file

unmerged

unmerged: string[];

Git status U: “unknown” change type (most probably a bug, please report it)

Defined in: modules/git/src/index.ts

ModifiedFromThrough<ByStatus>

type ModifiedFromThrough<ByStatus>: ModifiedBaseOptions<ByStatus> & {
  from: string;
  staged: false;
  through: string;
};

Type declaration

from?

optional from: string;

Git ref for start (exclusive) to get list of modified files

staged?

optional staged: false;

Cannot include staged files when using from/through refs.

through?

optional through: string;

Git ref for end (inclusive) to get list of modified files

Type Parameters

Type Parameter
`ByStatus` extends `boolean`

Defined in: modules/git/src/index.ts

ModifiedStaged<ByStatus>

type ModifiedStaged<ByStatus>: ModifiedBaseOptions<ByStatus> & {
  from: never;
  staged: true;
  through: never;
};

Type declaration

from?

optional from: never;

Disallowed when staged: true

staged

staged: true;

Get staged modified files only

through?

optional through: never;

Disallowed when staged: true

Type Parameters

Type Parameter
`ByStatus` extends `boolean`

Defined in: modules/git/src/index.ts

Options

type Options: {
  step: LogStep;
};

Generic options passed to all Git operations.

Type declaration

step?

optional step: LogStep;

Avoid creating a new step in output for each function. Pass a Logger Step to pipe all logs and output to that instead.

Defined in: modules/git/src/index.ts

UpdateIndexOptions

type UpdateIndexOptions: Options & {
  immediately: boolean;
};

Type declaration

immediately?

optional immediately: boolean;

Set whether to immediately add to the git index or defer until process shutdown

Default: false
Defined in: modules/git/src/index.ts

Functions

flushUpdateIndex()

function flushUpdateIndex(options?): Promise<void>;

Write all pending files added using `updateIndex()` to the git index.

await git.flushUpdateIndex();

Parameters:

Parameter	Type
`options`?	`Options`

Returns: Promise<void>
Defined in: modules/git/src/index.ts

getBranch()

function getBranch(options?): Promise<string>;

Get the name of the current branch. Equivalent to git rev-parse --abbrev-ref HEAD.

const currentBranch = await git.getBranch();

Parameters:

Parameter	Type
`options`?	`Options`

Returns: Promise<string>
Defined in: modules/git/src/index.ts

getCurrentSha()

function getCurrentSha(options?): Promise<string>;

Get the current sha ref. This is equivalent to git rev-parse HEAD.

const sha = await git.getCurrentSha();

Parameters:

Parameter	Type
`options`?	`Options`

Returns: Promise<string>
Defined in: modules/git/src/index.ts

getMergeBase()

function getMergeBase(options?): Promise<string>;

Determine the git ref for merging the current working branch, sha, or ref, whichever that is. This function does a bunch of internal checks to determine the where the most likely point of forking happened.

const mergeBase = await getMergeBase();

Parameters:

Parameter	Type
`options`?	`Options`

Returns: Promise<string>
Defined in: modules/git/src/index.ts

getModifiedFiles()

function getModifiedFiles<ByStatus>(modified?, options?): Promise<ByStatus extends true ? ModifiedByStatus : string[]>;

Get a map of the currently modified files based on their status. If from and through are not provided, this will use merge-base determination to get the changes to the working tree using git diff and git diff-tree.

By default, this function will not return deleted and unmerged files. If you wish to include files with those statuses, set the option allStatus: true or get a map of all files by status using byStatus: true.

const changesSinceMergeBase = await git.getModifiedFiles();
const betweenRefs = await git.getModifiedFiles({ from: 'v1.2.3', through: 'v2.0.0' });

Get modified files categorized by modification type:

const allChanges = await git.getModifiedFiles({ byStatus: true });

Will result in allChanges equal to an object containing arrays of strings:

{
  added: [/* ... */],
  copied: [/* ... */],
  modified: [/* ... */],
  deleted: [/* ... */],
  renamed: [/* ... */],
  fileTypeChanged: [/* ... */],
  unmerged: [/* ... */],
  unknown: [/* ... */],
}

Type Parameters

Type Parameter	Default type
`ByStatus` extends `boolean`	`false`

Parameters:

Parameter	Type
`modified`?	`ModifiedStaged`<`ByStatus`> \| `ModifiedFromThrough`<`ByStatus`>
`options`?	`Options`

Returns: Promise<ByStatus extends true ? ModifiedByStatus : string[]>
Defined in: modules/git/src/index.ts

isClean()

function isClean(options?): Promise<boolean>;

Check if the current git working state is clean.

const isClean = await git.isClean();
if (!isClean) {
  // There are local modifications that have not yet been committed.
}

Parameters:

Parameter	Type
`options`?	`Options`

Returns: Promise<boolean>
Defined in: modules/git/src/index.ts

updateIndex()

function updateIndex(paths, options?): Promise<string | undefined>;

Add filepaths to the git index. Equivalent to git add [...files]. By default, this method will track the files that need to be added to the git index. It will only add files immediately if given the immediately option.

Use `flushUpdateIndex()` to write all tracked files the git index. This method is automatically called during the oneRepo command shutdown process, so you may not ever need to call this.

It is best to avoid immediately adding items to the git index to avoid race conditions which can drop git into a bad state, requiring users to manually delete their .git/index.lock file before continuing.

await git.updateIndex(['tacos.ts']);

Parameters:

Parameter	Type
`paths`	`string` \| `string`[]
`options`?	`UpdateIndexOptions`

Returns: Promise<string | undefined>
Defined in: modules/git/src/index.ts