{"id":13837296,"url":"https://github.com/mactat/framed","last_synced_at":"2025-07-10T18:32:52.814Z","repository":{"id":170948220,"uuid":"644531584","full_name":"mactat/framed","owner":"mactat","description":"Architect your project with Framed: effortless files and directories management","archived":false,"fork":false,"pushed_at":"2024-01-04T11:26:17.000Z","size":1025,"stargazers_count":172,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-05T15:05:41.154Z","etag":null,"topics":["ci","cicd","cli","config","devops","go","golang","project-management","strctures"],"latest_commit_sha":null,"homepage":"https://blog.mactat.dev/posts/framed/","language":"Go","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/mactat.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":["mactat"]}},"created_at":"2023-05-23T18:02:10.000Z","updated_at":"2024-08-05T13:34:50.000Z","dependencies_parsed_at":"2023-12-30T09:20:20.105Z","dependency_job_id":"bfb87d71-c068-42df-947e-91f37d6b8792","html_url":"https://github.com/mactat/framed","commit_stats":null,"previous_names":["mactat/framed"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mactat%2Fframed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mactat%2Fframed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mactat%2Fframed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mactat%2Fframed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mactat","download_url":"https://codeload.github.com/mactat/framed/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225653860,"owners_count":17502939,"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":["ci","cicd","cli","config","devops","go","golang","project-management","strctures"],"created_at":"2024-08-04T15:01:05.616Z","updated_at":"2024-11-21T00:30:29.569Z","avatar_url":"https://github.com/mactat.png","language":"Go","readme":"\u003cimg src=\"./docs/static/logo-wide.png\" style=\"object-fit: cover; width: 100%;\"\u003e\n\n[![onTag](https://github.com/mactat/framed/actions/workflows/release.yaml/badge.svg)](https://github.com/mactat/framed/actions/workflows/release.yaml) [![pr](https://github.com/mactat/framed/actions/workflows/pr.yaml/badge.svg?branch=master)](https://github.com/mactat/framed/actions/workflows/pr.yaml) ![GitHub release (latest by date)](https://img.shields.io/github/v/release/mactat/framed) ![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/mactat/framed) ![Docker Pulls](https://img.shields.io/docker/pulls/mactat/framed) ![Docker Image Version (latest by date)](https://img.shields.io/docker/v/mactat/framed?label=docker-version)  ![GitHub](https://img.shields.io/github/license/mactat/framed) ![GitHub Repo stars](https://img.shields.io/github/stars/mactat/framed?style=social)\n\n# Framed - Files and Directories Reusability, Architecture, and Management\n\nFramed is a CLI tool that simplifies the organization and management of files and directories in a reusable and architectural manner. It provides YAML templates for defining project structures and enables workflows based on those.\n\nTo always be in sync with the YAML template, Framed provides a built-in test command that can be used in CI/CD pipelines to verify the project structure.\n\n## Demo\n\n![Demo](./docs/static/demo.gif)\n\n## Features\n\n- **YAML Templates**: Framed uses YAML templates to define the entire project structure.\n\n- **Always in Sync**: Framed provides a built-in test command that can be used in CI/CD pipelines to verify the project structure and ensure that it is always in sync with the YAML template.\n\n- **Consistency Across Projects**: Framed offers a consistent way of organizing files and directories across different projects.\n\n## Example configuration\n\nTo get started with Framed, you can use the following example:\n\n```yaml\n# Framed Configuration\nname: framed\n\nstructure:\n  name: root\n  maxDepth: 5 # Disallow dirs deeper than 5\n  files:\n    - README.md\n    - framed.yaml\n    - main.go\n    - go.mod\n    - go.sum\n    - .gitignore\n  dirs:\n    - name: cmd\n      allowedPatterns:\n        - \".go\"\n      forbiddenPatterns:\n        - \"_test.go\" # Disallow tests in /src\n    - name: pipelines\n      maxCount: 2\n      allowedPatterns:\n        - \".yml\"\n        - \".yaml\" # only yaml files allowed\n      files:\n        - pr.yaml\n    - name: dockerfiles\n      minCount: 1 # At least one file has to be there\n      allowChildren: false # Allow subdirectories creation, default true\n      allowedPatterns:\n        - \".dockerfile\"\n    - name: docs\n      maxCount: 10 # No more than 10 files per dir\n      allowedPatterns:\n        - \".md\"\n        - \".txt\"\n      dirs:\n        - name: design\n    - name: examples\n```\n\n### Project Structure Definition\n\nFramed allows you to define the desired structure of your project using a YAML-based configuration file. The configuration specifies the required files and directories that should exist in the project.\n\n### Root-level Requirements\n\nThe structure section defines the files that are required at the root level of the project. These files must be present for the project to be considered valid.\n\n### Nested Structure\n\nThe dirs section allows you to define nested directories within the project structure. Each subdirectory can have its own set of required files and directories.\n\n### File Requirements\n\nYou can specify file requirements using the files property. It ensures that specific files are present within the designated directory.\n\n### File Patterns\n\nThe allowedPatterns property enables you to define file patterns using glob syntax. This allows for more flexible matching of files based on their extensions or naming conventions.\n\n### Forbidden Files\n\nThe forbiddenPatterns property lets you specify file patterns that are not allowed within a directory. This can be useful for enforcing certain naming conventions or excluding specific types of files.\n\n### Minimum File Count\n\nThe minCount property allows you to set a minimum count for files within a directory. It ensures that a certain number of files must be present in the directory.\n\n### Maximum File Count\n\nThe maxCount property allows you to set a maximum count for files within a directory. It limits the number of files that can exist within the directory.\n\n### Allowing Children\n\nThe allowChildren property, when set to true, permits the presence of additional directories within a specified directory. This provides flexibility for organizing files and directories within the project.\n\n## Installation\n\n### Brew Installation\n\n1. Open a terminal and run the following command:\n\n   ```shell\n   brew tap mactat/mactat\n   brew install framed\n   ```\n\n### Darwin (macOS) Installation\n\n1. Download the `framed-darwin-amd64-\u003cversion\u003e.tar.gz` package from release page.\n\n2. Extract the package by double-clicking on the downloaded file or using a tool like `tar` in your terminal:\n\n   ```shell\n   tar -xzf framed-darwin-amd64-\u003cversion\u003e.tar.gz\n   ```\n\n3. This will extract the `framed` binary.\n\n4. Open a terminal and navigate to the extracted directory:\n\n   ```shell\n   cd framed-darwin-amd64-\u003cversion\u003e\n   ```\n\n5. Make the binary executable by running the following command:\n\n   ```shell\n   chmod +x framed\n   ```\n\n6. Move the `framed` binary to a directory in your system's `PATH` so that it can be accessed from anywhere. For example:\n\n   ```shell\n   sudo mv framed /usr/local/bin/\n   ```\n\n7. You can now use the `framed` command to execute the application.\n\n### Linux Installation\n\n1. Download the `framed-linux-amd64-\u003cversion\u003e.tar.gz` package from release page.\n\n2. Extract the package using the following command in your terminal:\n\n   ```shell\n   tar -xzf framed-linux-amd64-\u003cversion\u003e.tar.gz\n   ```\n\n3. This will extract the `framed` binary.\n\n4. Open a terminal and navigate to the extracted directory:\n\n   ```shell\n   cd framed-linux-amd64-\u003cversion\u003e\n   ```\n\n5. Make the binary executable by running the following command:\n\n   ```shell\n   chmod +x framed\n   ```\n\n6. Move the `framed` binary to a directory in your system's `PATH` so that it can be accessed from anywhere. For example:\n\n   ```shell\n   sudo mv framed /usr/local/bin/\n   ```\n\n7. You can now use the `framed` command to execute the application.\n\n### Windows Installation\n\n1. Download the `framed-windows-amd64-\u003cversion\u003e.tar.gz` package from release page.\n\n2. Extract the package using a file extraction tool like 7-Zip or WinRAR.\n\n3. This will extract the `framed.exe` binary.\n\n4. Move the `framed.exe` binary to a directory that is included in your system's `PATH`, such as `C:\\Windows` or `C:\\Windows\\System32`.\n\n5. You can now use the `framed` command to execute the application from the Command Prompt or PowerShell.\n\n**Please note that the exact steps may vary depending on your system configuration.**\n\n## Usage\n\n**Note**: The following commands assume that you have already installed Framed and added it to your system's PATH environment variable.\n\n**Note**: By default template file is `framed.yaml`. You can specify a different template file using the `--template` flag f.e `--template path/to/my-template.yaml`.\n\n### 1. Creating a Project Structure\n\nTo create a new project structure using a YAML template, run the following command:\n\n```bash\nframed create\n```\n\nIf you also want to create required files, run the following command:\n\n```bash\nframed create --files\n```\n\n### 2. Capturing current project structure\n\nTo capture the current project structure as a YAML template, run the following command:\n\n```bash\nframed capture --output \u003ctemplate-file\u003e\n```\n\n### 3. Test Project Structure (CI/CD)\n\nTo test the project structure for consistency and compliance with the YAML template, run the following command:\n\n```bash\nframed verify\n```\n\nFor a complete list of available commands and usage examples, refer to the [documentation](link-to-full-docs).\n\n### 4. Visualize Project Structure\n\nTo visualize the project structure, run the following command:\n\n```bash\nframed visualize\n```\n\n### 5. Importing Project Structure\n\nTo import the project structure from url, run the following command:\n\n```bash\nframed import --url \u003curl\u003e\n```\n\nurl has to be pointing to a yaml file with valid structure.\n\nTo import an example project structure, run the following command:\n\n```bash\nframed import --example \u003cexample-name\u003e\n```\n\nCurrently available examples:\n\n- python\n- golang\n\nSee [examples](./examples) for more details.\n\n## Running from docker\n\nTo run framed from docker, run the following command:\n\n```bash\ndocker run --rm -v $(pwd):/app --user $(id -u):$(id -g) mactat/framed framed \u003ccommand\u003e\n```\n\nexample:\n\n```bash\ndocker run --rm -v $(pwd):/app --user $(id -u):$(id -g) mactat/framed framed import --example python\n```\n\nImages can be found on [dockerhub](https://hub.docker.com/r/mactat/framed).\n\n\n## Github Action\n\nYou can use framed as a github action to verify your project structure. Minimal example:\n\n  ```yaml\n  name: Verify Project Structure\n  on: [push, pull_request]\n  jobs:\n    verify:\n      runs-on: ubuntu-latest\n      steps:\n        - uses: actions/checkout@v2\n        - name: Verify Project Structure\n          uses: mactat/framed@0.0.7\n          with:\n            template: './framed.yaml' # Optional, default is framed.yaml\n            version: 'v0.0.8'         # Optional, default is v0.0.8\n  ```\n\n## TODO\n\n- [ ] Add support from importing part of the structure from url or file like:\n\n  ```yaml\n  name: framed\n\n  structure:\n    name: root\n    dirs:\n      - name: other\n        template: other.yaml # Use another template for this dir\n      - name: another\n        template: https://yourfile.com/framed.yaml # Share templates between projects\n  ```\n\n- [x] Add some tests\n- [ ] Add contributing guidelines\n- [ ] Add more examples\n- [x] Create a github action for running tests\n- [ ] Move remaining business logic to a separate package\n","funding_links":["https://github.com/sponsors/mactat"],"categories":["Go","\u003ca name=\"file-dir-cleanup\"\u003e\u003c/a\u003eClean up of files and directories"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmactat%2Fframed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmactat%2Fframed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmactat%2Fframed/lists"}