{"id":43447803,"url":"https://github.com/sts10/fgift","last_synced_at":"2026-02-03T01:07:44.933Z","repository":{"id":56809494,"uuid":"187397929","full_name":"sts10/fgift","owner":"sts10","description":"Generate randomly assigned gift givers from a list of groups of people","archived":false,"fork":false,"pushed_at":"2025-12-02T22:34:07.000Z","size":211,"stargazers_count":4,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-05T22:53:28.566Z","etag":null,"topics":["random","rust","secret-santa"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sts10.png","metadata":{"files":{"readme":"README.markdown","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-05-18T19:34:22.000Z","updated_at":"2025-12-02T22:33:40.000Z","dependencies_parsed_at":"2023-11-10T11:15:32.517Z","dependency_job_id":"b4f60f6d-3438-41db-87b7-52f4fb2c9464","html_url":"https://github.com/sts10/fgift","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/sts10/fgift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sts10%2Ffgift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sts10%2Ffgift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sts10%2Ffgift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sts10%2Ffgift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sts10","download_url":"https://codeload.github.com/sts10/fgift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sts10%2Ffgift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29025665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T00:53:18.321Z","status":"ssl_error","status_checked_at":"2026-02-03T00:51:45.186Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["random","rust","secret-santa"],"created_at":"2026-02-03T01:07:44.215Z","updated_at":"2026-02-03T01:07:44.924Z","avatar_url":"https://github.com/sts10.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FGift: Family Gift List Maker\n[![](https://deps.rs/repo/github/sts10/fgift/status.svg)](https://deps.rs/repo/github/sts10/fgift)\n\nThis is a command-line tool that takes an input of a CSV or JSON file, describing an (extended) family, in which each line represents an immediate family. It outputs a list of who should give to who, ensuring that no one gives to anyone in their immediate family, but otherwise selecting randomly. One common use-case for this would be where you need to create \"Secret Santa\" give assignments.\n\nObviously you can substitute the concept of \"families\" for any small groups of people, such as teams at your workplace.\n\n## Usage\n\n```text\nUsage: fgift [OPTIONS] \u003cNAMES FILE\u003e\n\nArguments:\n  \u003cNAMES FILE\u003e  File containing names and family information. Can be CSV or JSON file\n\nOptions:\n  -v, --verbose...\n          Prints verbose output, including parameters as received. Can accept either one \n          or two count\n  -p, --previous \u003cPREVIOUS_YEARS_FILE\u003e\n          Optionally provide file with previous years giving\n  -s, --special \u003cSPECIAL_REQUESTS_FILE\u003e\n          Optionally provide file with special requests (assignments that _must_ be made)\n  -o, --output \u003cOUTPUT\u003e\n          Print assignments to a file, rather than to the terminal\n  -h, --help\n          Print help\n  -V, --version\n          Print version\n```\n\n## How to create/format the NAMES file properly\n\nFGift requires a NAMES file that describes the names and groups of the people who will be on your list.\n\nFGift can accept this file in two different formats: CSV or JSON. (FGift uses **the file's extension** to determine how to parse the file, so be sure it is accurate: either `.csv` or `.json`.)\n\n### Example NAMES file as CSV\nIf you want to create your NAMES file as a CSV, each row needs to be an immediate (nuclear) family.\n\nFor example:\n\n```csv\nNames,,,,\nClaire,Phil,Haley,Alex,Luke\nCameron,Mitchell,Lily,,\nJay,Gloria,Manny,,\n```\n\n(Generally I'd recommend creating and editing the CSV file in a spreadsheet editor like Microsoft Excel or [LibreOffice](https://www.libreoffice.org/) Calc, rather than a text editor like Vim or Sublime Text.)\n\n### Example NAMES file as JSON\nFGift can also accept a JSON file describing the `names` and their relationships:\n\n```json\n{\n  \"names\": [\n    [\"Claire\", \"Phil\", \"Haley\", \"Alex\", \"Luke\"],\n    [\"Cameron\", \"Mitchell\", \"Lily\"],\n    [\"Jay\", \"Gloria\", \"Manny\"]\n  ]\n}\n```\n\nI find this format a bit easier to edit with a text editor.\n\n## What FGift does with this inputted NAMES file\nNow we're ready to run either `fgift names.csv` or `fgift names.json` back on the command line. This should give you an output like this:\n\n```\nClaire gives to Cameron\nPhil gives to Mitchell\nHaley gives to Manny\nAlex gives to Jay\nLuke gives to Gloria\nBaby gives to Lily\nJay gives to Haley\nGloria gives to Alex\nManny gives to Baby\nCameron gives to Phil\nMitchell gives to Luke\nLily gives to Claire\n```\n\nThe gift assignments here are randomized, _except_ that no one gives to anyone in their immediate family (the same row or sub-array). For example, Claire does not give to Phil, Haley, Alex, or Luke, since they are in Claire's immediate family. \n\nThis information -- that Claire is in an immediate family with Phil, Haley, Alex, and Luke -- is established (or encoded) in the inputted file, by the fact that all those names are in the same row or sub-array. \n\n## Installation \n\n### Using Cargo (Rust)\n1. [Install Rust](https://www.rust-lang.org/tools/install) if you haven't already\n2. Install FGift: `cargo install --git https://github.com/sts10/fgift --locked --branch main`\n\nYou should now be able to run `fgift` from anywhere in your terminal. Run `fgift --help` to check that this is now the case.\n\nTo **upgrade** this installation of FGift, run the same installation command again.\n\n### From a GitHub release\nAlternatively, you can download/install the latest release of FGift. See [the GitHub Releases page for further instructions](https://github.com/sts10/fgift/releases).\n\nIn general, to install the executable on a Linux/macOS machine, download the `fgift` executable and move it to somewhere in your `$PATH`, like `$HOME/.local/bin` (you can do this on the command line with something like `mv ~/Downloads/fgift ~/.local/bin/`). You may also need to give the executable permissions with something like `chmod +x ~/.local/bin/fgift`.\n\n### Uninstalling FGift and Rust\n\nIf you installed FGift using Cargo, you can uninstall FGift by running: `cargo uninstall fgift`\n\nTo uninstall Rust and `cargo` (if you install Rust solely to run FGift, for example), as of 2023, run: `rustup self uninstall` ([source](https://www.rust-lang.org/tools/install)).\n\n## Using FGift: Examples\n\nFGift is a command-line tool. It must also take a NAMES file, but there are other optional arguments it can take.\n\n- `fgift tests/test-files/test-names.csv` Creates random gift assignments from Names file `test-names.csv`, without assigning anyone to give to members of their immediate family (as denoted by rows in the `test-names.csv` file (see above for examples).\n\n- `fgift tests/test-files/test-names.json` Creates random gift assignments from Names file `test-names.json`, without assigning anyone to give to members of their immediate family (as denoted by rows in the `test-names.json` file (see above for examples).\n\n- `fgift -p=tests/test-files/previous-years-giving-list-test.txt tests/test-files/test-names.csv` Creates gift assignments without repeating any assignments found in `previous-years-giving-list-test.txt`\n\n- `fgift -p=tests/test-files/previous-years-giving-list-test.txt -o=this-years-assignments.txt tests/test-files/test-names.csv` Creates gift assignments without repeating any assignments found in `previous-years-giving-list-test.txt`. Writes created assignments to text file `this-years-giving.txt` instead of to the terminal.\n\n- `fgift -p=tests/test-files/previous-years-giving-list-test.txt tests/test-files/test-names.csv \u003e this-years-assignments.txt` Same as above; just uses `\u003e` to write to an output file.\n\n- `fgift -p tests/test-files/previous-years-giving-list-test.txt -s tests/test-files/special-requests-test.txt tests/test-files/test-names.csv` Creates gift assignments that respects special requests made in `special-requests-test.txt` file, then avoids repeating any assignments found in `previous-years-giving-list-test.txt`.\n\n## Using FGift: Optional files and when to use them\nAs shown in the above examples, in addition to the required NAMES file, users can also provide (a) a text file of who has given to who in previous years, if you want to avoid reassignments, and/or (b) a file with special requests, which will be fulfilled as specified. \n\nBoth of these optional files should look just like the output text (i.e. \"Claire gives to Cameron\"), with each assignment on its own line.\n\n## Notes on randomness in FGift\nFor an investigation into how \"random\" the gift assignments this programs makes, see [\"Notes on Randomness\" document](./notes-on-randomness.markdown).\n\n## Goal of longevity\nFor personal reasons, one of the goals of this project is for it to work for decades with little to no maintenance. I'm hoping that Rust was a good choice for this, specifically with [its \"edition\" system](https://doc.rust-lang.org/edition-guide/introduction.html).\n\nPython, Javascript, C++, [Zig](https://ziglang.org/) or even [Hare](https://harelang.org/) would also be interesting choices.\n\n## For developers: How to create a release of FGift\nThis project uses [cargo-dist](https://opensource.axo.dev/cargo-dist/) (sometimes known as simply \"dist\") to create releases. \n\nSome of [my personal docs on how to use cargo-dist are here](https://sts10.github.io/docs/cargo-dist-tips.html); but basically, `cargo install cargo-dist`. When you're ready to cut a new release, test the current state of the project with `dist build` and `dist plan`. If that went well, create a new git tag that matches the current project version in `Cargo.toml` with `git tag vX.X.X`. Finally, run `git push --tags` to kick off the release process. GitHub will handle it from here -- check [this repository's Releases page](https://github.com/sts10/fgift/releases) about 5 to 10 minutes after running `git push --tags` locally.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsts10%2Ffgift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsts10%2Ffgift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsts10%2Ffgift/lists"}