Swiftpack.co - Package - SDGGiesbrecht/Workspace


macOS • Linux


Workspace automates management of Swift projects.

Πᾶν ὅ τι ἐὰν ποιῆτε, ἐκ ψυχῆς ἐργάζεσθε, ὡς τῷ Κυρίῳ καὶ οὐκ ἀνθρώποις.
Whatever you do, work from the heart, as working for the Lord and not for men.



(For a list of related projects, see here.)


Paste the following into a terminal to install or update Workspace:

curl -sL https://gist.github.com/SDGGiesbrecht/4d76ad2f2b9c7bf9072ca1da9815d7e2/raw/update.sh | bash -s Workspace "https://github.com/SDGGiesbrecht/Workspace" 0.4.2 "workspace help" workspace arbeitsbereich

The Workspace Workflow

The Workspace project is managed by... Workspace! So let’s try it out by following along using the Workspace project itself.

When the Repository Is Cloned

Workspace hides as much as it can from Git, so when a project using Workspace is pulled, pushed, or cloned...

git clone https://github.com/SDGGiesbrecht/Workspace

...only one small piece of Workspace comes with it: A short script called “Refresh” that comes in two variants, one for each operating system.

Hmm... I wish I had more tools at my disposal... Hey! What if I...

Refresh the Workspace

To refresh the workspace, double‐click the Refresh script for the corresponding operating system. (If you are on Linux and double‐clicking fails or opens a text file, see here.)

Refresh opens a terminal window, and in it Workspace reports its actions while it sets the project folder up for development.

This looks better. Let’s get coding!

[Add this... Remove that... Change something over here...]

...All done. I wonder if I broke anything while I was working? Hey! It looks like I can...

Validate Changes

When the project seems ready for a push, merge, or pull request, validate the current state of the project by double‐clicking the Validate script.

Validate opens a terminal window and in it Workspace runs the project through a series of checks.

When it finishes, it prints a summary of which tests passed and which tests failed.

Oops! I never realized that would happen...


  1. Refresh before working.
  2. Validate when it looks complete.

Wow! That was so much easier than doing it all manually!


The following commands require a full install. (See Installation.)

Existing Projects

To have Workspace take responsibility for an existing project, run this command in the root of its repository:

workspace refresh

When it is added to an existing project, Workspace will refrain from most responsibilities by default, behaving in a primarily opt‐in manner. This setting can be changed.

New Projects

To have Workspace create a new Swift project from scratch, run one of the following commands in an empty folder:

To create a library project:

workspace initialize

To create an application project:

workspace initialize •type application

To create an executable project:

workspace initialize •type executable

When it creates a new project, Workspace will handle many responsibilities by default, behaving in a primarily opt‐out manner. This setting can be changed.


The Workspace project is maintained by Jeremy David Giesbrecht.

If Workspace saves you money, consider giving some of it as a donation.

If Workspace saves you time, consider devoting some of it to contributing back to the project.

Ἄξιος γὰρ ὁ ἐργάτης τοῦ μισθοῦ αὐτοῦ ἐστι.
For the worker is worthy of his wages.



Stars: 13
Help us keep the lights on



0.4.2 - Dec 8, 2017

Bug Fixes

  • JSON parsing errors no longer occur when a query to the Swift Package Manager indirectly triggers dependency resolution.

0.4.1 - Dec 6, 2017

Bug Fixes

  • Documentation is no longer needlessly repeated in unrelated jobs.
  • Test coverage validation reliably selects the correct target.
  • Versioned workaround markers are evaluated properly.

0.4.0 - Dec 5, 2017

Breaking Changes

  • Read‐me templates
    • Related configuration options now must be localized.
    • The dynamic element Next Major Version has been dropped. (Swift 4’s manifest API using from, etc. is preferred.)

New Features

  • The “Example Usage” section of the read‐me can now be customized.

    • Any example can now be used from anywhere in the read‐me.
  • More tasks are available in isolation as individual subcommands:

    • $ workspace refresh read‐me

0.3.0 - Nov 23, 2017

Breaking Changes

  • Generation of API documentation is now active by default.

    • Workspace now documents each library product defined in the package manifest.
    • Documentation is now shared between operating systems.
    • Due to the above, the resulting URLs have changed.
      • Projects upgrading from older versions of Workspace should note that the old directories (docs/macOS, docs/Linux, etc.) will not be erased. That means that, though links will fall out of date, the they will not go completely dead until the directories are manually deleted. When doing so, it is recommended to replace at least the index pages with redirects for a while before entirely removing the directories.
  • Workspace now reads Package.swift and .xcodeproj files instead of guessing a project’s structure, making several configuration overrides obsolete. The following have been removed: Project Name, Package Name, Module Name, Xcode Scheme Name, Primary Xcode Target, Xcode Test Target

New Features

  • More tasks are available in isolation as individual subcommands:

    • $ workspace refresh continuous‐integration
    • $ workspace document
    • $ workspace validate documentation‐coverage
  • Individual continuous integration jobs can be directly followed locally:

    • $ workspace validate •job miscellaneous

Bug Fixes

  • Sped up continuous integration by improving cache efficiency.

0.2.0 - Nov 11, 2017

Breaking Changes

  • The names of scripts have been shortened:

    • Refresh WorkspaceRefresh
    • Validate ChangesValidate
  • Workspace is now installed differently (see the read‐me) and has a full command line interface. User scripts which reference executables from the deprecated ~/.Workspace directory will no longer work.

  • Workspace no longer updates automatically. Instead, each project’s Refresh and Validate scripts use a consistent, stable version of Workspace. This enables the results of Validate to be more consistent as time passes. (Validate will still notify when a project is using an outdated version, but it will not prevent validation from passing.)