{"id":14069364,"url":"https://github.com/yunielrc/ydf","last_synced_at":"2025-04-12T05:50:53.842Z","repository":{"id":194826430,"uuid":"691614316","full_name":"yunielrc/ydf","owner":"yunielrc","description":"A dotfiles manager+. Be ready to work in just a few minutes on your Fresh OS","archived":false,"fork":false,"pushed_at":"2025-01-24T18:39:23.000Z","size":753,"stargazers_count":26,"open_issues_count":11,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T01:12:54.674Z","etag":null,"topics":["ansible","automation","bashdot","chezmoi","configuration-as-code","configuration-automation","configuration-management","configuration-manager","development-environment","dotbare","dotbot","dotfiles","dotfiles-manager","puppet","stow","yadm"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yunielrc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-14T14:31:59.000Z","updated_at":"2025-03-23T01:47:31.000Z","dependencies_parsed_at":"2024-01-10T16:11:06.277Z","dependency_job_id":"584de4c2-c3af-46ef-8612-5b957adb4aec","html_url":"https://github.com/yunielrc/ydf","commit_stats":null,"previous_names":["yunielrc/ydf"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunielrc%2Fydf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunielrc%2Fydf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunielrc%2Fydf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yunielrc%2Fydf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yunielrc","download_url":"https://codeload.github.com/yunielrc/ydf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525153,"owners_count":21118616,"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":["ansible","automation","bashdot","chezmoi","configuration-as-code","configuration-automation","configuration-management","configuration-manager","development-environment","dotbare","dotbot","dotfiles","dotfiles-manager","puppet","stow","yadm"],"created_at":"2024-08-13T07:06:53.834Z","updated_at":"2025-04-12T05:50:53.810Z","avatar_url":"https://github.com/yunielrc.png","language":"Shell","funding_links":[],"categories":["Shell","\u003ca name=\"system\"\u003e\u003c/a\u003eSystem tools"],"sub_categories":[],"readme":"\u003c!-- DO NOT EDIT THIS FILE; IT WAS GENERATED BY ./tools/update-readme --\u003e\n\u003c!-- EDIT README.md.tpl INSTEAD --\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"\" rel=\"noopener\"\u003e\n    \u003cimg src=\"media/ydf.png\" width=\"96px\" alt=\"ydf\" /\u003e\n\n# ydf\n\n  \u003c/a\u003e\n\n**_A dotfiles manager+_**\n\n**_Be ready to work in just a few minutes on your Fresh OS_**\n\n**_Declare your working environment and Automate its configuration_**\n\n**_New member on the team?, reproduce your colleague working environment and start working now_**\n\n\u003c/div\u003e\n\n\u003ca href=\"https://www.producthunt.com/posts/ydf?utm_source=badge-featured\u0026utm_medium=badge\u0026utm_souce=badge-ydf\" target=\"_blank\"\u003e\u003cimg src=\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=416013\u0026theme=light\" alt=\"ydf - A\u0026#0032;disruptive\u0026#0032;dotfiles\u0026#0032;manager\u0026#0043; | Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /\u003e\u003c/a\u003e\n\n\u003ca href=\"https://github.com/yunielrc/.ydf-packages\" target=\"_blank\"\u003e\u003cimg width=95%  src=\"media/ydf-packages.png\" alt=\"ydf-packages\"\u003e\u003c/a\u003e\n\n👉 [**_A working environment declared in a simple directory structure_**](https://github.com/yunielrc/.ydf-packages)\n\n## Table of Contents\n\nClick on the menu right before `README.md` as shown in the image below.\n\n\u003cimg width=300px src=\"media/toc.png\" alt=\"toc\"/\u003e\n\n## About\n\nAre you tired of dealing with dotfiles of tools you are not using, are you tired\nof installing a bunch of messy and dirty configs and executing an\nelephant script.\n\nThis solution brings you a simple way to declare and install idempotently the tools\nyou need along with its configurations, following the principles of high cohesion\nand low coupling. Turn the chaos to order, if you install the configuration, you\ninstall the tool because those belong to the same `package`.\n\nWith this solution you can create multiple selections of packages for your different\nneeds, for example, you can create a `packages selection` for your laptop, desktop,\nservers, different operating systems, etc.\n\nDeclaring your working environment give you some benefits: transparency and control\nover it, allowing you to easily reproduce it on a new machine or fresh OS, you can\nshare it with others, so they can reproduce your working environment, you can version it with git.\n\n\u003e What you write you can read, share, save and reproduce, it is simply there, it exists.\n\n## Tested OS\n\nIt has been tested on the following linux distributions, click to show the dependencies:\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eManjaro\u003c/b\u003e\u003c/summary\u003e\n\nRuntime Dependencies:\n\n```sh\n# SYSTEM: Linux manjaro-gnome 6.5.3-1-MANJARO #1 SMP PREEMPT_DYNAMIC Wed Sep 13 12:21:35 UTC 2023 x86_64 GNU/Linux\n# PACMAN\nbash 5.1.016-3\n```\n\nOptional Dependencies:\n\n```sh\n# SYSTEM: Linux manjaro-gnome 6.5.3-1-MANJARO #1 SMP PREEMPT_DYNAMIC Wed Sep 13 12:21:35 UTC 2023 x86_64 GNU/Linux\n# PACMAN\nyay 12.1.3-1\nsnapd 2.60.3-1\ndocker 1:24.0.5-1\ndocker-compose 2.20.3-1\n# GITHUB\nyunielrc/yzsh\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eUbuntu\u003c/b\u003e\u003c/summary\u003e\n\nRuntime Dependencies:\n\n```sh\n# SYSTEM: Linux ubuntu-gnome 6.2.0-26-generic #26~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Thu Jul 13 16:27:29 UTC 2 x86_64 x86_64 x86_64 GNU/Linux\n# APT\nbash 5.1-6ubuntu1\n```\n\nOptional Dependencies:\n\n```sh\n# SYSTEM: Linux ubuntu-gnome 6.2.0-26-generic #26~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Thu Jul 13 16:27:29 UTC 2 x86_64 x86_64 x86_64 GNU/Linux\n# APT\ncontainerd.io 1.6.24-1\ndocker-buildx-plugin 0.11.2-1~ubuntu.22.04~jammy\ndocker-ce-cli 5:24.0.6-1~ubuntu.22.04~jammy\ndocker-ce 5:24.0.6-1~ubuntu.22.04~jammy\ndocker-compose-plugin 2.21.0-1~ubuntu.22.04~jammy\nflatpak 1.14.4-1~flatpak1~22.04.1\n# GITHUB\nyunielrc/yzsh\n```\n\n\u003c/details\u003e\n\nIt should work on any other linux distribution, but it has not been tested.\n\n## Install\n\nInstall `git`, `make` and `vim`\n\nClone the repository and switch to ydf directory\n\n```sh\ngit clone https://github.com/yunielrc/ydf.git \u0026\u0026 cd ydf\n```\n\nSelect the latest stable version\n\n```sh\ngit checkout \"$(git tag --sort='version:refname' | grep -Po '^v\\d+\\.\\d+\\.\\d+$' | tail -n 1)\"\n```\n\n### Install on Manjaro\n\nInstall optional dependencies and ydf on home directory\n\n```sh\nmake install-opt-manjaro \u0026\u0026 make install-tohome\n```\n\n### Install on Ubuntu\n\nInstall optional dependencies and ydf on home directory\n\n```sh\nmake install-opt-ubuntu \u0026\u0026 make install-tohome\n```\n\n### Install on Any Linux Distro (Minimal installation)\n\nMinimal installation without optional dependencies\n\n```sh\nmake install-tohome\n```\n\n⚠️ Attention: Instructions that rely on optional dependencies can't be used\n   with the minimal installation. For each instruction you want to use install\n   its dependency.\n\nInstruction | Optional dependency\n---------|----------\n `@snap` | snapd\n `@flatpak` | flatpak\n `docker-compose.yml` | docker, docker-compose\n `@yay` | yay\n `*.plugin.zsh` | yzsh\n `*.theme.zsh` | yzsh\n\n## Configure\n\nEdit the config file:\n\n- Set the variable `YDF_PACKAGE_SERVICE_DEFAULT_OS` to `manjaro` or `ubuntu`\n  according to your distro. If you have any other distro don't set this variable.\n\n```sh\nvim ~/.ydf.env\n```\n\n## YDF Package\n\n### What is a package?\n\nA `package` is a directory containing files and directories in which some have\na special meaning for the `interpreter`. ydf is an `interpreter`.\n\n### What are the directories and files with special meaning?\n\nHere is an example of a `package` with 19 directories and files with special\nmeaning, those are `instructions` that work on any linux distribution:\n\n```sh\npackage1\n├── preinstall           # Script executed before all instructions\n├── @flatpak             # Install \u003cpackage1\u003e with flatpak\n├── @snap                # Install \u003cpackage1\u003e with snap\n├── install              # Script executed on install\n├── docker-compose.yml   # Run docker compose up -d\n├── package1.plugin.zsh  # Install yzsh plugin\n├── package1.theme.zsh   # Install yzsh theme\n├── homeln/              # Create symlinks on home for the first level files and\n|                        # directories inside this directory\n├── homelnr/             # Create symlinks on home for all files inside this\n|                        # directory\n├── homecp/              # Copy all files to home directory\n├── rootcp/              # Copy all files to root directory\n├── homecat/             # Concatenate all files with those existing in home\n├── rootcat/             # Concatenate all files with those existing in root\n├── homecps/             # Evaluate variables in files and copy them to home\n├── rootcps/             # Evaluate variables in files and copy them to root\n├── homecats/            # Evaluate variables in files and concatenates them with\n|                        # those existing in home\n├── rootcats/            # Evaluate variables in files and concatenates them with\n|                        # those existing in root\n├── dconf.ini            # Load gnome dconf settings\n└── postinstall          # Script executed after all instructions\n```\n\nThe `instructions` can be grouped in 4 categories:\n\n- Scripts instructions: `preinstall`, `install`, `postinstall`.\nThese instructions are shell scripts that are executed by bash.\n\n- Package manager instructions: `@flatpak`, `@snap`.\nThese instrucions are plain text files, the file can have inside one or more package\nnames that are going to be installed. The file can be empty, in this case the package\n`package1` is going to be installed.\n\n- Directory instructions: `homeln`, `homelnr`, `homecp`, `rootcp`, `homecat`,\n`rootcat`, `homecps`, `rootcps`, `homecats`, `rootcats`.\nThese instructions are directories that contains files that are going to be\nsymlinked, copied or concatenated to the home or root directory. For those\nthat end with `s` all the variables inside each file are substituted with the\nvalues defined in the `envsubst.env` file that is inside the `packages directory`.\n\n- Tool files instructions: `docker-compose.yml`, `dconf.ini`, `package1.plugin.zsh`,\n`package1.theme.zsh`.\nThese instructions are files that are going to be used by a tool. For example\n`docker-compose.yml` is going to be used by docker compose.\nThe `package1.plugin.zsh` is a plugin that is going to be installed inside the\nYZSH data directory and used by YZSH.\n\nThese `instructions` only work for archlinux, manjaro linux an others arch distros:\n\n```sh\npackage2\n├── @pacman\n└── @yay\n```\n\nThese `instructions` only work for debian, ubuntu and others debian distros:\n\n```sh\npackage3\n├── @apt\n└── @apt-get\n```\n\n👉 If you want support for others package managers you can open an issue or\ncreate a pull request.\n\nYou can check out some examples of `packages` at: `tests/fixtures/packages`\n\n### What is a YDF Packages Directory\n\nThe `packages directory` is the declaration of your working environment. It's a\ndirectory that contains a list of `packages` and the `envsubst.env` file, besides\nit can have one or more `packages selection` files.\n\nBelow is shown the recommended approach of a `packages directory`:\n\n```sh\n~/.ydf-packages       # packages directory\n├── bat/              # package\n├── bmon/             # package\n├── htop/             # package\n├── aws-cli-v2/       # package\n├── mpv/              # package\n├── ....              # package\n├── envsubst.env      # substitution variables\n├── pc-gaming.pkgs    # packages selection\n├── laptop-work.pkgs  # packages selection\n└── ....              # packages selection\n```\n\nThe `envsubst.env` file has the variables that are evaluated in the files inside\nof `Directory instructions` that end with `s`.\n\nThe `packages selection` are plain text files that contains a list of `packages`\none per line.\n\nThe `packages directory` is where the `interpreter` is going to look for\n`packages`, `substitution variables` and `packages selection`.\n\n👉 You can check out my `packages directory` at: \u003chttps://github.com/yunielrc/.ydf-packages\u003e\n\nBelow is shown the approach of only one big `package` with all dotfiles inside,\nthis is the classic approach used by the most well-known dotfiles managers:\n\n```sh\n~/.ydf-packages/all/homelnr\n├── .vedv.env\n├── .viminfo\n├── .vultr-cli.yaml\n├── .xinitrc\n├── .ydf.env\n├── .yzsh\n│   ├── aliases.zsh\n│   ├── environment.zsh\n│   └── .yzsh.env\n├── .zsh_plugins.zsh\n├── .zshrc\n└── ....\n```\n\nThe advantages of this approach are:\n\n1. simplicity\n2. ease of creation\n\nThe disadvantages of this approach are:\n\n1. you can't make a custom pick of packages to install\n2. loss of the relationship between tool installation and configuration\n3. it breaks the principle of high cohesion and low coupling\n4. no suitable for sharing, because #1\n5. no `packages selection`\n6. no `substitution variables`\n7. no instructions other than `homelnr`\n\n## Usage\n\nReload your shell to load the new PATH.\n\n```sh\nexec $SHELL\n```\n\nShow the help\n\n```sh\nydf --help\n```\n\n```sh\n# command output:\nUsage:\nydf COMMAND\n\nA tool for managing ydotfiles\n\nFlags:\n  -h, --help    Show this help\n\nManagement Commands:\n  package   Manage packages\n\nRun 'ydf COMMAND --help' for more information on a command.\n```\n\n### Add packages to your packages directory\n\nBefore adding a `package` to your `packages directory` you must create a git\nrepository.\n\n```sh\ncd ~/.ydf-packages\ngit init\ngit remote add origin git@github.com:\u003cyour_user\u003e/.ydf-packages.git\n```\n\nOpen the `packages directory` in your favorite code editor .\n\n```sh\ncode ~/.ydf-packages\n```\n\nCreate a `package` and add `instructions` to it. You can check out my `packages directory`\nat: \u003chttps://github.com/yunielrc/.ydf-packages\u003e\n\nAdd variables to the `~/.ydf-packages/envsubst.env` if apply.\n\nTest that the `package` works.\n\n```sh\nydf package install \u003cpackage\u003e\n```\n\nVerify that the software was installed and configured correctly.\n\nCreate a `packages selection` if apply and add the package.\n\n```sh\necho \"\u003cpackage\u003e\" \u003e\u003e ~/.ydf-packages/\u003cpackages_selection\u003e.pkgs\n```\n\nCommit the changes.\n\n```sh\ncd ~/.ydf-packages\ngit add .\ngit commit -m \"Add \u003cpackage\u003e\"\ngit push -u origin master\n```\n\n### Install packages\n\nWhen you reinstall your OS or on a new machine you can:\n\nInstall packages from a `packages selection` file\n\n```sh\nydf package install \u003cpackages_selection\u003e.pkgs\n```\n\nInstall some packages\n\n```sh\nydf package install \u003cpackage1\u003e \u003cpackage2\u003e ...\n```\n\nInstall one package\n\n```sh\nydf package install \u003cpackage\u003e\n```\n\n👉 You can test the installation of the packages on a virtual machine before\n   install them on a real one.\n\nIt's recommended to check out `vedv` at \u003chttps://github.com/yunielrc/vedv\u003e\nfor working with virtual machines.\n\n## Contributing\n\nContributions, issues and feature requests are welcome!\n\n### Manjaro dev dependencies\n\n```sh\n# SYSTEM: Linux yuniel-pc 6.1.53-1-MANJARO #1 SMP PREEMPT_DYNAMIC Wed Sep 13 14:10:57 UTC 2023 x86_64 GNU/Linux\n# YAY\nvedv-git 0.2.3-1\nmake 4.4.1-2\npython-pre-commit 2.20.0-3\nshfmt 3.7.0-1\nshellcheck 0.9.0-47\nnodejs 20.6.1-1\nnpm 10.1.0-1\nbash-bats 1.10.0-2\nbash-bats-assert-git 2.1.0-1\nbash-bats-file 0.4.0-2\nbash-bats-support-git 0.3.0-1\nfd 8.7.0-1\n# NPM\n@commitlint/cli@17.7.1\n@commitlint/config-conventional@17.7.0\ncommitizen@4.3.0\ncz-conventional-changelog@3.3.0\n```\n\n### Ubuntu dev dependencies\n\n```sh\n# SYSTEM: Linux user-MS-7D43 6.2.0-33-generic #33~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Thu Sep  7 10:33:52 UTC 2 x86_64 x86_64 x86_64 GNU/Linux\n# APT\nfd-find 8.3.1-1ubuntu0.1\nmake 4.3-4.1build1\npre-commit 2.17.0-1\n# SNAP\nnode 18.18.0\nshellcheck v0.9.0\nshfmt 3.5.1\n# NPM\n@commitlint/cli@17.7.1\n@commitlint/config-conventional@17.7.0\nbats@1.10.0\ncommitizen@4.3.0\ncz-conventional-changelog@3.3.0\n# GITHUB\nbats-core/bats-support\nbats-core/bats-assert\nbats-core/bats-file\nyunielrc/vedv\n```\n\n### Configure dev environment\n\n#### Copy config samples\n\n```sh\ncp .env.sample .env\ncp .ydf.env.sample .ydf.env\n```\n\nEdit the config file .env:\n\n- Set the variable `HOST_OS` to `manjaro` or `ubuntu` according to your distro.\n  If you have any other distro don't set this variable.\n\n- Set the variable `TEST_OS` to `manjaro` or `ubuntu` according to distro that\n  It's going to be tested.\n\n```sh\nvim ~/.env\n```\n\n#### Install dependencies for Manjaro\n\nThe command below install development dependencies for Manjaro\n\n```sh\nmake install-dev-manjaro\n```\n\n#### Install dependencies for Ubuntu\n\nThe command below install development dependencies for Ubuntu\n\n```sh\nmake install-dev-ubuntu\n```\n\n#### Install dependencies for Any Linux Distro\n\nFor any other linux distribution install development dependencies\nmanually.\n\n#### Configure vedv\n\nCheck out: \u003chttps://github.com/yunielrc/vedv#configure\u003e\n\n### Workflow\n\n#### Code\n\nWrite your code\n\n#### Run Tests\n\nAll tests are run within a virtual machine, this ensures that your operating system\nwill never be modified.\n\nThe first time the image need to be downloaded and builded for development,\nthis process take a while, below are shown the download and build time for the\nsupported Linux distros at 90Mbps:\n\nDistro  | download    | build\n--------|-------------|----------\nmanjaro | 5m 9.11s    | 13m 4.74s\nubuntu  | 10m 13.611s | 8m 33.755s\n\nRun Unit Testing for one component\n\n```sh\nmake test-suite u=\"$(fd utils.bats)\"\n```\n\nRun Unit Testing for one function\n\n```sh\nmake test-name n='text_file_to_words' u=\"$(fd utils.bats)\"\n```\n\nRun Integration Testing for one function\n\n```sh\nmake test-name n='install_one_from_dir' u=\"$(fd ydf-package-service.i.bats)\"\n```\n\nRun Functional Testing for one function\n\n```sh\nmake test-name n='20homecats' u=\"$(fd ydf-package-command.f.bats)\"\n```\n\nRun All Unit Tests\n\n```sh\nmake test-unit\n# 2.331s on manjaro\n# 2.304s on ubuntu\n```\n\nRun All Integration Tests\n\n```sh\nmake test-integration\n# 53.475s on manjaro\n# 1m 11.739s on ubuntu\n```\n\nRun All Functional Tests\n\n```sh\nmake test-functional\n# 1m 52.301s on manjaro\n# 1m 31.900s on ubuntu\n```\n\nRun All tests\n\n```sh\nmake test-all\n# 1m 43.793s on manjaro\n# 2m 17.157s on ubuntu\n```\n\n#### Commit\n\nThis project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).\n\nFor commiting use the command below\n\n```sh\nmake commit\n```\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyunielrc%2Fydf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyunielrc%2Fydf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyunielrc%2Fydf/lists"}