{"id":19903678,"url":"https://github.com/regolith-linux/trawl","last_synced_at":"2025-06-20T18:10:43.661Z","repository":{"id":44367217,"uuid":"510899814","full_name":"regolith-linux/trawl","owner":"regolith-linux","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-16T17:10:38.000Z","size":141,"stargazers_count":4,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-27T03:32:59.868Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/regolith-linux.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2022-07-05T21:31:08.000Z","updated_at":"2025-03-16T17:10:42.000Z","dependencies_parsed_at":"2024-04-14T23:01:01.472Z","dependency_job_id":"fe437f31-9159-4c2e-aa35-43388721f14f","html_url":"https://github.com/regolith-linux/trawl","commit_stats":{"total_commits":81,"total_committers":2,"mean_commits":40.5,"dds":"0.12345679012345678","last_synced_commit":"62cf7cf325ab516a3fac9305b3f4a7c96b84b814"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regolith-linux%2Ftrawl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regolith-linux%2Ftrawl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regolith-linux%2Ftrawl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regolith-linux%2Ftrawl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/regolith-linux","download_url":"https://codeload.github.com/regolith-linux/trawl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252068673,"owners_count":21689525,"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":[],"created_at":"2024-11-12T20:24:52.043Z","updated_at":"2025-05-03T00:31:13.614Z","avatar_url":"https://github.com/regolith-linux.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trawl\n\nSimple **Xresources** style linux based configuration system that is independent of distro / display backend (Wayland / X11 / etc).\n\n# Build Instructions\n\nMake sure you have the rust toolchain (version \u003e= 1.62) installed. Use the following commands to build all the binaries:\n\n```bash\ngit clone https://github.com/regolith-linux/trawl.git\ncd trawl\nmake\n```\n\n**Note 1**: Replace `cargo build` with `cargo build --release` to build the binaries in release mode.\n\n**Note 2**: The binaries are located in the `target/debug` directory (`target/release` if built in release mode).\n\n**Note 3**: The `make setup` command will fail the first time you run it. This is because the code for dbus-interface is generated at this step. You can ignore this error and proceed to the following commands.\n\n# Install Instructions\n\n```bash\ngit clone https://github.com/regolith-linux/trawl.git\ncd trawl\n# enable the \"install\" target in the Makefile\nmake install\nsystemctl daemon-reload\nsystemctl enable --now trawld\n```\n**Note**: The `make setup` command will fail the first time you run it. This is because the code for dbus-interface is generated at this step. You can ignore this error and proceed to the following commands.\n\n\n# Features\n\n- **Xresources** like file based configuration system.\n- Compatible with existing `Xresources` files.\n- Display backend and distro independent.\n- **Lightweight** and **Simple** to use.\n- Uses **DBus session bus** to estabish IPC. This allows each user to run thier own instance of the config manager.\n\n# Usage\n\nPrefix the binaries with build directory path (`target/debug` or `target/release`) to use without installing.\n\n## Resource file / Config file format\n\n- Each line in the resource file is a key value pair separated by ':'. Eg.\n  ```\n  key1: value1\n  key2: value2\n  ```\n- A valid key is an ASCII alphanumeric string with no whitespace, but can include the following special characters -- **' - ', ' . ', ' \\_ '**. Eg.\n  ```\n  sway-wm.screen_timeout: 100\n  ```\n- In case a line contains multiple colons (':'), the contents before the first colon are treated as key and the contents after the first colon are treated as value. Eg.\n  ```\n  swaywm.workspace.1.name: 1: Shell\n  ```\n- Value can be any UTF-8 string.\n- Comments are prefixed with '//' and are ignored.\n- By default, preprocessor directives (begin with '#') are processed by the c preprocessor. If the directive is not recognized, it is ignored.\n- Preprocessor directives can be used to include other files. The directive is of the form `#include \u003cfile\u003e`. The file is relative to the resource file.\n  ```c\n  #include \u003cconfig.d/swayidle\u003e\n  ```\n- Preprocessor directives can be used to define macros. The directive is of the form `#define \u003cmacro\u003e \u003cvalue\u003e`. The macro is a string and the value is a string. The macro is defined in the resource file.\n  ```c\n  #define USERNAME \"John Doe\"\n  ```\n- Just like in C, parts of the resource file can be ignored / included conditionally using the `#ifdef` and `ifndef` directives.\n  ```c\n  #ifdef USERNAME\n  swaylock.greeter.user USERNAME // USERNAME is replaced with John Doe\n  #endif\n  ```\n\n## Start the config manager (trawld)\n\nRun `trawld` to start the config daemon. You can pass optional arguments to the daemon to customize the behavior or to change the logging level. Run `trawld --help` documentation for more information.\n\n## Using the CLI Cleint (_trawldb_)\n\nThe CLI client allows the user to interact with the config manager. Primary functions of the client include loading configurations from files.  Run `trawldb --help` for more information.\n\n### Examples\n\n1. Load a file\n   ```bash\n   # load a file (doesn't overwrite existing resources)\n   trawldb --load example/resources\n   # load a file without preprocessing\n   resrdb --load example/resources --nocpp\n   ```\n2. Merge resources from a file\n   ```bash\n   # merge resource from a file (overrides existing resources)\n   trawldb --merge example/resources\n   # merge resource from a file without preprocessing\n   trawldb --merge example/resources --nocpp\n   ```\n3. Save currently loaded resources into a file\n   ```bash\n   # if file exists it is backed up to a file with the same name but with a .bak extension\n   trawldb --edit all_resources\n   # specify suffix for -edit [.bak]\n   trawldb --edit all_resources --backup .old\n   ```\n4. Query Resources\n   ```bash\n   # query all resources\n   trawldb --query\n   # query a specific resource (partial matches are also shown)\n   trawldb --query key1\n   ```\n5. Get resource values\n   ```bash\n   # get the value for the resouource whose name is 'key1'\n   trawldb --get key1\n   ```\n\n## Get resource value (trawlcat)\n\n`trawlcat` is a drop-in replacement for `xrescat` and prints the value of the requested resource. For more info, see the ([xrerscat](https://github.com/regolith-linux/xrescat)) documentation.\n\n## Client API (for C)\n\nThe header and implementation files for the dbus interface are autogenerated from the `service.xml` file during the `meson` build. The `client_api.h` header file provides a simple to use wrapper api. All the dbus method names are in snake case and are prefixed with `conf_client`.\n\n## Rust Client Library\n\nInclude the `trawldb` crate in the `Cargo.toml` file. You can then use the Rust client library to interact with the config manager.\n\n```toml\n[dependencies]\ntrawldb = { path = \"/path/to/trawldb\" }\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fregolith-linux%2Ftrawl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fregolith-linux%2Ftrawl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fregolith-linux%2Ftrawl/lists"}