{"id":37202954,"url":"https://github.com/thinkparq/beegfs-go","last_synced_at":"2026-01-14T23:24:46.977Z","repository":{"id":289543330,"uuid":"858945477","full_name":"ThinkParQ/beegfs-go","owner":"ThinkParQ","description":"BeeGFS 🛠️ software and 📚 libraries written in Go such as the 🆕 BeeGFS command-line tool.","archived":false,"fork":false,"pushed_at":"2026-01-10T19:57:55.000Z","size":2465,"stargazers_count":9,"open_issues_count":66,"forks_count":2,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-01-11T05:53:42.118Z","etag":null,"topics":["badgerdb","beegfs","cli","s3"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThinkParQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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":"2024-09-17T20:01:51.000Z","updated_at":"2025-12-19T21:20:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"d903cb4b-94bd-4842-a59d-38cbf52e3d71","html_url":"https://github.com/ThinkParQ/beegfs-go","commit_stats":null,"previous_names":["thinkparq/beegfs-go"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/ThinkParQ/beegfs-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinkParQ%2Fbeegfs-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinkParQ%2Fbeegfs-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinkParQ%2Fbeegfs-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinkParQ%2Fbeegfs-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThinkParQ","download_url":"https://codeload.github.com/ThinkParQ/beegfs-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThinkParQ%2Fbeegfs-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28437981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T22:37:52.437Z","status":"ssl_error","status_checked_at":"2026-01-14T22:37:31.496Z","response_time":107,"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":["badgerdb","beegfs","cli","s3"],"created_at":"2026-01-14T23:24:46.016Z","updated_at":"2026-01-14T23:24:46.960Z","avatar_url":"https://github.com/ThinkParQ.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nbeegfs-go \u003c!-- omit in toc --\u003e\n=========\n\n# Contents \u003c!-- omit in toc --\u003e\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Building (With or Without Packaging)](#building-with-or-without-packaging)\n  - [Importing functionality into other Go projects](#importing-functionality-into-other-go-projects)\n- [FAQs:](#faqs)\n  - [How is the project versioned?](#how-is-the-project-versioned)\n    - [Why not just use the same version for the Go module and binaries it provides?](#why-not-just-use-the-same-version-for-the-go-module-and-binaries-it-provides)\n    - [Is there precedence for this versioning scheme?](#is-there-precedence-for-this-versioning-scheme)\n    - [Will eventually the version namespaces collide?](#will-eventually-the-version-namespaces-collide)\n    - [Why not just use different tags for the module and binaries?](#why-not-just-use-different-tags-for-the-module-and-binaries)\n  - [Can you explain the early development history of this project?](#can-you-explain-the-early-development-history-of-this-project)\n    - [Why am I unable to access some issue and PR links?](#why-am-i-unable-to-access-some-issue-and-pr-links)\n\nThe purpose of this repository is twofold:\n\n* Provide Go packages for interacting with BeeGFS.\n* Provide BeeGFS-related software written in Go, such as the `beegfs` command-line tool.\n\nThe overall project is setup as a [Go module](https://go.dev/blog/using-go-modules) which is a\ncollection of Go packages stored in a file tree with a `go.mod` file at its root:\n\n* `common/`: Contains shared Go packages that can be imported by other projects. These packages\n  provide common \"low-level\" functionality for interacting with BeeGFS and along with basic\n  application components (logging, configuration, databases, etc.) and serve as building blocks\n  \"higher-level\" applications and libraries written in Go.\n* Other top-level directories (e.g., `ctl/`) contain applications and libraries built on the\n  low-level functionality and other components in `common/`. Most developers interested in\n  integrating BeeGFS with some external application will want to start here.\n  * These directories generally adhere to the unofficial [Standard Go Project\n    Layout](https://github.com/golang-standards/project-layout).\n\nIMPORTANT: This repository is not be used for storing protocol buffers as those are not specific to\nprojects in Go. See the [protocol buffers](https://github.com/thinkparq/protobuf) repository for\n`.proto` files and precompiled libraries for Go and other languages.\n\n# Getting Started\n\n## Prerequisites\n\n* If you just want to build/run the project without OS packages, all you need to do is [install\n  Go](https://go.dev/doc/install).\n* If you want to build packages you also need to [install Go\n  Releaser](https://goreleaser.com/install/#go-install).\n\nIf you are interested in contributing to the project please refer to [Getting Started with\nGo](https://github.com/ThinkParQ/beegfs-go/wiki/Getting-Started-with-Go) in the project wiki.\n\n## Building (With or Without Packaging)\n\nThere are a few ways to run the components found in this project:\n\n* Directly build and run (best for debugging): `go run ctl/cmd/beegfs/main.go`\n\n* Install to your `$GOBIN` (best if you just want to run the applications): `go install ./ctl/cmd/beegfs/`\n  * For convenience there are also Makefile targets to install/uninstall binaries to `$HOME/go/bin`.\n    Use `make install` / `make uninstall` to install everything, or to install a specific binary\n    specify `install-\u003cname\u003e` (i.e., for `ctl/` run `make install-ctl` / `make uninstall-ctl`).\n\n* Build and install using OS packages: `make package-all` \n  * Install the resulting packages using `dpkg -i \u003cpackage\u003e` or similar.\n\nBelow replace `ctl/cmd/beegfs/main.go` with the path to the `main.go` file for the component you\nwant to run. Refer to the documentation included with each component for more details.\n\n## Importing functionality into other Go projects\n\nIf you just want to use some common functionality in your project, first run `go get\ngithub.com/thinkparq/beegfs-go@latest` then import/use the shared package(s) as needed throughout\nyour project. The `beegfs-go` project is meant to be used as a Go module meaning you can (and\nshould) pin your `go.mod` file to a particular stable version of beegfs-go. See versioning in the\nFAQ section below to ensure you use the correct version.\n\nIndividual modules can then be imported, for example to use the logging package:\n\n```go\nimport \"github.com/thinkparq/beegfs-go/common/logging\"\n\nmyConfig := logging.Config{\n    Type: \"stdout\",\n    Level: 5,\n}\n\nfunc main() {\n  logger, _ := logging.New(myConfig) // Ignore error for brevity.\n  logger.Info(\"This is an informational message\")\n}\n```\nFor details on using a particular package refer to its documentation. Generally, packages are\ndocumented using Go doc comments, which can be read directly from the source files or with the\ncommand line `go doc` (e.g., `go doc logging`). An interactive doc site can also be started using\nthe godoc tool (`go get golang.org/x/tools/cmd/godoc`) with `godoc -http=:8080`. Some packages may\nalso provide additional documentation in markdown format.\n\n# FAQs:\n\n## How is the project versioned?\n\nBeeGFS OS packages/binaries built from this repository and the `beegfs-go` module that provides\nreusable Go packages currently follow slightly different versioning schemes:\n\n* OS packages/binaries built from this repository follow the same versioning scheme as the other BeeGFS\n  components and start at version `v8.y.z`. \n  * For example if you want to build the version of the `beegfs` tool compatible with BeeGFS 8.0.0\n    you would check out the `v8.0.0` tag.\n* The Go module and reusable packages it provides will remain at `v0` indicating the Go module's API\n  is not necessarily guaranteed to be stable. For each `v8.y` BeeGFS `major.minor` release, the\n  module's API will be versioned as `v0.8.y`. Patch versions will not have a corresponding module\n  version tag and instead a [pseudo-version](https://go.dev/ref/mod#pseudo-versions) should be used.\n  Examples:\n  * To import Go packages from the `beegfs-go` module that work with BeeGFS `v8.1.0` you\n    would run `go get github.com/thinkparq/beegfs-go@v0.8.1`.\n  * If you needed to import new functionality or a bug fix in between major/minor versions you would\n    use a [pseudo-version](https://go.dev/ref/mod#pseudo-versions) by running `go get\n    github.com/thinkparq/beegfs-go@\u003cLONG-COMMIT-HASH\u003e` to import a specific commit.\n\n### Why not just use the same version for the Go module and binaries it provides?\n\nThere are a few reasons for this:\n\nFirst, Go has specific rules around [module version\nnumbering](https://go.dev/doc/modules/version-numbers). Once we move past `v0` or `v1`, the module\npath must be updated to include the version (i.e., `github.com/thinkparq/beegfs-go/v8`). However, it\nwould be ideal to provide a single Go module that maintains compatibility across different BeeGFS\nversions. This approach simplifies development for maintainers of `beegfs-go` (as there is no need\nto backport fixes to multiple branches) and makes it easier for external users. Since we cannot yet\ndetermine if future major BeeGFS versions will require breaking changes to the Go module, there is\nno immediate need to synchronize the versions.\n\nSecond, moving past `v0` signals that the module's external API is stable and guaranteed not to\nchange. While we believe the external API is largely stable, we think it is still prudent to wait\nbefore making this guarantee to users.\n\nIn short, moving past v0 is a one way trip. Until there is a compelling reason to do so, sticking at\n`v0` leaves more options available for how to handle module versioning in the future.\n\n### Is there precedence for this versioning scheme?\n\nYes, Kubernetes releases are versioned as `v1.31.0`, but the [`kubernetes/client-go`\nmodule](https://github.com/kubernetes/client-go?tab=readme-ov-file#versioning) is versioned as\n`v0.31.0`, signaling no API stability is guaranteed (and they do break their API from time to time).\n\n### Will eventually the version namespaces collide? \n\nIf/when we bump from `v0` we would likely either bump to `v1` if we think we can provide one module\nthat works across multiple major BeeGFS versions, or bump directly to sync with the BeeGFS major\nversion if backward compatibility cannot be ensured.\n\n### Why not just use different tags for the module and binaries?\n\nWe use GoReleaser to build binaries and OS packages. It expects to work with a tag that follows\nsemantic versioning rules, and currently does not appear to provide a way to extract a semver from a\nnon-semver tag. However we only run GoReleaser on tags prefixed with `v8.` and the actions workflow\nis configured to only run on the pushed tag and determine the previous tag based on the most recent\nsemantic version before the current tag.\n\n## Can you explain the early development history of this project?\n\nEarly development of the components in this repository took place in separate private repositories.\nAs the project matured and we prepared for the v8.0.0 release, we evaluated the need for this\nseparation and concluded there was no reason to keep the code split or private. The repositories\nwere then merged into a unified public repo: `beegfs-go`.\n\nThe full commit histories were preserved and stitched together to enable investigation into\narchitectural decisions made during early development. However, as part of the consolidation\nprocess, the code was reorganized into subdirectories. This means that older commits prior to\n`v8.0.0` (or `v0.8.0`) may not build successfully, since their original structure may have changed.\n\nNote those original repositories are archived and read-only. All development now happens on the\npublic `beegfs-go` repository.\n\n### Why am I unable to access some issue and PR links?\n\nWhen merging commit histories, we rewrote commit messages to include references to the original\nrepositories (e.g., `bee-remote/#23`, `bee-watch/#10`) to preserve context. However, these links may\nnot work for everyone because the original repositories remain private.\n\nWe chose not to make those original repositories public due to privacy concerns. For example, to\nprotect contributor privacy, we updated all commit metadata in this public repo to use GitHub\nnoreply emails, but sanitizing historical PRs, issues, and branches across multiple private repos is\nnon-trivial and could still expose private data. If you come across one of these broken links, feel\nfree to ask in a GitHub Discussion or open an issue if you need clarification.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthinkparq%2Fbeegfs-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthinkparq%2Fbeegfs-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthinkparq%2Fbeegfs-go/lists"}