{"id":15629790,"url":"https://github.com/simonbs/dependency-graph","last_synced_at":"2025-04-06T10:11:26.858Z","repository":{"id":64690103,"uuid":"575900640","full_name":"simonbs/dependency-graph","owner":"simonbs","description":"🕸️ dependency-graph is a command-line tool that can visualize the dependencies of packages.","archived":false,"fork":false,"pushed_at":"2024-06-21T15:31:32.000Z","size":5886,"stargazers_count":298,"open_issues_count":8,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-30T09:09:41.349Z","etag":null,"topics":["ios","macos","swift","swiftpackage","swiftpackagemanager","xcode"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonbs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"simonbs"}},"created_at":"2022-12-08T14:54:21.000Z","updated_at":"2025-03-30T00:34:19.000Z","dependencies_parsed_at":"2024-10-23T01:03:58.467Z","dependency_job_id":null,"html_url":"https://github.com/simonbs/dependency-graph","commit_stats":{"total_commits":100,"total_committers":6,"mean_commits":"16.666666666666668","dds":"0.050000000000000044","last_synced_commit":"1c9b5f786995a5b915c52cc025b14a03807c9b34"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonbs%2Fdependency-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonbs%2Fdependency-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonbs%2Fdependency-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonbs%2Fdependency-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonbs","download_url":"https://codeload.github.com/simonbs/dependency-graph/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464220,"owners_count":20942970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ios","macos","swift","swiftpackage","swiftpackagemanager","xcode"],"created_at":"2024-10-03T10:28:46.857Z","updated_at":"2025-04-06T10:11:26.838Z","avatar_url":"https://github.com/simonbs.png","language":"Swift","readme":"# 🕸️ dependency-graph\n\n[![Build and Test](https://github.com/simonbs/dependency-graph/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/simonbs/dependency-graph/actions/workflows/build_and_test.yml) [![SwiftLint](https://github.com/simonbs/dependency-graph/actions/workflows/swiftlint.yml/badge.svg)](https://github.com/simonbs/dependency-graph/actions/workflows/swiftlint.yml)\n\ndependency-graph is a command-line tool that can visualize the dependencies of packages. The tool takes the path to an Xcode project or a Package.swift file as input and outputs a graph that shows the dependencies of the packages in the project or package.\n\n## 👀 Examples\n\nThe following graphs are examples of the graphs that dependency-graph can output. The first graph built by providing dependency-graph the path to a Package.swift file and the second graph was made by providing dependency-graph the path to an .xcodeproj file as input.\n\n|Swift Package|Xcode Project|\n|-|-|\n|\u003cimg width=\"400\" src=\"./example-swift-package.png\" alt=\"Example graph showing the dependencies of this package.\" /\u003e|\u003cimg width=\"400\" src=\"./example-xcodeproj.png\" alt=\"Example graph showing the dependencies of an Xcode project.\" /\u003e|\n\nNodes shaped as ellipsis represent products, e.g. the libraries in a Swift package, and the square nodes represent targets.\n\n## 🚀 Getting Started\n\nStart off by installing the tool with [Homebrew](https://brew.sh).\n\n```bash\nbrew tap simonbs/dependency-graph https://github.com/simonbs/dependency-graph.git\nbrew install dependency-graph\n```\n\n\u003e **Note**\n\u003e If you get the following error when attempting to install dependency-graph:\n\u003e\n\u003e ```\n\u003e Error: Cannot install under Rosetta 2 in ARM default prefix (/opt/homebrew)!\n\u003e To rerun under ARM use:\n\u003e    arch -arm64 brew install ...\n\u003e To install under x86_64, install Homebrew into /usr/local.\n\u003e ```\n\u003e\n\u003e You can use the the following to install dependency-graph:\n\u003e\n\u003e ```bash\n\u003e arch -arm64 brew install dependency-graph\n\u003e ```\n\nYou may now run the following command to verify that the tool was installed correctly. The following command should print information on how the tool can be used.\n\n```\ndependency-graph --help\n```\n\nRun the `dependency-graph` command with the path to a folder containing an .xcodeproj or Package.swift file.\n\n```bash\ndependency-graph ~/Developer/Example\n```\n\nYou may also pass the full path to the .xcodeproj or Package.swift file as shown below.\n\n```bash\ndependency-graph ~/Developer/Example/Example.xcodeproj\n```\n\n### Rendering a Graph\n\nThe `dependency-graph` command will output a textual representation of a graph. By default the tool will output a graph using the [DOT syntax](https://graphviz.org/doc/info/lang.html). For example, if the Xcode project or Package.swift file contains the following dependencies:\n\n```\nLibrary A in Package A depends on Target A\nLibrary B in Package B depends on Target B\nLibrary A in Package A depends on Library B in Package B\n```\n\nThe output of the tool would be a graph that looks like this:\n\n```dot\ndigraph g {\n  subgraph cluster_packageA {\n    label=\"Package A\"\n    libraryA [label=\"LibraryB\", shape=ellipse]\n    targetA [label=\"TargetA\", shape=box]\n  }\n\n  subgraph cluster_packageB {\n    label=\"Package B\"\n    libraryB [label=\"LibraryB\", shape=ellipse]\n    targetB [label=\"TargetB\", shape=box]\n  }\n\n  libraryA -\u003e targetA\n  libraryB -\u003e targetB\n  libraryA -\u003e libraryB\n}\n```\n\nThe output can be rendered to an image by piping it to a renderer. See the following sections for details on the supported renderers.\n\n#### DOT\n\n\u003cimg width=\"400\" src=\"./example-dot.png\" alt=\"Example graph rendered with dot.\" /\u003e\n\nBy default dependency-graph will use the DOT syntax which can be rendered by the [dot CLI](https://graphviz.org/doc/info/command.html), which is part of [Graphviz](https://graphviz.org).\n\nInstall Graphviz and run `dependency-graph` and pass the output to the newly installed `dot` CLI.\n\n```bash\nbrew install graphviz\ndependency-graph ~/Developer/Example | dot -Tsvg -o graph.svg\n```\n\nWhen rendering the graph to a PNG, you will likely want to specify the size of the output to ensure it is readable. To generate an image with dot that is exactly 6000 pixels wide or 8000 pixels tall but not necessarily both, do the following:\n\n```bash\ndependency-graph ~/Developer/Example | dot -Tpng -Gsize=60,80\\! -Gdpi=100 -o graph.png\n```\n\nYou may want to play around with the values for `--node-spacing` and `--rank-spacing` to increase the readability of the graph.\n\n```bash\ndependency-graph --node-spacing 50 --rank-spacing 150 ~/Developer/Example | dot -Tsvg -o graph.svg\n```\n\nFor large projects the graph may become unreadable. Passing the output through Grahpviz' [unflatten](https://graphviz.org/docs/cli/unflatten/) command may improve the results.\n\n```bash\ndependency-graph ~/Developer/Example | unflatten -l 100 -c 100 -f | dot -Tpng -o graph.png\n```\n\n#### Mermaid\n\n\u003cimg width=\"400\" src=\"./example-mermaid.png\" alt=\"Example graph rendered with mermaid.\" /\u003e\n\nSpecify the `--syntax mermaid` option to have dependency-graph output a graph using [the Mermaid diagram syntax](https://mermaid-js.github.io/mermaid/#/flowchart).\n\nThe output be rendered to an image using the [the mermaid cli](https://github.com/mermaid-js/mermaid-cli).\n\n```bash\nnpm install -g @mermaid-js/mermaid-cli\ndependency-graph --syntax mermaid ~/Developer/Example | mmdc -o graph.svg\n```\n\nTo generate an image on a page that is 6000 pixels wide with mermaid, do the following:\n\n```bash\ndependency-graph --syntax mermaid ~/Developer/Example | mmdc -o graph.png -w 6000\n```\n\nYou may also want to play around with the values for `--node-spacing` and `--rank-spacing` to increase the readability of the graph.\n\n```bash\ndependency-graph --syntax mermaid --node-spacing 50 --rank-spacing 150 ~/Developer/Example | mmdc -o graph.png\n```\n\n#### D2\n\n\u003cimg width=\"400\" src=\"./example-d2.png\" alt=\"Example graph rendered with D2.\" /\u003e\n\nSpecify the `--syntax d2` option to have dependency-graph output a graph using [the d2 scripting language](https://d2lang.com/tour/intro).\n\nThe output be rendered to an image using the [the d2 cli](https://github.com/terrastruct/d2#install).\n\n```bash\ncurl -fsSL https://d2lang.com/install.sh | sh -s --\ndependency-graph --syntax d2 ~/Developer/Example | d2 - graph.png\n```\n\nThe ELK layout engine renders some quite tidy graphs, as shown in the example below.\n\n\u003cimg width=\"400\" src=\"./example-d2-elk.png\" alt=\"Example graph rendered with D2 and the ELK layout engine.\" /\u003e\n\n## Graphing Packages Only\n\nPass the `--packages-only` flag to include only the Xcode project and Swift packages in the graph. This omits the libraries and targets within the Xcode project and Swift packages.\n\n\u003cimg width=\"400\" src=\"./example-packages-only.png\" alt=\"Example graph showing only an Xcode project and Swift packages.\" /\u003e\n\n## 🤷‍♂️ OK, why?\n\nAs I'm splitting my iOS and macOS applications into small Swift packages with several small targets, I started wishing for a way to visualise the relationship between the products and targets in my Swift packages. That's why I built this tool.\n\nSeveral other tools can visualise a Swift package, however, I wanted a tool that can take both a Swift package and an Xcode project as input.\n\nThe example in the top of this README shows a visualization of a Swift package and the graph below shows a visualisation of an Xcode project.\nNotice that the left-most subgraph represents an Xcode project named ScriptUIEditor.xcodeproj and it has three targets: ScriptUIEditor, ScriptBrowserFeature, and ScriptBrowserFeatureUITests. Two of these depends on the Swift packages represented by the remaining subgraphs.\n\nThese graphs provide a good way to get an overview of a package or the relationship between several packages. Sometimes it can be helpful to generate multiple graphs to get a good overview, for example, a graph of the entire project and graphs of selected packages. Fortunately, the `dependency-graph` CLI makes this easy as it can take either an Xcode project and a Package.swift file as input.\n\n## 🧐 ...but how?\n\ndependency-graph parses Xcode project using [XcodeProj](https://github.com/tuist/XcodeProj) and interprets Package.swift files using the output from the `swift package dump-package` command. \n\nThis means that dependency-graph does not perform any package resolution or build the project, making it very fast to run the `dependency-graph` command but also produces a less detailed output that tools that rely on package resolution.\n\nThe tool has a focus on visualising local dependencies, that is, Swift packages stored locally in a project. dependency-graph will include remote dependencies in the visualisation but it will not clone those dependencies to determine their dependency graph. It is technically possible to include this but it has not been necessary for my use cases.\n","funding_links":["https://github.com/sponsors/simonbs"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonbs%2Fdependency-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonbs%2Fdependency-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonbs%2Fdependency-graph/lists"}