Skip to main content

Multi-repo content

With Swimm, you can describe flows spanning across multiple repositories, by including snippets, tokens and paths from multiple repositories, in the Web app and IDE.

Web app

Snippets

To insert a snippet from a repository other than your current one, bring up the Snippet Studio (/Code snippet), then click All repos to choose the desired repository and file for your snippet.

Multi-repo snippets in Swimm's web app

Tokens

Type backtick ` or /Smart Token, followed by your specific token reference (like a variable or class). Swimm will then offer suggestions from various repositories. You can modify your search scope by clicking the repository dropdown to select or deselect repositories.

Multi-repo Smart Tokens in Swimm's web app

Paths

To include paths from any repository, enter /Path and select the corresponding command. Then, choose the path you want and finalize your selection.

Multi-repo Paths in Swimm's web app

IDE

Important note:

Ensure that the repository is a part of your Swimm workspace to add a code-coupled element. Otherwise, if you add code referenced from a repository that is not part of your workspace, you will add an untracked, standard, Markdown code block.

See the difference below when adding a /Code Snippet:

Multi-repo content for Swimm docs in your IDE

VS Code

While in VS Code, you are able to add a /Code Snippet, /Smart Token and /Path from your current repository or any other repository you have access to in two ways in the same open window:

1. VS Code workspace file with multiple repositories.

VS Code allows you to create a multi-root workspace file, which can include multiple repositories. This way, you can access all the repositories in the same window and easily add snippets, tokens, and paths from any of them.

In the example below, we create a Swimm document that lives in the git-src-playground repository, and successfully added a /Code snippet from another repository, docs.swimm.io.

Multi-repo content for Swimm docs in your IDE

2. One repository open in active window

Swimm works best when repositories are add at the root/parent level in your IDE, within the same window. If you would like to reference code from a repository that is not part of your active window, you can do so by opening the desired file and executing your desired Swimm command for the code snippet, token, or path you need.

See example:

Multi-repo content for Swimm docs in your IDE

JetBrains

Adding multi-repo code referencing in JetBrains IDEs is similar to VS Code. You can add a /Code Snippet, /Smart Token and /Path from your current repository or any other repository you have access to in the same open window, across your tabs.

Multi-repo content for Swimm docs in your IDE

How will multi-repo content affect my CI checks?

Consider this example: You're working in a repository named backend-repo and create a document linking to elements from both backend-repo and frontend-repo. When Swimm is integrated with your Continuous Integration (CI) system, it performs checks on every pull request. If there's an outdated code reference in backend-repo, the CI check will fail and Swimm will either update the reference or notify you, based on the change and your settings.

However, if a code reference in frontend-repo becomes outdated, it won't trigger a CI check failure. This design prevents awkward development scenarios where a pull request in backend-repo is held up awaiting changes in frontend-repo, or vice versa. That way, changes in frontend-repo impacting documents in backend-repo will not result in notifications.

Generally, these notifications appear as comments on the pull request or merge request page and can also be sent to Slack if Swimm's Slack App is in use.

Review outdated docs in a Github pull request

You'll receive notifications prior to and following the merging of changes into the default branch.

In the example above, Swimm's Review outdated page will label the document as outdated and offer options for updating it. Additionally, when you read or edit this document, any outdated references (from either repository) will be flagged, allowing you to make necessary edits to the document.

Review outdated docs in Swimm's web app

This document is automatically kept up to date using Swimm.