Git Status

Monitor the state of your Git repository and track changes.

Get Repository Status

Get the current status of your Git repository.

// Using SDK
const status = await sandbox.git.status({
  repoPath: '/opt/app'
});

console.log('Modified:', status.modified);
console.log('Staged:', status.staged);
console.log('Untracked:', status.untracked);

POST /git/status HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "repoPath": "/opt/app"
}

Response:

{
  "success": true,
  "status": {
    "modified": ["src/index.js", "README.md"],
    "staged": ["package.json"],
    "untracked": ["new-file.js"],
    "deleted": [],
    "renamed": [],
    "clean": false
  },
  "branch": "main",
  "ahead": 2,
  "behind": 0
}

Response Fields:

Field	Type	Description
`modified`	array	Modified but not staged files
`staged`	array	Files staged for commit
`untracked`	array	New files not tracked by Git
`deleted`	array	Deleted files
`renamed`	array	Renamed files
`clean`	boolean	True if no changes
`branch`	string	Current branch name
`ahead`	number	Commits ahead of remote
`behind`	number	Commits behind remote

Check for Changes

Determine if there are uncommitted changes:

const status = await sandbox.git.status({ repoPath: '/opt/app' });

if (status.status.clean) {
  console.log('No changes to commit');
} else {
  console.log('You have uncommitted changes');
  
  // Show what changed
  if (status.status.modified.length > 0) {
    console.log('Modified files:', status.status.modified);
  }
  
  if (status.status.untracked.length > 0) {
    console.log('New files:', status.status.untracked);
  }
}

Track Sync Status

Check if your branch is in sync with remote:

const status = await sandbox.git.status({ repoPath: '/opt/app' });

if (status.ahead > 0) {
  console.log(`You have ${status.ahead} commit(s) to push`);
}

if (status.behind > 0) {
  console.log(`You are ${status.behind} commit(s) behind remote`);
  // Pull changes
  await sandbox.git.pull({ repoPath: '/opt/app' });
}

Common Workflows

Pre-Commit Check

// Check what will be committed
const status = await sandbox.git.status({ repoPath: '/opt/app' });

if (status.status.staged.length === 0) {
  console.log('No files staged for commit');
  
  // Stage modified files
  if (status.status.modified.length > 0) {
    await sandbox.git.add({
      repoPath: '/opt/app',
      files: status.status.modified
    });
  }
}

// Now commit
await sandbox.git.commit({
  repoPath: '/opt/app',
  message: 'Update files'
});

Auto-Stage All Changes

const status = await sandbox.git.status({ repoPath: '/opt/app' });

// Combine modified and untracked
const allChanges = [
  ...status.status.modified,
  ...status.status.untracked
];

if (allChanges.length > 0) {
  await sandbox.git.add({
    repoPath: '/opt/app',
    files: allChanges
  });
  
  await sandbox.git.commit({
    repoPath: '/opt/app',
    message: 'Auto-commit all changes'
  });
}

Pre-Push Validation

// Check if everything is committed
const status = await sandbox.git.status({ repoPath: '/opt/app' });

if (!status.status.clean) {
  console.log('Warning: You have uncommitted changes');
  console.log('Modified:', status.status.modified);
  return;
}

// Check if you're ahead
if (status.ahead === 0) {
  console.log('Nothing to push');
  return;
}

// Safe to push
console.log(`Pushing ${status.ahead} commits...`);
await sandbox.git.push({ repoPath: '/opt/app' });

Status Output Examples

Clean Repository

{
  "success": true,
  "status": {
    "modified": [],
    "staged": [],
    "untracked": [],
    "deleted": [],
    "renamed": [],
    "clean": true
  },
  "branch": "main",
  "ahead": 0,
  "behind": 0
}

Uncommitted Changes

{
  "success": true,
  "status": {
    "modified": ["src/app.js"],
    "staged": [],
    "untracked": ["test.js"],
    "deleted": ["old-file.js"],
    "renamed": [],
    "clean": false
  },
  "branch": "develop",
  "ahead": 0,
  "behind": 1
}

Staged for Commit

{
  "success": true,
  "status": {
    "modified": [],
    "staged": ["src/index.js", "README.md"],
    "untracked": [],
    "deleted": [],
    "renamed": [],
    "clean": false
  },
  "branch": "feature/new-ui",
  "ahead": 0,
  "behind": 0
}

Best Practices

1. Check Status Before Operations

// Always check before committing
const status = await sandbox.git.status({ repoPath: '/opt/app' });

if (status.status.staged.length > 0) {
  await sandbox.git.commit({ ... });
}

2. Review Changes Before Push

const status = await sandbox.git.status({ repoPath: '/opt/app' });

// Show what will be pushed
if (status.ahead > 0) {
  const history = await sandbox.git.history({
    repoPath: '/opt/app',
    limit: status.ahead
  });
  
  console.log('Commits to push:');
  history.commits.forEach(c => console.log(`  - ${c.message}`));
  
  // Confirm and push
  await sandbox.git.push({ repoPath: '/opt/app' });
}

3. Handle Merge Conflicts

const status = await sandbox.git.status({ repoPath: '/opt/app' });

if (status.status.conflicted && status.status.conflicted.length > 0) {
  console.log('Merge conflicts detected:', status.status.conflicted);
  // Resolve conflicts manually
}

Next Steps

Learn about Git Branches
Explore Git Clone
Check Snapshots for version control

On this page