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.
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.
Paths
To include paths from any repository, enter /Path and select the corresponding command. Then, choose the path you want and finalize your selection.
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:
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.
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:
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.
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.
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.
This document is automatically kept up to date using Swimm.