feat: add GitTool for git operations

[divyanshu-iitian]

Summary

This PR adds GitTool, a comprehensive git operations tool that enables AI agents to autonomously perform version control tasks. The tool provides a structured interface to 14 essential git commands, allowing agents to manage repositories, branches, commits, and remotes as part of their workflows.

Key Features:

• 14 git commands: status, add, commit, push, pull, branch, checkout, diff, log, clone, init, reset, stash, remote
• Secure subprocess-based execution with timeout protection
• Structured observations for agent decision-making
• Rich terminal-style visualization
• Comprehensive parameter validation

What's Included:

• Core tool implementation (openhands-tools/openhands/tools/git/)
• 53 comprehensive tests covering all operations (tests/tools/git/)
• Working example demonstrating automated git workflow (examples/01_standalone_sdk/40_git_workflow_automation.py)
• Documentation with usage examples and security notes

Architecture:

• Follows existing tool patterns (TerminalTool, FileEditorTool)
• Builds on openhands.sdk.git utilities
• Proper error handling and validation
• No breaking changes to existing code

Use Cases:

• Automated commit workflows
• Branch management in multi-agent systems
• Code review automation
• CI/CD integration
• Version control in autonomous development tasks

Checklist

• If the PR is changing/adding functionality, are there tests to reflect this?
  • Yes, 53 tests covering all git commands and edge cases
• If there is an example, have you run the example to make sure that it works?
  • Yes, 40_git_workflow_automation.py tested successfully
• If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
  • Yes, tool follows standard OpenHands SDK patterns
• If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
  • Tool-level README included; can create docs PR if maintainers prefer
• Is the github CI passing?
  • Will verify after PR creation

[all-hands-bot]

[Automatic Post]: I have assigned @enyst as a reviewer based on git blame information. Thanks in advance for the help!

[enyst]

Hey @divyanshu-iitian , thank you for the contribution!

OpenHands agent does all git operations, using terminal tool most of the time: LLMs know git, gh, and other common tools very very well.

It's possible it would more difficult, not easier, for the LLM to use correctly a new tool that looks like git but it's a tool with a different format than the git command itself. 🤷

Did you encounter problems with OpenHands using git?

[divyanshu-iitian]

Hi @enyst, thank you for the detailed feedback! You're absolutely right.

I made an assumption without validating the actual need - agents already use git perfectly through the terminal tool, and LLMs know git commands very well. A separate structured tool would indeed add unnecessary cognitive overhead.

However, your feedback made me realize a different gap: agents currently cannot interact with GitHub's API (forking repos, creating PRs, managing issues, etc.). They can do local git operations but not remote GitHub operations.

Would a GitHub API Integration Tool (using PAT tokens) be more useful? It could enable:

• Fork repositories to user's account
• Create pull requests programmatically
• Manage issues and comments
• Create branches remotely
• Complete contribution workflows automation

This would extend agent capabilities rather than duplicate existing terminal functionality. The git utilities in openhands.sdk.git could even be leveraged for some operations.

If this sounds useful, I'm happy to:

1. Close this PR
2. Open a discussion for the GitHub API tool proposal
3. Implement it properly after getting feedback

Or if you have other areas where contributions would be more valuable, I'd love to hear! Thank you for the learning opportunity. 🙏

[enyst]

However, your feedback made me realize a different gap: agents currently cannot interact with GitHub's API (forking repos, creating PRs, managing issues, etc.). They can do local git operations but not remote GitHub operations.

Would a GitHub API Integration Tool (using PAT tokens) be more useful? It could enable:

OpenHands agent can do that too! 😄

Just give it a PAT token. It can use gh or REST API, or if you configure it, the Github MCP.

Or if you have other areas where contributions would be more valuable, I'd love to hear! Thank you for the learning opportunity. 🙏

I suggest to use OpenHands for your needs. For example, via the CLI. See where it falls short of what you'd like, and please feel free to fix what you don't like.

It's the best way to improve it, and to learn while doing.