{"id":14063544,"url":"https://github.com/aldrichtr/stitch","last_synced_at":"2025-07-29T15:33:59.490Z","repository":{"id":171433027,"uuid":"647801306","full_name":"aldrichtr/stitch","owner":"aldrichtr","description":"PowerShell developer tools","archived":false,"fork":false,"pushed_at":"2024-05-07T02:09:33.000Z","size":683,"stargazers_count":1,"open_issues_count":54,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-12T04:34:23.988Z","etag":null,"topics":["developer-tools","invoke-build","powershell","task"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","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/aldrichtr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-31T14:47:21.000Z","updated_at":"2024-08-13T07:04:57.428Z","dependencies_parsed_at":"2023-09-28T21:41:45.420Z","dependency_job_id":"908c7055-ea2e-4f88-bc6b-e5e9c75b191e","html_url":"https://github.com/aldrichtr/stitch","commit_stats":null,"previous_names":["aldrichtr/stitch"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldrichtr%2Fstitch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldrichtr%2Fstitch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldrichtr%2Fstitch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aldrichtr%2Fstitch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aldrichtr","download_url":"https://codeload.github.com/aldrichtr/stitch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228028476,"owners_count":17858340,"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":["developer-tools","invoke-build","powershell","task"],"created_at":"2024-08-13T07:03:23.440Z","updated_at":"2024-12-04T01:30:58.629Z","avatar_url":"https://github.com/aldrichtr.png","language":"PowerShell","funding_links":[],"categories":["PowerShell"],"sub_categories":[],"readme":"---\nurl: https://github.com/aldrichtr/stitch\nstatus: pre-release\n---\n\n# stitch project\n\nA set of PowerShell functions and Invoke-Build tasks stitched together to aid\nthe developer.\n\n[![Analyze PowerShell source code](https://github.com/aldrichtr/stitch/actions/workflows/cicd-run-pssa.yml/badge.svg)](https://github.com/aldrichtr/stitch/actions/workflows/cicd-run-pssa.yml)\n[![Run unit tests](https://github.com/aldrichtr/stitch/actions/workflows/cicd-run-unit-tests.yml/badge.svg)](https://github.com/aldrichtr/stitch/actions/workflows/cicd-run-unit-tests.yml)\n\n![space-pen](docs/images/space-pen.jpg)\n\nThere is a [story][1] about NASA pens and pencils:\n\n\u003e When NASA started sending astronauts into space, they quickly Discovered that\n\u003e ball-point pens would not work in zero Gravity. To combat this problem, NASA\n\u003e scientists spent a Decade and $12 billion developing a pen that writes in zero\n\u003e Gravity, upside-down, on almost any surface including glass and at\n\u003e temperatures ranging from below freezing to over 300 C.\n\u003e\n\u003e The Russians used a pencil.\n\n***In this analogy, `stitch` is most definitely, the space-pen*** :rocket::black_nib:\n\n\n## Synopsis\n\n🧵 stitch is a collection of functions and [Invoke-Build][2] tasks designed to\nhelp authors of PowerShell modules.\n\n## Description\n\n`stitch` is a *project management system*.  That means that in addition to\nbuilding source files into a module, `stitch` contains functions and tasks for\nmany other aspects of developing and managing a project.\n\n`stitch` takes inspiration from the java build system [maven][3] and is designed\nto help manage:\n\n- Source code\n- Builds\n- Testing\n- Documentation\n- Reporting\n- Dependencies\n- Source Code Management / Version Control\n- Releases\n- Publishing / Distribution\n\n## Installing\n\nto install stitch from the [PSGallery][4]\n\nIf using PSResourceGet\n\n```powershell\nInstall-PSResource stitch -Prerelease\n```\n\nor if not\n\n```powershell\nInstall-Module stitch -AllowPrerelease\n```\n\n## Overview\n\nstitch is both a module, and a set of Invoke-Build tasks.  If you are already\nusing a build script of your own, then you can still use functions from the\nstitch *module* without having to change your existing process.  Or, if you have\na set of tasks already, you can run those with the stitch build driver without\nneeding to use any of the ones that come with `stitch`\n\n### Build system\n\n#### Phases\n\nOn top of \"regular\" Invoke-Build tasks, `stitch` adds the concept of a *build\nphase*... these are the \"common\" (usually multi-step) tasks that we all have in\nour build scripts like:\n\n- **Build**: Create a module file (.psm1) and manifest (.psd1) from the files in\n  the source directory.\n- **Test**: Run Pester tests on the source files\n- **Package**: Create a nuget package file (.nupkg)\n- **Publish**: Post the package to a repository such as [PSGallery][4]\n\n(for a full list of phases, see the [wiki][6])\n\nEach phase is made up of one or more smaller \"atomic\" tasks, and the phases\nare chained together to follow a natural progression in the \"life cycle\" of the\nproject. For an excellent introduction to this concept see [this article][7] from\nthe maven project and the [wiki][6] of this repo for `stitch` specific details.\n\n#### Profiles\n\nAnother concept built on top of Invoke-Build tasks (and phases) is the build\n*profile*.  There are many ways to use profiles but two of the most common are:\n\n1. Maintaining two or more \"products\" in the same code-base, such as a module\n   and a website.\n1. Maintaining two or more \"environments\" in the same code-base, such as \"dev\",\n   \"qa\", \"prod\", etc.\n\nEach profile can make use of the same tasks (or not), and the same parameters\n(or not); it is a flexible way to define multiple \"builds\" of a single project.\n\n(for a detailed explanation of build profiles, including examples, see the [wiki][6])\n\n### Module functions\n\n#### Working with source code\n\nThere are several functions that turn files in the project's source directory\ninto objects on the pipeline:\n\n![sourceinfo](docs/images/get-sourceitem-screenshot.png)\n\nEach item has a rich set of properties for use in your scripts and tasks:\n\n![members](docs/images/sourceitem-members-screenshot.png)\n\nSome examples of things you can do with this information:\n\n1. Build a list of functions to be exported:\n   ![exported functions](docs/images/get-exported-functions.png)\n1. Generate a list of components in your module\n   ![components](docs/images/get-components.png)\n1. Create Pester test files from your source file\n\n   ```powershell\n   get-sourceitem | ? Name -like Get-SourceItem | New-TestItem\n   ```\n\n   ***Disclamer***: `stitch` has a few templates that are based on the [EPS][5]\n   module... they work *ok* for simple things, but I'm looking for a suitable\n   replacement.\n\nAs you can see, there are a lot of useful things you can do with the\n`sourceiteminfo` object.\n\nHead over to the [wiki][6] to see more.\n\n### Invoke-Build tasks\n\n\n#### task locations\n\n`stitch` will look in multiple other locations for the tasks definitions:\n\n- The given build profile directory\n- The user's `~/.stitch` directory\n- The stitch module`s installed directory\n\nEach layer \"overlays\" the one below it, so that if a task in the build profile\ndirectory has the same name as a task in the module's directory, it will be run\ninstead of the module's.\n\nAdditionally, tasks can be included or excluded by name at run-time using the\nconfiguration file or the command line parameters.\n\n#### task runbook\n\n`stitch` phases and tasks are defined in a \"special\" build script called the\n*runbook*.\n\nTo make it easier to create and modify phases and tasks, `stitch` adds\nadditional aliases to your build that let you control tasks in an easy-to-read\nway, creating a build [DSL][8]\n\ncurrently, there are three of these DSL words:\n\n- **jobs**: A flexible way to add subtasks (jobs) to any phase or task\n\n  ```powershell\n  'Build' | jobs 'write.module', 'write.manifest'\n  ```\n\n- **before**: Set a task to run before another\n\n  ```powershell\n  'Clean' | before 'Build'\n  ```\n\n- **after**: Set a task to run after another\n\n  ```powershell\n  'add.footer' | after 'new.document'\n  ```\n\n[1]: https://www.snopes.com/fact-check/the-write-stuff/\n[2]: https://github.com/nightroman/Invoke-Build\n[3]: https://maven.apache.org/guides/getting-started/index.html#what-is-maven\n[4]: https://www.powershellgallery.com/\n[5]: https://github.com/straightdave/EPS\n[6]: https://github.com/aldrichtr/stitch/wiki\n[7]: https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html\n[8]: https://en.wikipedia.org/wiki/Domain-specific_language\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faldrichtr%2Fstitch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faldrichtr%2Fstitch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faldrichtr%2Fstitch/lists"}