Skip to main content
This guide covers the essential Git workflow using useGit: initializing a repository, adding files, and creating commits.

​
Initialize a Repository

Start by creating a new Git repository in your project directory: 
import { init } from 'usegit';

await init();
// Creates a new repository with 'main' as the default branch
By default, init() creates a repository with main as the initial branch. You can customize this behavior using options.

​
Custom Initial Branch

Specify a different initial branch name: 
import { init } from 'usegit';

await init({
  '--initial-branch': 'develop'
});

​
Complete Workflow Example

Here’s a complete example showing a typical Git workflow:
1

Initialize the repository

import { init, add, commit, status } from 'usegit';

// Create a new Git repository
await init();
2

Check repository status

// View the working tree status
const statusOutput = await status();
console.log(statusOutput);
3

Stage your files

// Add all files to staging
await add('.');

// Or add specific files
await add(['src/index.ts', 'package.json']);
4

Create a commit

// Commit with a message
await commit('feat: initial project setup');

// Commit with message and description
await commit(
  'feat: add user authentication',
  'Implements login and signup functionality with JWT tokens'
);

​
Working with Staged Files

​
Check What’s Staged

Before committing, you can check which files are staged and what changes they contain: 
import { status, diffStaged } from 'usegit';

// View status in short format
const shortStatus = await status(undefined, {
  flags: ['--short', '--branch']
});
console.log(shortStatus);

// View the actual changes that are staged
const stagedChanges = await diffStaged();
console.log(stagedChanges);

​
Selective Staging

Stage only specific files or directories: 
import { add } from 'usegit';

// Stage a single file
await add(['README.md']);

// Stage multiple files
await add(['src/index.ts', 'src/utils.ts']);

// Stage a directory
await add(['src/']);

// Stage all files in current directory
await add('.');

​
Commit Variations

​
Basic Commit

Create a standard commit with staged changes: 
import { commit } from 'usegit';

await commit('fix: resolve login bug');

​
Commit with Description

Add a detailed description to provide context: 
import { commit } from 'usegit';

await commit(
  'refactor: reorganize component structure',
  'Moves components into feature-based directories for better organization. This improves code discoverability and maintains clearer separation of concerns.'
);

​
Commit All Tracked Changes

Skip the staging step for tracked files: 
import { commitAll } from 'usegit';

// Stage and commit all tracked files in one step
await commitAll(
  'chore: update dependencies',
  'Bumps all packages to latest stable versions'
);
Use commitAll() when you want to commit all modified tracked files without explicitly running add() first. This is equivalent to git commit -a.

​
Real-World Example

Here’s a practical example of a complete workflow: 
import { 
  init, 
  add, 
  commit, 
  status, 
  isCleanWorkingTree,
  diffStaged 
} from 'usegit';

async function setupProject() {
  // Initialize repository
  console.log('Initializing repository...');
  await init();

  // Create initial project files (simulated)
  // ... (your file creation logic)

  // Check status
  console.log('Checking status...');
  const statusResult = await status();
  console.log(statusResult);

  // Stage all files
  console.log('Staging files...');
  await add('.');

  // Review what will be committed
  const staged = await diffStaged();
  console.log('Staged changes:', staged);

  // Create initial commit
  console.log('Creating initial commit...');
  await commit(
    'feat: initial project setup',
    'Sets up project structure with configuration files and basic dependencies'
  );

  // Verify clean state
  const isClean = await isCleanWorkingTree();
  console.log('Working tree is clean:', isClean);
}

setupProject();

​
Next Steps

Branch Management

Learn how to create, switch, and manage branches

Commit Operations

Explore advanced commit techniques

Build docs developers (and LLMs) love

Get started for freeTalk to us