Git Commits

Learn how to stage files, create commits, and push changes to remote repositories.

Add Files to Staging

Stage files for commit.

// Using SDK
await sandbox.git.add({
  repoPath: '/opt/app',
  files: ['src/index.js', 'package.json']
});

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

{
  "repoPath": "/opt/app",
  "files": ["src/index.js", "package.json"]
}

Response:

{
  "success": true,
  "message": "Files added to staging",
  "files": ["src/index.js", "package.json"]
}

Parameters:

Parameter	Type	Required	Description
`repoPath`	string	Yes	Path to Git repository
`files`	array	Yes	Array of file paths to stage

Examples:

// Stage specific files
await sandbox.git.add({
  repoPath: '/opt/app',
  files: ['file1.js', 'file2.js']
});

// Stage all files in directory
await sandbox.git.add({
  repoPath: '/opt/app',
  files: ['.'] // Stages everything
});

// Stage all JavaScript files
await sandbox.git.add({
  repoPath: '/opt/app',
  files: ['*.js']
});

Commit Changes

Create a commit with staged files.

// Using SDK
await sandbox.git.commit({
  repoPath: '/opt/app',
  message: 'Add new feature',
  author: {
    name: 'AI Agent',
    email: 'ai@oblien.com'
  }
});

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

{
  "repoPath": "/opt/app",
  "message": "Add new feature",
  "author": {
    "name": "AI Agent",
    "email": "ai@oblien.com"
  }
}

Response:

{
  "success": true,
  "message": "Changes committed",
  "commit": "a1b2c3d4e5f6",
  "files": 2,
  "insertions": 45,
  "deletions": 12
}

Parameters:

Parameter	Type	Required	Description
`repoPath`	string	Yes	Path to Git repository
`message`	string	Yes	Commit message
`author`	object	No	Author info `{name, email}`

Push to Remote

Push commits to remote repository.

// Using SDK
await sandbox.git.push({
  repoPath: '/opt/app',
  branch: 'main',
  force: false,
  auth: {
    type: 'token',
    token: process.env.GITHUB_TOKEN
  }
});

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

{
  "repoPath": "/opt/app",
  "branch": "main",
  "force": false,
  "auth": {
    "type": "token",
    "token": "ghp_xxxxxxxxxxxx"
  }
}

Response:

{
  "success": true,
  "message": "Changes pushed successfully",
  "branch": "main",
  "commits": 3
}

Parameters:

Parameter	Type	Required	Description
`repoPath`	string	Yes	Path to Git repository
`branch`	string	No	Branch to push (default: current)
`force`	boolean	No	Force push (default: false)
`auth`	object	No	Authentication config

Pull from Remote

Pull latest changes from remote repository.

// Using SDK
await sandbox.git.pull({
  repoPath: '/opt/app',
  branch: 'main',
  auth: {
    type: 'token',
    token: process.env.GITHUB_TOKEN
  }
});

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

{
  "repoPath": "/opt/app",
  "branch": "main",
  "auth": {
    "type": "token",
    "token": "ghp_xxxxxxxxxxxx"
  }
}

Response:

{
  "success": true,
  "message": "Changes pulled successfully",
  "files": 5,
  "commits": 2,
  "branch": "main"
}

View Commit History

Get repository commit history.

// Using SDK
const history = await sandbox.git.history({
  repoPath: '/opt/app',
  limit: 10
});

history.commits.forEach(commit => {
  console.log(`${commit.hash.substring(0, 7)} - ${commit.message}`);
});

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

{
  "repoPath": "/opt/app",
  "limit": 10
}

Response:

{
  "success": true,
  "commits": [
    {
      "hash": "a1b2c3d4e5f6",
      "author": "AI Agent <ai@oblien.com>",
      "date": "2025-10-16T12:00:00Z",
      "message": "Add new feature",
      "files": 3
    }
  ],
  "total": 42
}

Parameters:

Parameter	Type	Required	Description
`repoPath`	string	Yes	Path to Git repository
`limit`	number	No	Number of commits (default: 20)

Complete Workflow

Here's a complete Git workflow from start to finish:

// 1. Check status
const status = await sandbox.git.status({ repoPath: '/opt/app' });
console.log('Modified files:', status.modified);

// 2. Stage files
await sandbox.git.add({
  repoPath: '/opt/app',
  files: status.modified
});

// 3. Commit changes
await sandbox.git.commit({
  repoPath: '/opt/app',
  message: 'Fix: Resolve authentication bug',
  author: {
    name: 'Blurs AI',
    email: 'blurs@oblien.com'
  }
});

// 4. Push to remote
await sandbox.git.push({
  repoPath: '/opt/app',
  auth: {
    type: 'token',
    token: process.env.GITHUB_TOKEN
  }
});

console.log('Changes pushed successfully!');

Best Practices

1. Always Pull Before Push

// Pull latest changes first
await sandbox.git.pull({ repoPath: '/opt/app' });

// Make your changes...
await sandbox.files.edit({ ... });

// Commit and push
await sandbox.git.add({ ... });
await sandbox.git.commit({ ... });
await sandbox.git.push({ ... });

2. Write Meaningful Commit Messages

// ✅ Good commit messages
'feat: Add user authentication'
'fix: Resolve memory leak in file handler'
'docs: Update API documentation'

// ❌ Bad commit messages
'update'
'fix bug'
'changes'

3. Use Conventional Commits

// Format: <type>: <description>

await sandbox.git.commit({
  repoPath: '/opt/app',
  message: 'feat: Add email validation'
});

// Types: feat, fix, docs, style, refactor, test, chore

4. Commit Frequently

Create small, focused commits:

// ✅ Good - small focused commits
await sandbox.git.commit({ message: 'Add login form' });
await sandbox.git.commit({ message: 'Add form validation' });
await sandbox.git.commit({ message: 'Add error handling' });

// ❌ Bad - one huge commit
await sandbox.git.commit({ message: 'Add entire auth system' });

Error Handling

try {
  await sandbox.git.push({ repoPath: '/opt/app' });
} catch (error) {
  if (error.message.includes('rejected')) {
    console.log('Push rejected - pull first');
    await sandbox.git.pull({ repoPath: '/opt/app' });
    await sandbox.git.push({ repoPath: '/opt/app' });
  } else if (error.message.includes('authentication')) {
    console.log('Authentication failed - check your token');
  }
}

Next Steps

Check Git Status for tracking changes
Learn about Git Clone for repository setup
Explore Snapshots for version control

On this page