oneRepo API: git

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

Classes

StagingWorkflow

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

Constructors

Constructor

new StagingWorkflow(options): StagingWorkflow;

Defined in: modules/git/src/workflow.ts
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

Methods

restoreUnstaged()

restoreUnstaged(): Promise<void>;

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

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>

saveUnstaged()

saveUnstaged(): Promise<void>;

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

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>

Type Aliases

ModifiedBaseOptions<ByStatus>

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

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

Type Parameters

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

Properties

allStatus?

optional allStatus: boolean;

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

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

byStatus?

optional byStatus: ByStatus;

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

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

ModifiedByStatus

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

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

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.

Properties

added

added: string[];

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

Git status A: addition of a file

copied

copied: string[];

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

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

deleted

deleted: string[];

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

Git status D: deletion of a file

fileTypeChanged

fileTypeChanged: string[];

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

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

modified

modified: string[];

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

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

renamed

renamed: string[];

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

Git status R: renaming of a file

unknown

unknown: string[];

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

Git status X: addition of a file

unmerged

unmerged: string[];

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

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

ModifiedFromThrough<ByStatus>

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

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

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`

ModifiedStaged<ByStatus>

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

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

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`

Options

type Options = {
  step?: LogStep;
};

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

Generic options passed to all Git operations.

Properties

step?

optional step: LogStep;

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

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

UpdateIndexOptions

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

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

Type declaration

immediately?

optional immediately: boolean;

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

Default: false

Functions

flushUpdateIndex()

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

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

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

await git.flushUpdateIndex();

Parameters:

Parameter	Type
`options?`	`Options`

Returns: Promise<void>

getBranch()

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

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

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>

getCurrentSha()

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

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

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>

getMergeBase()

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

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

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>

getModifiedFiles()

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

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

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[]>

isClean()

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

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

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>

updateIndex()

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

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

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<undefined | string>