From 89ff46ab49e1aee1fb79d9aec9b4be6ea5c1c496 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 5 Dec 2025 14:47:27 +0000 Subject: [PATCH 1/2] Add guidance for cloning multiple repositories - Added new section 'Working with Multiple Repositories' to prompting best practices - Covers common scenarios: frontend/backend splits, microservices, shared libraries - Documents two methods: repository configuration files and ad-hoc prompting - Includes best practices and practical examples for multi-repo workflows - Addresses real-world use case of accessing related repositories during development Co-authored-by: openhands --- .../usage/tips/prompting-best-practices.mdx | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/openhands/usage/tips/prompting-best-practices.mdx b/openhands/usage/tips/prompting-best-practices.mdx index f873bb32..64651f8e 100644 --- a/openhands/usage/tips/prompting-best-practices.mdx +++ b/openhands/usage/tips/prompting-best-practices.mdx @@ -35,4 +35,58 @@ Good prompts are: The more precise and informative your prompt, the better OpenHands can assist you. +## Working with Multiple Repositories + +When working on projects that span multiple repositories, you can instruct OpenHands to clone additional repositories using your Git provider token. This is particularly useful when you need OpenHands to be aware of code in related repositories. + +### Common Scenarios + +- **Frontend/Backend Split**: Starting in a `backend` repo but needing access to UI code in a `frontend` repo +- **Microservices**: Working across multiple service repositories +- **Shared Libraries**: Accessing common utilities or components from separate repositories + +### Methods for Cloning Additional Repos + +#### 1. Repository Configuration Files + +You can include cloning instructions in your repository's configuration files: + +- **`repo.md`**: Add instructions for OpenHands to clone related repositories +- **`agents.md`**: Include repository setup as part of agent initialization + +Example in `repo.md`: +```markdown +## Related Repositories + +Please clone the following related repositories for full context: + +```bash +git clone https://github.com/your-org/frontend-repo.git ../frontend +git clone https://github.com/your-org/shared-utils.git ../shared-utils +``` + +#### 2. Ad-hoc Prompting + +During a conversation, you can directly instruct OpenHands to clone additional repositories: + +**Example prompts:** +- "Please clone our frontend repository from `https://github.com/our-org/frontend-repo.git` so you can see the UI components that interact with this API." +- "Clone the shared utilities repo at `https://github.com/our-org/utils.git` into a `../utils` directory so you can reference the helper functions." +- "I need you to access our documentation repo. Please clone `https://github.com/our-org/docs.git` to understand the API specifications." + +### Best Practices for Multi-Repo Workflows + +- **Specify clone location**: Use relative paths like `../repo-name` to keep repositories organized +- **Provide context**: Explain why the additional repository is needed +- **Use your Git token**: OpenHands will automatically use your configured Git provider token for authentication +- **Be explicit about relationships**: Describe how the repositories relate to each other + +### Example Multi-Repo Prompt + +``` +I'm working on the user authentication API in this backend repo, but I need to understand how the frontend handles login flows. Please clone our frontend repository from https://github.com/our-company/frontend-app.git into ../frontend so you can see the login components and help me ensure the API responses match what the frontend expects. +``` + +This approach allows OpenHands to have full context across your entire project ecosystem, leading to better suggestions and more accurate implementations. + See [First Projects](/overview/first-projects) for more examples of helpful prompts. From 1a96e5ff973fde69d5c4fc2aaa680c7327eff300 Mon Sep 17 00:00:00 2001 From: openhands Date: Fri, 5 Dec 2025 14:50:43 +0000 Subject: [PATCH 2/2] Move multi-repo content to separate document - Created new 'Working with Multiple Repos' document under Tips and Tricks - Moved all multi-repo content from prompting-best-practices.mdx to the new document - Updated docs.json navigation to include the new document - Kept the reference to First Projects in the original prompting document Co-authored-by: openhands --- docs.json | 3 +- .../usage/tips/prompting-best-practices.mdx | 54 ------------------ .../tips/working-with-multiple-repos.mdx | 56 +++++++++++++++++++ 3 files changed, 58 insertions(+), 55 deletions(-) create mode 100644 openhands/usage/tips/working-with-multiple-repos.mdx diff --git a/docs.json b/docs.json index ddeff833..7bffb94c 100644 --- a/docs.json +++ b/docs.json @@ -52,7 +52,8 @@ { "group": "Tips and Tricks", "pages": [ - "openhands/usage/tips/prompting-best-practices" + "openhands/usage/tips/prompting-best-practices", + "openhands/usage/tips/working-with-multiple-repos" ] }, { diff --git a/openhands/usage/tips/prompting-best-practices.mdx b/openhands/usage/tips/prompting-best-practices.mdx index 64651f8e..f873bb32 100644 --- a/openhands/usage/tips/prompting-best-practices.mdx +++ b/openhands/usage/tips/prompting-best-practices.mdx @@ -35,58 +35,4 @@ Good prompts are: The more precise and informative your prompt, the better OpenHands can assist you. -## Working with Multiple Repositories - -When working on projects that span multiple repositories, you can instruct OpenHands to clone additional repositories using your Git provider token. This is particularly useful when you need OpenHands to be aware of code in related repositories. - -### Common Scenarios - -- **Frontend/Backend Split**: Starting in a `backend` repo but needing access to UI code in a `frontend` repo -- **Microservices**: Working across multiple service repositories -- **Shared Libraries**: Accessing common utilities or components from separate repositories - -### Methods for Cloning Additional Repos - -#### 1. Repository Configuration Files - -You can include cloning instructions in your repository's configuration files: - -- **`repo.md`**: Add instructions for OpenHands to clone related repositories -- **`agents.md`**: Include repository setup as part of agent initialization - -Example in `repo.md`: -```markdown -## Related Repositories - -Please clone the following related repositories for full context: - -```bash -git clone https://github.com/your-org/frontend-repo.git ../frontend -git clone https://github.com/your-org/shared-utils.git ../shared-utils -``` - -#### 2. Ad-hoc Prompting - -During a conversation, you can directly instruct OpenHands to clone additional repositories: - -**Example prompts:** -- "Please clone our frontend repository from `https://github.com/our-org/frontend-repo.git` so you can see the UI components that interact with this API." -- "Clone the shared utilities repo at `https://github.com/our-org/utils.git` into a `../utils` directory so you can reference the helper functions." -- "I need you to access our documentation repo. Please clone `https://github.com/our-org/docs.git` to understand the API specifications." - -### Best Practices for Multi-Repo Workflows - -- **Specify clone location**: Use relative paths like `../repo-name` to keep repositories organized -- **Provide context**: Explain why the additional repository is needed -- **Use your Git token**: OpenHands will automatically use your configured Git provider token for authentication -- **Be explicit about relationships**: Describe how the repositories relate to each other - -### Example Multi-Repo Prompt - -``` -I'm working on the user authentication API in this backend repo, but I need to understand how the frontend handles login flows. Please clone our frontend repository from https://github.com/our-company/frontend-app.git into ../frontend so you can see the login components and help me ensure the API responses match what the frontend expects. -``` - -This approach allows OpenHands to have full context across your entire project ecosystem, leading to better suggestions and more accurate implementations. - See [First Projects](/overview/first-projects) for more examples of helpful prompts. diff --git a/openhands/usage/tips/working-with-multiple-repos.mdx b/openhands/usage/tips/working-with-multiple-repos.mdx new file mode 100644 index 00000000..730ebb40 --- /dev/null +++ b/openhands/usage/tips/working-with-multiple-repos.mdx @@ -0,0 +1,56 @@ +--- +title: Working with Multiple Repos +description: Learn how to instruct OpenHands to clone and work with multiple repositories in your project ecosystem. +--- + +When working on projects that span multiple repositories, you can instruct OpenHands to clone additional repositories using your Git provider token. This is particularly useful when you need OpenHands to be aware of code in related repositories. + +## Common Scenarios + +- **Frontend/Backend Split**: Starting in a `backend` repo but needing access to UI code in a `frontend` repo +- **Microservices**: Working across multiple service repositories +- **Shared Libraries**: Accessing common utilities or components from separate repositories + +## Methods for Cloning Additional Repos + +### 1. Repository Configuration Files + +You can include cloning instructions in your repository's configuration files: + +- **`repo.md`**: Add instructions for OpenHands to clone related repositories +- **`agents.md`**: Include repository setup as part of agent initialization + +Example in `repo.md`: +```markdown +## Related Repositories + +Please clone the following related repositories for full context: + +```bash +git clone https://github.com/your-org/frontend-repo.git ../frontend +git clone https://github.com/your-org/shared-utils.git ../shared-utils +``` + +### 2. Ad-hoc Prompting + +During a conversation, you can directly instruct OpenHands to clone additional repositories: + +**Example prompts:** +- "Please clone our frontend repository from `https://github.com/our-org/frontend-repo.git` so you can see the UI components that interact with this API." +- "Clone the shared utilities repo at `https://github.com/our-org/utils.git` into a `../utils` directory so you can reference the helper functions." +- "I need you to access our documentation repo. Please clone `https://github.com/our-org/docs.git` to understand the API specifications." + +## Best Practices for Multi-Repo Workflows + +- **Specify clone location**: Use relative paths like `../repo-name` to keep repositories organized +- **Provide context**: Explain why the additional repository is needed +- **Use your Git token**: OpenHands will automatically use your configured Git provider token for authentication +- **Be explicit about relationships**: Describe how the repositories relate to each other + +## Example Multi-Repo Prompt + +``` +I'm working on the user authentication API in this backend repo, but I need to understand how the frontend handles login flows. Please clone our frontend repository from https://github.com/our-company/frontend-app.git into ../frontend so you can see the login components and help me ensure the API responses match what the frontend expects. +``` + +This approach allows OpenHands to have full context across your entire project ecosystem, leading to better suggestions and more accurate implementations. \ No newline at end of file