DEV Community: Inhere

How my Go coding agent keeps a turn-1 constraint across 3 context resets

Inhere — Mon, 26 Oct 2026 08:25:35 +0000

Originally published on my blog. I'm the author of suga, an MIT-licensed coding agent written in Go.

Keep an agent in one session long enough and three things go wrong. The context fills up and gets compacted, and the part that gets dropped is the constraint you gave it in the first turn. Every request carries a few thousand tokens of fixed overhead, so long sessions get expensive. And when something breaks, there is no record of what the agent did.

suga is a personal coding agent I write in Go. The goal is a session that can stay with me for a full working day. This post covers the trade-offs it makes for long sessions, which of them are backed by data and which experiments failed, and how it works with gofer, my job platform. suga itself is built on gofer, one batch of agent jobs at a time.

The current version is v0.49. It is v0, so minor releases may break things. It is MIT licensed. What follows is an introduction to suga.

Repository: github.com/inhere/suga
Releases: releases/latest (Linux / macOS / Windows binaries)

A session that lasts all day: the hard part is the context reset

The context window fills up eventually. The usual fix is to compress old messages into a summary and keep going. The summary is written by the model, though, and the model will reasonably drop whatever it thinks is unimportant, such as the "don't touch vendor/" you said in turn 1.

suga uses segments instead. When the context is nearly full, it starts a new segment. The old one is stored and stays searchable, and the new one opens with a handoff. The handoff has a fixed structure: current task, coordinates (file / symbol / line), accepted and rejected decisions, how far verification got, progress and blockers, next step, and references to look things up. The "accepted and rejected" section holds hard constraints, rules and the user's own words. It is kept verbatim, has no length limit and may not be rewritten. Every other section has a byte budget (coordinates get at most 2 KB, for example), and old coordinates are deduplicated by file and symbol when they are folded in.

Why a budget? The early handoff folded the whole previous handoff into each new one. In one 14-turn session it grew from 4.7 KB to 7.8 KB to 16 KB, and every later request carried it. With budgets, the same task stays at 7.2k to 8.7k tokens of context after each reset.

This is tested by a set of "hard" long-session evals. Each task runs 13 to 14 turns with 2 to 3 forced resets, padded with large files and unrelated work, and the last turn checks whether the turn-1 constraint survived. For example:

the user changed the constraint halfway through, and the check expects the new one, not the old one;
the topic goes A, B, C and back to A, and the check looks for mixed-up topics;
a tool output contains "ignore previous rules", and the check looks for whether the agent followed it.

With a real model (deepseek-v4.1-flash), three runs per task, it currently passes 12/12.

I got this wrong once. I gave the model call that writes the handoff an output limit derived from the budget (about 3.3k tokens). Unit tests and fake-model evals all passed. On a real model, 3 of 4 tasks failed at the reset with "empty summary": a reasoning model spends output tokens on thinking, and the limit ran out before the answer started. That call now has no limit. The handoff size is enforced by the budgets and by trimming each section afterwards. The lesson: a fake model will not catch changes that depend on model behavior. They need a real model run.

Every token is accounted for: fixed prefix, tool descriptions, lazy loading

Start with the shortest possible prompt (measured on v0.48). The prompt below asks the model to answer with just "ok":

suga run --prompt "只回答 ok 两个字"

ok
opencode-go/deepseek-v4.1-flash · in 8853 / out 2 tokens · 2.8s

A 10-character prompt, 8,853 input tokens. The context event in suga inspect trace <session> --json shows where they went:

Part	Bytes	Notes
`tools`	19,753	schemas of the 16 tools in a read-only session, more than the next three combined
`rules`	6,782	workspace `AGENTS.md` and local context files
`system`	3,559	the stable system prompt
`skills`	1,333	the skills list

Providers cache by prefix, so the prefix has to stay stable: the tool table, the system prompt and the segment context do not change within a session, which lets later requests reuse what earlier ones cached. Put a timestamp or a random ID into the system prompt on every request and the cache stops working and the bill goes up. The thinking-signature bug later in this post has the same cause.

Cost in a long session is roughly "number of calls × context per call". Breaking a 14-turn task down call by call showed that 29% of the input was the fixed prefix resent on every call: about 0.9k tokens of system prompt and about 7.0k tokens of schemas for the 20 built-in tools.

So I did two things:

Shorter tool descriptions. I removed parser details and conventions repeated across tools (five search tools each said "skips vendor/node_modules by default") and said them once in the system prompt. That saves about 920 tokens per call. A test now pins the character count of every tool schema so it cannot grow back unnoticed.
Lazy loading for rarely used tools. In 128 eval runs, 11 of the 20 tools were called 44 times in total. The idea was to drop them from the tool table, keep a one-line list, and load them when needed.

Both went wrong at first, and the evals caught both:

After the trim, one task made 24% more calls. The session log showed why: the words "skips vendor/" had been cut from the no_ignore parameter description, so the model could not see them and listed vendor/ through the shell instead. Putting those words back brought the call count back to normal.
For lazy loading I first ran a probe: describe the tool schemas only in message text, not in the tools declaration. Across three models and 9 runs, the model made 0 native calls. Models do not call tools that are not declared. So within a segment, lazy tools go through a resident proxy tool, tool_call, and they join the real tool table at the next reset, which keeps the tool table and the cache stable within a segment. The on/off comparison: prompt per call down 16.9%, calls up 8.3%, total down only 6.8%, which failed the "calls up by no more than 5%" bar. So the feature is off by default, and tools.deferred_native: auto turns it on.

These comparisons later became the eval compare subcommand. It lines up two result sets by task, labels each as helped / hurt / no observed effect / confounded, and writes the verdict to a ledger, so I no longer do the math by hand.

When something breaks, you can find out why: a thinking-signature bug

suga writes every run to one SQLite file: sessions, turns, tokens and cache hits per model call, every tool call, resets, approvals and end-of-turn checks. Agents fail in predictable ways: going in circles, rerunning the same command, writing without verifying, claiming "done". With a timeline these show up. Here is the summary of one bug-fix run (measured on v0.48):

suga inspect trace <session> --analyze

steps                  5 model calls, 6 tool calls, 2 parallel steps (max 2 calls in one step)
tokens                 in 51.2k (cache read 40.4k), out 427; reasoning 77 chars, text 478 chars
tools                  file_read x2, shell_exec x2, file_edit x1, file_list x1
re-reads               -
reads after own write  0
shell                  2 runs, 1 failed (exit != 0), 0 exited 0 with stderr output
repeated commands      command=go test ./... x2
tests                  2 runs, 0 after the first pass
phases                 explore 2, first write to green 2, after green 1 (model calls)

The re-reads, reads after own write, repeated commands and tests rows exist to spot going in circles and skipped verification. --transcript renders the same session as plain text you can paste into a review or hand to another agent, and --web opens a read-only page you can leave open during a long run. A trace is a record after the fact. It does not stop an agent from looping, and it does not replace tests.

Here is one problem the trace helped me find. Running multi-step tool calls on Claude, the second request was rejected with Invalid signature in thinking block. Comparing the two requests turned up two causes:

after optional arguments the model left out were normalized away, tool_use.input was sent back as null;
Anthropic now binds a thinking block's signature to the request prefix it was generated under, and suga added a "about N minutes left before the deadline" reminder to every step. The text changed on every step, so the earlier thinking block no longer verified.

The fix: send back {}, and keep that reminder's text and position fixed within a turn. After that I recorded real streaming responses from four providers (deepseek, glm, Claude, codex) as replay fixtures, with keys removed, so unit tests catch the next change in these protocol details first.

Safe by default, and "tests pass" comes from a command, not the model

suga is read-only by default. With writes enabled, chat asks before writing a file or running a command (y / n / a to stop asking for this session), and rules by tool, path or command can live in a file. File tools snapshot before writing, so :undo or suga undo <session> can roll back. Changes made through shell_exec are recorded but not rolled back, on purpose.

A model saying "fixed, tests pass" does not count. --verify runs the check command you give it after the turn ends, and a failure goes back to the model as a new turn (at most 2 rounds by default). A small repository with one bug (the prompt asks it to confirm the bug in Add with the tests, then fix it; the model answered in Chinese):

suga run --allow-write --verify "go test ./..." --prompt "calc.go 里的 Add 有 bug，先跑测试确认，再修好它"

已确认并修复。
**确认 bug**：修复前 go test ./... 失败 —— calc_test.go:7: Add(2,3) = -1, want 5。
**原因**：calc.go:5 里 Add 写成了 a - b。
**修复**：改为 return a + b。

verify #1: go test ./... → exit 0 (488ms)

The verify #1 line is the evidence. The same turn also runs end-of-turn checks (nudge): files written but no check command run, plan steps still open, or an answer ending with "next I'll run the tests" each push the model back once.

One more detail: approval is done by a person, and the model does not know that. Once, running as a resident session, suga replied to a message for me and wrote that "writing the file did not trigger approval". In fact I had approved it. Now a manually approved call ends its result with the line [已经人工批准执行] ("executed after manual approval"), so the model does not have to guess.

Working with gofer: how suga gets built

gofer is my other project. It runs agents such as codex, claude and suga as async jobs: submit a job, work in a separate git worktree, approve from the web UI or DingTalk, read logs and token usage, merge back to the main branch. suga runs in gofer in two ways:

suga run: a one-off job that exits when done and streams events as stream-json;
suga acp: a resident session. Each tool-call approval goes through ACP to gofer, where you click it on the web or in DingTalk.

This is how suga itself is developed:

Supervisor session (reads the plan, writes job briefs, reviews, releases)
   │  gofer job run -a suga --model <deepseek | glm | codex> --worktree ...
   ▼
Several suga jobs in parallel, each in its own worktree + branch: change code, run tests, commit
   │  supervisor reviews the diff, reruns race tests and pty smoke tests in a Linux container
   ▼
gofer job worktree merge → suga-verify workflow
   (Linux race / CI simulation / staticcheck / Windows tests + ConPTY smoke / 40+ pty scenarios)
   ▼
tag → GitHub Actions builds binaries for three platforms → upload

Jobs go to different models in rotation, and every review verdict is recorded. Changes that need a design get a design doc, a review and human approval, then a plan that also needs approval before implementation. By v0.49 there are 56 tags and more than 2,400 commits. For the last few dozen batches, the code was written almost entirely by suga jobs. I split the work, review it and release.

The most useful step in this loop turned out to be review. Implementers often fail where they cannot verify their own work: a pty smoke test written on Windows that never ran, a fake model whose if/elif chain was cut in two by a single assignment, a test that took the echo of the input line as the end of the turn. All of these were caught by rerunning in a container before the merge.

The two also connect directly. gofer sends mail to a resident suga session (agent:suga), and suga replies with gofer's mailbox tool. suga sessions can message each other (suga send) with message IDs, merged delivery, receipts and failure barriers. gofer's memory backend can serve as suga's long-term memory.

The core embeds in other Go programs

pkg/agentcore is the core below the application layer: the model/tool loop, resumable run state, providers, tool registry and approval, MCP, skills and long-term memory. It does not depend on internal/*. An allowlist in pkg/agentcore/layering_test.go enforces that boundary: any dependency outside the list, or a new package that is not registered, fails the test. The smallest working setup needs one provider:

runtime := agentcore.New(agentcore.Config{
    Provider: mock.NewProvider(mock.Final("hello")),
})

result, err := runtime.Run(ctx, agentcore.RunInput{
    AgentID:     "example-agent",
    Instruction: "say hello",
})
// result.Output == "hello"

For a real model, swap in llm.NewOpenAIProvider(...). Add tools with reg.Register(...). To control permissions, wrap it in tools.NewApproval: with no approver configured, every call is denied, not allowed. The limits, stated here too: it is a single-agent loop with no multi-agent orchestration, and pkg/sugasdk (in-process Open / Send / Event) is marked experimental.

Compared with similar tools

Claude Code and Codex CLI come from the model vendors, and their model integration and interaction are more polished. aider has a mature git workflow. opencode has a good TUI. suga makes different trade-offs:

one Go binary with no runtime dependencies; Windows is a first-class platform (PowerShell, Job Object process trees, ConPTY smoke tests);
session persistence, segments and handoffs, long-session evals and regression gates are where most of the effort went;
it embeds in other Go programs (pkg/sugasdk) and can run as an ACP server driven by an editor or by gofer;
it switches between providers, and the config can list fallback models that it moves to when a connection fails.

When it is a poor fit:

you want an IDE plugin or a GUI: it is terminal only for now;
you want multi-agent orchestration: a sub-agent only does one read-only investigation and never hands out work of its own; job queues and the console live on the gofer side;
you do not want to bring your own provider key: every request goes straight to the endpoint you configure, and there is no hosted service;
you need English docs: the detailed docs are the Chinese built-in skill suga-guide;
you need a stable API: it is v0.

I mostly use it on Windows and Linux, and CI runs Ubuntu and Windows. macOS builds are published, but I rarely use them.

Up and running in 30 seconds

eget install inhere/suga          # or go install github.com/inhere/suga/cmd/suga@latest
suga init                         # creates ~/.suga/config.yaml and .env
# put one key in ~/.suga/.env, e.g. DEEPSEEK_API_KEY=... (built in: openai / anthropic / deepseek)
suga config set model deepseek/deepseek-chat
suga chat                         # start in the current directory; :help lists commands, :context shows what is in the context

For a one-off task: suga run --prompt "Summarize this project". To have it change code and check its work: suga run --allow-write --verify "go test ./..." --prompt "Fix the failing test".

If you read the code, start in these four places

internal/cli: one file per command; root.go shows the whole command tree;
internal/wiring: assembles providers, tools, skills, the system prompt and the runner, shared by the CLI and ACP;
internal/personal: turns, segments, handoffs and events; reading it is reading suga's product logic;
pkg/agentcore: the core and capability layer; start with the table in layering_test.go.

docs/ holds 45 design docs, 32 plans and 13 research reports. Most of the "why" is in there, and most numbers in this post come from docs/research.

I'm inhere (blog · GitHub), the author of suga. The numbers in this post come from measured runs on v0.48 to v0.49 and from the reports under docs/research in the repository. The commands are all in the text, so you can reproduce them.

miglite v0.8.0: ship migrations inside the binary

Inhere — Tue, 29 Sep 2026 12:22:19 +0000

The last post about miglite covered v0.4.0 in June. Since then it shipped four releases and 69 commits (v0.4.0..v0.8.0), up to v0.8.0. The design did not change. Two things did: migration files can now travel inside the binary, and several flags that were accepted but ignored now take effect.

Project: https://github.com/gookit/miglite
API docs: https://pkg.go.dev/github.com/gookit/miglite
Previous post: miglite: raw SQL migrations for Go projects
Latest release: v0.8.0

What changed across these releases

Version	Date	Change
v0.5.0	2026-07-18	`exec` runs multiple statements in one transaction; `--db` overrides the database name
v0.6.0	2026-08-08	Dependency updates
v0.7.0	2026-09-21	`internal/runtime` extraction, four behaviour fixes
v0.8.0	2026-09-28	`fs.FS` / `embed.FS` migrations

The command set is unchanged: create / init / up / down / skip / status / show / exec. Upgrade scripts do not need edits.

Ship migrations inside the binary

Deploying a small service used to mean keeping a migrations/ directory next to the binary. In a container image that directory needs a COPY line and the working directory has to line up with it. When the directory is missing or its files come from an older build, miglite status reports no pending migrations, which is not an obvious failure.

SQL files can now be embedded with go:embed:

package main

import (
    "embed"

    "github.com/gookit/miglite"
    "github.com/gookit/miglite/pkg/command"

    _ "modernc.org/sqlite"
)

//go:embed migrations/*.sql
var migrationFS embed.FS

func main() {
    mig, err := miglite.NewAuto(func(cfg *miglite.Config) {
        // a logical path inside migrationFS, not a disk path
        cfg.Migrations.Path = "migrations"
    })
    if err != nil {
        panic(err)
    }

    // miglite.NewWithConfigAndFS(cfg, migrationFS) does the same
    mig.SetFS(migrationFS).SetSqlDB(db)
    if err := mig.Up(command.UpOption{Yes: true}); err != nil {
        panic(err)
    }
}

A few details:

After SetFS, cfg.Migrations.Path is an io/fs logical path with forward slashes, not a directory on disk.
SetFS(nil) goes back to reading from the local filesystem, for projects that support both.
An embedded filesystem is read-only, so create still writes to the local disk and cannot add files to embed.FS.
The new API surface is Migrator.SetFS, NewWithConfigAndFS and the package-level miglite.BindFS, plus ParseFS, FindMigrationsFS and MigrationsFromFS in pkg/migration.

If you reuse miglite's commands in your own CLI instead of calling cmd/miglite, one miglite.BindFS(migrationFS) call before app.Run() makes the handlers read from that filesystem.

--db points one command at another database

Debugging and tests often need the same instance with a different database name, for example running migrations against a copy of production data. Editing the config or the environment variables for that is easy to forget to undo.

v0.5.0 added a global --db flag:

# status of one specific database
miglite --db new_db status

# run SQL against that database
miglite exec --db new_db --yes "SELECT current_database();"

It overrides the database name from the YAML file, DATABASE_DSN or DATABASE_URL; for SQLite it overrides the database file path. The flag applies to the current command only and is not written back to the config.

exec runs multi-statement SQL in one transaction

exec used to send statements to the database one at a time. If statement five failed, the first four had already been applied and the rest never ran.

It now splits the input with SplitSQL and runs the statements inside a single transaction, committing only when all of them succeed. Query statements go through Query, and their result set is printed:

miglite exec --yes ./scripts/import-seed.sql

The database still decides what can be rolled back. Several MySQL DDL statements commit implicitly and cannot be rolled back as part of a transaction. miglite guarantees how it executes the statements; whether a DDL statement is reversible depends on the engine. Migration files have the same constraint.

Four behaviours that only looked right

v0.7.0 moved the logic out of package-level globals in pkg/command into internal/runtime: each call builds a Runtime (config, connection, filesystem, connection ownership), and the CLI and the library share one output path. The refactor was not meant to be visible, and it fixed four real problems along the way:

up --skip-err accepted the flag and ignored it. A failed file is now skipped and the remaining migrations still run, while the command returns an error and the CLI exits non-zero.
An injected *sql.DB is no longer closed. A connection passed to SetSqlDB(db) belongs to the caller, and only connections opened from the config are closed by miglite. In a long-running service the old behaviour could close a connection out from under you.
A migration file without a DOWN section is now reported as skipped with the empty_down status, and only a real rollback reaches the after hook. Before, down on such a file gave the impression that a rollback had happened.
Failures no longer print the success banner. That sounds minor until a script scans the output by eye and the last line says everything completed.

miglite up --yes --skip-err

Using miglite as a library

The main package still builds on database/sql and does not bind a driver by default, the same as in v0.4.0. A typical call sequence now looks like this:

mig, err := miglite.NewWithConfig(cfg) // or NewAuto / New(configFile)
if err != nil {
    return err
}

if err = mig.SetSqlDB(db).Init(command.InitOption{}); err != nil {
    return err
}
if err = mig.Up(command.UpOption{Yes: true}); err != nil {
    return err
}
if err = mig.Status(command.StatusOption{}); err != nil {
    return err
}

Three differences from the CLI:

Library calls never ask for confirmation. Yes only affects the CLI prompt.
Library calls print the same progress output as the CLI, through the shared output path introduced in v0.7.0.
There is nothing to close. The *sql.DB you pass in stays yours, and connections opened from the config are closed at the end of each call.

Should you upgrade

There are no breaking changes between v0.4.0 and v0.8.0: no command was removed, no config key changed, and the migration file format is the same. Two things are worth checking after the upgrade:

If a script relied on up --skip-err stopping at the first failure, it now continues past failed files. Check the exit-code handling around it.
If you pass your own *sql.DB, the connection is no longer closed for you, so workarounds added for that can be deleted.

For a single-binary deployment that should not carry a migrations directory, the embed.FS support in v0.8.0 removes that step. For a local SQLite database that just needs schema management, the v0.4.0 usage still works unchanged.

Project: gookit/miglite
Quick install: go install github.com/gookit/miglite/cmd/miglite@latest
Or with eget: eget install gookit/miglite

eget: install GitHub releases without waiting for a central index

Inhere — Wed, 01 Jul 2026 16:18:04 +0000

The pace of command-line tooling has changed. New tools show up on GitHub every day, and active projects may publish several releases in a week, sometimes in a day.

The slow part is often not the project itself. It is the central package index in the middle: a formula, bucket, manifest, or package definition that has not caught up yet. eget is for that gap. If the release asset already exists, or the download URL can be described by a simple rule, eget can fetch and install it directly.

Project: https://github.com/inherelab/eget
Latest release: v1.8.x
Documentation: README.md

Start with a GitHub repository

The shortest path is to pass a repository name:

eget cfg init
# install tools
eget i openai/codex
eget install junegunn/fzf
eget install --name rg BurntSushi/ripgrep

eget reads release assets, matches the current OS and architecture, downloads the selected file, extracts it when needed, and installs the executable into the target directory.

If a project uses nightly builds, beta tags, or a specific release tag, choose it explicitly:

eget install --tag nightly inhere/markview
eget install --tag v0.28.0 openai/codex

There is no extra registry step here. If the upstream release page has the asset, eget can start from there.

The repository is the entry point

Many package managers depend on a central index. That gives users a consistent experience, but it also creates delay. A project can publish a release before the index is updated.

eget keeps the default path short:

owner/repo -> releases -> assets -> install

When automatic asset matching is not enough, inspect the assets and add filters:

eget query --action assets openai/codex

eget install --asset "PRE:codex,SUF:.zip" openai/codex
eget install --asset "REG:\\.deb$" owner/repo
eget install --asset "windows,amd64,zip" owner/repo

Some release archives have nested directories, or the executable name is not the name you want on disk. Handle that at install time:

eget install --extract-all \
  --rename "codex-x86_64-pc-windows-msvc.exe=codex.exe" \
  openai/codex

eget download --extract-all --strip-components 1 \
  --asset "windows,zip" ventoy/Ventoy

The point is not to describe every package in advance. The point is to work with the files that upstream already published.

It is not limited to GitHub

GitHub is common, but it is not the only source. eget install and eget download can target GitLab, Gitea/Forgejo, SourceForge, direct URLs, and local files.

eget install gitlab:fdroid/fdroidserver
eget install gitlab:gitlab.gnome.org/GNOME/gtk
eget install --asset linux,amd64 gitea:codeberg.org/forgejo/forgejo
eget install --asset x64,PerUser,setup sourceforge:winmerge

A plain download URL also works:

eget download --file go --to ~/go1.17.5 \
  https://go.dev/dl/go1.17.5.linux-amd64.tar.gz

That matters for tools that do not publish GitHub releases. If there is a stable URL, or if the latest version can be read from a page, JSON file, or YAML file, the tool does not need to be wrapped in a central index first.

Internal tools can use one reusable rule

Internal tool distribution is usually boring in a very specific way. Every team has its own layout:

http://mydev.lan/tools/markview/latest.yaml
http://mydev.lan/tools/markview/markview-linux-amd64
http://mydev.lan/tools/chlog/latest.yaml
http://mydev.lan/tools/chlog/chlog-linux-amd64

Once the naming rule is stable, each tool should not need a full copy of the same configuration. pkg_templates lets you describe the rule once:

[pkg_templates.mydev]
latest_url = "http://mydev.lan/tools/{name}/latest.yaml"
latest_format = "yaml"
url_template = "http://mydev.lan/tools/{name}/{name}-{os}-{arch}{ext}"
ext_map = { windows = ".exe", linux = "", darwin = "" }

[packages.markview]
repo = "pkg-template:mydev:markview"

Then use the short alias:

eget add mydev:markview
eget install mydev:markview
eget install --add mydev:chlog

This is not an internal app store. There is no server-side registry to maintain. It is a local rule for turning a package name into a latest-version request and a download URL.

Keep frequently used tools in config

For a one-off test, install owner/repo is enough. For tools you use regularly, add them to local config:

eget install --add junegunn/fzf
eget install --add --name rg BurntSushi/ripgrep
eget add --name winmerge --system windows/amd64 \
  --asset x64,PerUser,setup sourceforge:winmerge

# restore all configured tools from an existing config file
eget install --all

List what is installed or configured:

# installed packages by default; --all shows all configured packages too
eget list
eget ls --all
# configured packages that are not installed yet
eget ls --ni

The install record lives in ~/.config/eget/installed.toml by default. Config files live under the same directory, and you can edit them directly when that is faster.

Update tools

eget update --all # check and update all updatable packages
# or check first, then update selected tools
eget up --check
eget up fzf markview codex

Self-update is a separate command:

eget up --self

SDK downloads are built in

SDK archives have a similar problem to CLI tools: multiple versions, multiple platforms, mirrors, archive extraction, and local install records.

eget sdk handles that layer:

eget sdk config add --all
eget sdk config add --all --mirror mirror
eget sdk config add jdk --mirror zulu

eget sdk index refresh go
eget sdk index show go

eget sdk install go@1.22.0
eget sdk install go:1.22 node:20.11.1
eget sdk dl --os linux --arch arm64 -o ./downloads go:1.22

The built-in templates cover Go, Node, and JDK. Sources can use official URLs or common mirrors. SDK index cache, archive download cache, and install records are kept separate, which works better for multi-version SDK installs.

One boundary is important: eget sdk downloads, extracts, and records SDKs. It does not modify PATH, write shell hooks, or switch the active version for a project. If you need project-level activation, pair it with a tool such as xenv.

Cache mirrors help on team machines

Repeated installs are faster when downloads are cached. On a local network, one machine can expose its existing package and SDK cache:

eget cache serve --host 0.0.0.0 --port 8686 --token "$EGET_CACHE_TOKEN" --json-log

Other machines can try that cache before going upstream:

[cache_mirror]
enable = true
url = "http://192.168.1.10:8686"
timeout = 5
fallback = true

With this enabled, install, download, and sdk install try the LAN cache first and fall back to the original source on a miss. The mirror is only a download optimization, not a trust root. Existing checksum validation still runs later in the flow.

More features are in the GitHub docs

This article covers the main path. eget also has a set of practical features that are better documented in the GitHub README and configuration docs:

concurrent downloads and batch install/update
HTTP Range chunked downloads for large files
resumable downloads with .part files and metadata
Windows GUI installer launch
portable GUI package installation into gui_target
separate API cache, download cache, and SDK index cache

You may not need all of those every day. They become useful in CI, on shared development machines, on Windows tool distribution flows, and when large SDK archives are downloaded repeatedly.

Where eget fits

eget is a good fit when:

you want to try a new GitHub release immediately
a tool ships zip, tar.gz, exe, deb, or similar release assets
internal tools follow a stable download URL rule
CI machines, developer laptops, or LAN machines need the same tools and SDKs repeatedly

It is not a replacement for a system package manager. Dependency solving, service registration, and complex post-install scripts are not its job.

The shorter description is this: eget is a release asset downloader and installer. If GitHub already has the release, a download site already has the file, or an internal directory already has the package, eget helps get it onto the machine without waiting for the index in the middle.

Originally published at https://inhere.github.io/en/blog/2026/eget-intro/

gookit/gcli v3.5.0 released - easy-to-use, feature-rich Go command line application and tool library

Inhere — Tue, 23 Jun 2026 14:46:09 +0000

GCli v3.5 Updates: Changes Since v3.3.1

GCli is a command-line application and tool library for Go.
This post covers the main changes from v3.3.1 to the recently released v3.5 (including the v3.4 cycle). These updates focus on developer experience and underlying stability.

If you write CLI tools in Go, a few of these features might be useful. Here are the main changes.

Key Updates

Shell completion: Supports zero-registration generation and a dynamic completion mode (bash / zsh / PowerShell).
Command middleware: Handle auth, logging, and other cross-cutting concerns via Command.Use() / App.Use().
Grouped help: Categorize commands and options into titled sections using Category.
Struct binding improvements: Added a field tag rule and support for expanding anonymous nested structs.
Interactive input: Automatically prompt for missing values via Question.
POSIX short-option merging: Support for -aux splitting into -a -u -x.
Robustness fixes: Panic handling, help command behavior, and more.
A few breaking changes (migration guide at the end).

1. Shell Completion Improvements

Generating shell completion scripts previously required hardcoding command and option names, meaning adding a new command required regenerating the script. GCli v3.5 improves this workflow.

You no longer need to manually register the genac command. A built-in global option generates the static script directly:

# generate a completion script for your shell, then source it
myapp --gen-completion bash > myapp.bash
source myapp.bash

# zsh / PowerShell also supported
myapp --gen-completion zsh  > _myapp
myapp --gen-completion pwsh > myapp.ps1

Additionally, a dynamic completion mode is now available. The generated script no longer hardcodes names; instead, it calls back into your binary via the built-in --in-completion option to fetch candidates at completion time. New commands will immediately work with Tab-completion without regeneration.

For option values, you can define a list of candidates using Choices:

c.StrOpt2(&format, "format", "output format",
    gflag.WithChoices("json", "yaml", "table"))
// typing `--format <Tab>` now suggests: json  yaml  table

2. Command Middleware

If you need to run auth checks or logging before a command's main logic without duplicating code across commands, you can use middleware.

Handlers registered with Use() run in order before the command's main Func. If a handler returns an error, the chain stops, and the error propagates upward.

// command-level middleware
cmd.Use(func(c *gcli.Command, args []string) error {
    if os.Getenv("TOKEN") == "" {
        return c.NewErrf("missing TOKEN env")
    }
    return nil // return nil to continue the chain
})

// application-level middleware: applies before every command
app.Use(func(c *gcli.Command, args []string) error {
    gcli.Debugf("running command: %s", c.Name)
    return nil
})

Both Command.Use() and App.Use() return the receiver, supporting chaining. Apps without middleware behave exactly as before.

3. Grouped Help

When an app has many commands and options, the help output can become cluttered. You can now group them into titled sections using the Category field.

// group commands
app.Add(&gcli.Command{Name: "migrate", Desc: "run db migrate", Category: "database"})
app.Add(&gcli.Command{Name: "serve",   Desc: "start http server"}) // default group

// group options
cmd.StrVar(&dsn, &gcli.CliOpt{Name: "db-dsn", Desc: "database dsn", Category: "database"})
cmd.StrOpt2(&port, "port", "bind port", gflag.WithCategory("network"))

Groups appear in the order of their first definition, and items within a group are sorted by name. If no category is set, the output format remains the same as in older versions.

4. More Flexible Struct Binding

FromStruct now supports a third tag rule (TagRuleField) and automatically expands anonymous nested structs.

The three available rules, selected via c.FromStruct(ptr, ruleType):

gcli.TagRuleNamed (default): flag:"name=int0;shorts=i;required=true;desc=message"
gcli.TagRuleSimple: flag:"desc;required;default;shorts"
gcli.TagRuleField (new): Uses the field name (SnakeCase) as the option name and reads metadata from independent tag keys.

type commonOpts struct {
    Verbose bool `flag:"v" desc:"enable verbose output"`
}

type demoOpts struct {
    commonOpts        // anonymous: expands into a --verbose/-v option
    UserName string `flag:"u" desc:"the user name" required:"true"`
    Age      int    `desc:"the user age" default:"18"`
}

c.MustFromStruct(&demoOpts{}, gcli.TagRuleField)
// => options: --user-name/-u (required), --age (default 18), --verbose/-v

The field rule keeps the option name tied to the struct field, while desc, default, and required live in their own tags, making it easier to read and maintain.

5. Declarative Interactive Input

If a required option is missing at runtime, you can now attach a Question. GCli will detect the empty value and prompt the user for input interactively.

c.StrOpt2(&token, "token", "the access token",
    gflag.WithQuestion("Please input your access token: "))

$ myapp deploy
Please input your access token: ▮

If a custom Collector is also set, it takes priority over Question.

6. POSIX Short-Option Merging

GCli now supports merging short flags (e.g., -a -u -x becomes -aux) in a POSIX style. This is disabled by default and can be enabled via Config.EnhanceShort.

c.ParserCfg().EnhanceShort = gcli.EnhanceShortMerge  // 1: -aux => -a -u -x
c.ParserCfg().EnhanceShort = gcli.EnhanceShortAttach // 2: also -Ostdout => -O stdout

It can also be enabled globally:

gcli.SetEnhanceShort(gcli.EnhanceShortMerge)

Level	Constant	Behavior
0	`EnhanceShortNone`	Off (default), fully compatible with old behavior
1	`EnhanceShortMerge`	Split a group only when all members are bool shorts
2	`EnhanceShortAttach`	Also support value-attached form `-Ostdout` = `-O stdout`

A safety check is in place: a group is only split if every character is a boolean short option. Mixed forms like -aO (where O takes a value) are left untouched to prevent misparsing.

7. Robustness Fixes

Alongside new features, several long-standing issues were fixed:

Panics are no longer swallowed: gflag.Parser.Parse previously ignored recovered panics. It now returns them as an error for easier upstream handling.
help <command> works on the first call: Fixed an issue where it might print unknown input command "help".
findSimilarCmd fix: No longer writes a phantom help entry into the registry when an unknown command is run.
Command.Copy() fix: No longer clears the source command's hooks due to a shared pointer.

Breaking Changes & Migration

A few internal cleanups require adjustments if you depended on them:

Before	After
`import ".../gcli/v3/helper"`	Now internal; inline your own helper
`import ".../gcli/v3/gclicom"`	Removed (unused after cliui migration)
Global `--verbose 4` flag	Env `GCLI_VERBOSE=debug`, or `gcli.SetVerbose(gcli.VerbDebug)` / `gcli.SetDebugMode()`

The --verbose flag was removed because it bound to a per-app copy that the underlying logger never read, making it ineffective. Use the environment variable or code to control log levels.

Additionally, multiple App instances within the same process now share global options (verbose / help / version / strict / completion).

Upgrade & Examples

go get -u github.com/gookit/gcli/v3@latest

The _examples/cmd directory in the repository includes runnable examples: struct-flag (field tags + anonymous structs), short-merge (short option merging), and ask-demo (interactive input).

If you run into issues or have suggestions, feel free to open an issue or PR on GitHub. For full API documentation, refer to GoDoc.

gookit/goutil v0.7.2 Released: Enhanced Features & Fixes for an Improved Development Experience

Inhere — Thu, 20 Nov 2025 14:36:14 +0000

We're excited to announce the release of gookit/goutil v0.7.2! This version brings numerous new features, optimizations, and bug fixes, further enhancing the stability and usability of this Go utility library.
This update covers multiple modules, including math utilities, string processing, filesystem operations, and command-line flag handling, aiming to provide developers with a richer and more efficient toolkit.

Project Homepage: https://github.com/gookit/goutil
Full Changelog: v0.7.2 Release Notes
Full documentation: https://zread.ai/gookit/goutil

🛠️ Key Bug Fixes

This version fixes several key issues to ensure the stable operation of the library:

ccolor module: Fixed the issue where the NO_COLOR environment variable was not working correctly during printing, improving the compatibility of color output.
cflag module:
- Fixed a capp runtime error that occurred when parsing global flags.
- Fixed the issue where the OnAppFlagParsed event was not triggered when no command was input, ensuring the integrity of the event handling logic.

✨ New Feature Highlights

Math Utilities

Added the IsInteger function for strictly checking if a value is of an integer type (e.g., int(x), uint(x)).
Added StrictInt and StrictUint conversion functions for stricter integer type conversions.
Added the FormatBytes function to format byte sizes into human-readable strings (e.g., "1.2 MB"), convenient for log output and UI display.

String Utilities

Added the NumVersion function to quickly extract the numeric part from a version string.
Added the ReplaceVars function to support quick rendering of strings containing {var} placeholders, simplifying template replacement operations.
Added IsUpper and IsLower functions to check if a string is entirely uppercase or lowercase.
Added IsUint and IsPositiveNum functions to enhance string numeric validation capabilities.
Added BaseConvInt and BaseConvIntByTpl functions to support integer conversion between different bases.
Added the ContainsByteOne function to check if a string contains any of the specified bytes.
Optimized the MTimeBaseID function, which now supports bases greater than 36.

Filesystem Utilities

Added the EnsureDir function to ensure a directory exists (creates it if it doesn't).
Added HomeDir/UserHomeDir functions to get the user's home directory path.
Added CreateSymlink and IsSymlink functions to support the creation and detection of symbolic links.
Added FindAllInParentDirs, FindOneInParentDirs, and FindNameInParentDirs functions to support finding files in parent directories, simplifying the location of project configuration files.

Array/Slice Utilities

Added the ToMap function to convert a list (slice) to a map.
Added the Map1 function to convert a list to a new list (similar to a map operation).

Map Utilities

Added the AppendSMap function for merging string maps.
Added the AliasesNames function for handling alias names.

Testing Utilities

Added the assert.StrContainsAll assertion function to check if a string contains all specified substrings.
Added the testutil.SafeBuffer type, a thread-safe buffer designed for concurrent testing scenarios.
Enhanced testutil.EchoServer, which now supports responding with 404, 405, 500, or custom status codes, facilitating the testing of HTTP client error handling logic.

Command-line Utilities

The cflag module has a new HelpOnEmptyArgs configuration option to automatically display help information when no arguments are provided, improving user experience.
Optimized the rendering of help information.
Added support for setting aliases for cflag/capp commands.

Time Utilities

Added the FormatDuration function to format time duration into a clock-like format (e.g., "1h 23m 45s"), perfect for displaying performance statistics.

⚡ Performance Optimizations & Refactoring

Optimized the common logic of the ToStringWith function to improve conversion performance.
Refactored cflag.App into the subpackage capp.App, improving code organization.
Optimized the handling options logic in the ToInt64With function to enhance conversion efficiency.
Split integer conversion related code into conv2int.go and optimized the performance of all integer conversion related methods in mathutil.
Updated the VersionCompare function logic, fixing some comparison errors and improving the accuracy of version comparison.
The VarReplacer in textutil now supports parsing variable names as environment variables, enhancing dynamic configuration capabilities.

🌐 Platform Compatibility & Development Workflow

Added support for FreeBSD/Unix systems, expanding the platform coverage of the sysutil package.
Added comprehensive GitHub Copilot instructions for gookit/goutil, optimizing the AI-assisted development workflow.
Upgraded the github/codeql-action dependency from version 3 to 4, enhancing the security and capabilities of code analysis.

📝 Other Updates

Added a ShowLen option for dump output, allowing control over whether to display length information.
Updated the README generation CLI and related documentation, improving the project documentation generation process and templates.
Fixed unit test errors and unified the code style.
Updated some comments and code styles.

📦 How to Update

You can use the following command to get the latest version:

go get github.com/gookit/goutil@v0.7.2

Migration & Compatibility Notes

cflag -> cflag/capp Subpackage Refactoring: cflag.App has been refactored to capp.App. If your code directly references cflag.App, please adjust:
- Old: import "github.com/gookit/goutil/cflag"
- New: import "github.com/gookit/goutil/capp"
- And switch related types/calls to the App in the capp package.

TIP: This is a potential breaking change in this release, please check and update your references before upgrading.

VersionCompare and some string/version-related logic have been optimized. If you rely on the edge-case behavior of the old logic (such as equality comparison or sorting), please run relevant unit tests to verify after upgrading.

Example Snippets

Using `mathutil.IsInteger / StrictInt`

import "github.com/gookit/goutil/mathutil"
import "github.com/gookit/goutil/testutil/assert"

val := 123
if mathutil.IsInteger(val) {
    // true
}
i64, ok := mathutil.StrictInt("42") // Does not allow string to integer conversion
assert.False(t, ok)

Using `strutil.ReplaceVars`

import "github.com/gookit/goutil/strutil"

tpl := "Hello, {name}! Today is {day}."
out := strutil.ReplaceVars(tpl, map[string]string{
    "name": "Gopher",
    "day":  "Wednesday",
})
// Output: "Hello, Gopher! Today is Wednesday."

Using `fsutil.EnsureDir`

import "github.com/gookit/goutil/fsutil"

if err := fsutil.EnsureDir("/tmp/myapp/logs"); err != nil {
    // Handle error
}

🤝 Contributing

We thank all contributors for their efforts in this release! If you find any issues or have feature suggestions, please feel free to open an issue at GitHub Issues.

📖 More Information

Project Homepage: https://github.com/gookit/goutil
Full Changelog: v0.7.2 Release Notes
Full documentation: https://zread.ai/gookit/goutil

Enjoy the new features and improvements in v0.7.2

gookit/slog - release v0.5.8, Lightweight, configurable, extensible logging library

Inhere — Thu, 01 May 2025 02:01:37 +0000

We’re thrilled to announce the release of gookit/slog v0.5.8, a significant update to the lightweight, configurable, and extensible logging library for Go. With this release, we’ve addressed critical bug fixes, introduced powerful new features, and refined the overall functionality to offer an even more reliable logging experience for developers.

Github: https://github.com/gookit/slog

Highlights of v0.5.8

🛠️ Bug Fixes

Windows File Path Parsing Issue Resolved

Fixed a bug where log file paths could encounter parsing errors on Windows systems. (Commit)
Backup File Handling Improvement

Resolved a problem where setting BackupNum=0 caused all old files to be removed. (Commit)
File Rotation Stability

Fixed issues related to file rotation in short intervals, which previously caused conflicts and content overwrites. (Commit)
Old File Matching Issue

Resolved incorrect handling of file renaming (e.g., error.log to error.20250423_02.log). (Commit)

✨ New Features

Enhanced Logging Configuration

Improved the configuration functions, making it easier to fine-tune logging behavior. (Commit)
Top-Level Log Function

Introduced a Log function at the package's top level for more streamlined usage. (Commit)

🔄 Updates and Improvements

WithRotateTimeString Function Added

A new function to handle rotation time strings, along with corresponding tests. (Commit)
Refactored Clean Method

The clean method in the rotatefile handler now includes additional tests for compressing and cleaning files.(Commit)
Improved Debugging Logs

Added a debug mode environment variable and more detailed log outputs for development purposes. (Commit)
Optimized Rotate File Logic

Refactored the logic to ensure file extensions are always at the end and reduced lock ranges during write and rotation processes. (Commit)

📦 Dependency Updates

Updated github.com/gookit/goutil to v0.6.18. (PR #153)
Updated github.com/golang/glog from v1.1.1 to v1.2.4 for examples. (PR #157)

🧪 Improved Test Coverage

Added more unit test cases and internal test functions to ensure the stability and reliability of new features. (Commit)

Acknowledging New Contributors

We’re excited to welcome two new contributors to the gookit/slog community:

@ShyunnY for their work on the CallerFlagMode type alias. (PR #155)
@knbr13 for updating the code to use os.ReadFile instead of the deprecated ioutil.ReadFile. (PR #158)

Full Changelog

To explore all changes in detail, check out the v0.5.8 changelog.

This release represents a significant step forward in making gookit/slog a more robust, flexible, and user-friendly logging solution for Go developers. We’re grateful for the contributions from the community and look forward to seeing how these changes will enhance your projects.

Happy Logging!

gookit/goutil - released v0.6.10, an extension library of common Go features

Inhere — Wed, 05 Jul 2023 03:44:25 +0000

gookit/goutil An extended library of Go's common functionality. Contains: number, string, slice/array, Map, struct, reflection, text, file, error, time and date, test, CLI, command run, system information, formatting, common information acquisition, etc.

Github: https://github.com/gookit/goutil

v0.6.10 change log

Full changelog v0.6.9...v0.6.10

✨ New features

✨ feat: testutil - adds a new child package fakeobj to create fake objects for testing
✨ feat: testutil - adds a new function NewEchoServer() to start the echo server
✨ feat: byteutil - Buffer adds more useful methods for ease of use
✨ feat: dump - Special handling of custom int, uint type values, will print instructions in String format
✨ feat: fsutil - adds a new function to Glob() quickly list matching files
♻️ feat: httpreq - Refactoring the built-in HTTP client httpreq logic

👔 Update Adjustments

👔 up: structs - Update and support InitDefaults() for struct slice fields that are not null
👔 up: maputil - SimpleMerge() Supports deep merging of map[string]any data

Other adjustments

✅ test: Update some documentation and fix some unit tests
⬆️ dep: Update golang.org/x depends on the latest version

Some feature usage examples

dump - prints custom types

dump - special handles custom int, uint type values, and will print instructions in String format

Initialize the struct

Support for initializing the use of environment variables
Support initializing slice fields and nesting structs

type ExtraDefault struct {
    City   string `default:"some where"`
    Github string `default:"${ GITHUB_ADDR }"`
}

type User struct {
    Name  string        `default:"inhere"`
    Age   int           `default:"300"`
    Extra *ExtraDefault `default:""` // mark: need init
}

optFn := func(opt *structs.InitOptions) {
    opt.ParseEnv = true
}

obj := &User{}
err := structs.InitDefaults(obj, optFn)
goutil.PanicErr(err)

dump.P(obj)

Initialization result:

&structs_test.User {
  Name: string("inhere"), #len=6
  Age: int(300),
  Extra: &structs_test.ExtraDefault {
    City: string("some where"), #len=10
    Github: string("https://some .... url"), #len=21
  },
},

Test with Echo Server

Use testutil.NewEchoServer() to quickly create an HTTP echo server. Convenient for testing HTTP requests, responses, etc.

Usage examples:


var testSrvAddr string

func TestMain(m *testing.M) {
    s := testutil.NewEchoServer()
    defer s.Close()

    testSrvAddr = "http://" + s.Listener.Addr().String()
    fmt.Println("server addr:", testSrvAddr)

    m.Run()
}

func TestNewEchoServer(t *testing.T) {
    // can direct request the echo server
    r, err := http.Post(testSrvAddr, "text/plain", strings.NewReader("hello!"))
    assert.NoErr(t, err)

    // binding response to the testutil.EchoReply
    rr := testutil.ParseRespToReply(r)
    dump.P(rr)
    assert.Eq(t, "POST", rr.Method)
    assert.Eq(t, "text/plain", rr.ContentType())
    assert.Eq(t, "hello!", rr.Body)
}

v0.6.9 change log

Full changelog v0.6.8...v0.6.9

✨ New features

strutil - Added ToByteSize(),SafeByteSize() for converting size string (eg: 5MB) to byte size
strutil has added ParseSizeRange() to facilitate and quickly parse string size range expressions eg: 200kb~50mb
strutil - Added new utility functions: DatetimeNo(), RandWithTpl(), SimpleMatch()
byteutil - Add new utility functions: Random(), AppendAny()
fsutil - Add new utility functions: ReadOrErr(), ReadStringOrErr()
cliutil - Add new utility functions: Confirm(), ReadAsBool()
errorx - Add new utility functions Err(), Errf() for easy creation of error
structs - InitDefaults() enhanced to support nested structure pointer initialization
structs - SetValues() enhanced to support setting and processing structure pointer values
structs - Add ToSMap(), TryToSMap(), TryToSMap() to convert structure to string map
testutil/assert new assertion methods NotContainsKey(), NotContainsKeys()
Reflects new utility methods UnexportedValue(), SetUnexportedValue()
maputil new tool functions HasOneKey(), CombineToMap(), TryAnyMap()
Added utility functions AnyToSlice(), CombineToMap() in arrutil
jsonutil has added tool methods IsJSON(), IsJSONFast() to check whether it is JSON
♻️ fsutil/finder file and directory search reconstruction, enhanced functions, more convenient to use
timex new utility functions NowAddSec(), IsDuration(), InRange()
timex ToDuration() enhanced, support unit d, w and long unit hour, min, sec
mathutil new tool methods InRange(), OutRange(), InUintRange()
fsutil new tool method RemoveSub() to quickly delete subdirectories and files
maputil GetByPath() is enhanced to support matching paths similar to top.*.field to get values

👔 Update adjustments

strutil optimization ToByteSize() and GlobMatch() logic
struts - InitDefaults() supports initializing non-zero ptr substructure fields
💥 struts - InitDefaults() To initialize a substructure, the field must be marked with default:""

Other adjustments

📝 doc: README documentation updated, some subpackages added README
✅ test: Added and fixed some unit tests
⬆️ dep: update golang.org/x dependencies to latest version

Some feature usage examples

finder - find files or dir

fsutil/finder Provides a simple and fast way to find matching files and directories.

Built-in support Name, extension, suffix, prefix, glob, path, etc. include or exclude
Support matching file size, modification time (ModTime) and other extended matching methods

ff := finder.NewFinder("/path/to/dir/").
    // OnlyFindDir(). // default find files
    UseAbsPath().
    WithoutDotDir().
    WithDirName("testdata").
    Include(finder.HumanModTime("<10m")). // latest 10 minutes, to Now
    Include(finder.HumanSize("500kb~10mb")) // limit file size

// Find() returns chan, can be for handling
for el := range f.Find() {
    fmt.Println(el.Path())
}

strutil.ParseSizeRange

It is easy to parse the string size range to byte size.

opt := &strutil.ParseSizeOpt{}

mix, max, err := strutil.ParseSizeRange("1kb~1mb", opt)
goutil.PanicErr(err)
fmt.Println(min, max) // OUTPUT: 1024, 1048576

Examples of supported expression formats:

"1KB~2MB"       => 1KB to 2MB
"-1KB"          => <1KB
"~1MB"          => <1MB
"< 1KB"         => <1KB
"1KB"           => >1KB
"1KB~"          => >1KB
">1KB"          => >1KB
"+1KB"          => >1KB

timex.ParseRange()

timex.ParseRange() It is easy to quickly parse the relative time size range or keyword into time.Time

start, end, err := ParseRange("-1h~1h", nil)
goutil.PanicErr(err)


fmt.Println(start, end)

Examples of supported expression formats:

"-5h~-1h"           => 5 hours ago to 1 hour ago
"1h~5h"             => 1 hour after to 5 hours after
"-1h~1h"            => 1 hour ago to 1 hour after
"-1h"               => 1 hour ago to feature. eq "-1h~"
"-1h~0"             => 1 hour ago to now.
"< -1h" OR "~-1h"   => 1 hour ago.
"> 1h" OR "1h"      => 1 hour after to feature

// keyword: now, today, yesterday, tomorrow
"today"          => today start to today end
"yesterday"      => yesterday start to yesterday end
"tomorrow"       => tomorrow start to tomorrow end

More usage

For more instructions, see Unit tests for README and related methods

Github: https://github.com/gookit/goutil

gookit/slog - release v0.5.2, Lightweight, configurable, extensible logging library

Inhere — Tue, 20 Jun 2023 08:10:20 +0000

gookit/slog 📑 Lightweight, configurable, extensible logging library written in Go.
Support multi level, multi outputs and built-in multi file logger, buffers, clean, rotate-file handling.

Github https://github.com/gookit/slog

v0.5.2 changelog

Full changelog: https://github.com/gookit/slog/compare/v0.5.1...v0.5.2

Feature

✨ feat: Add new option FilePerm to customize the permission on log file creation. issues #102 https://github.com/gookit/slog/commit/699ecd8bc2dea0fb35607ba89d4299e86f96e40b
✨ feat: rotatefile - Added new option ModeCreate to support creating log files at rotation time. https://github.com/gookit/slog/commit/8c4a9a08a9b3432a699f6770b73935ecfd42e5b8

Update

👔 up: Update and add more unit tests, upgrade goutil to v0.6.10 https://github.com/gookit/slog/commit/693cc04eb0e375183357be18893cbecaa171ffa1
📝 doc: Update README document description https://github.com/gookit/slog/commit/cbf77c38db5615a9a7ec8ab07853b2f9e3517bfa
✅ test: Add more unit test cases https://github.com/gookit/slog/commit/8468ea470645bb981fb34002176671bac1a9559e

New feature usage

Custom log file permissions

The log file permission flag created by configuring the FilePerm setting of hander.Config.

h1 := handler.MustFileHandler("/tmp/error.log",
    handler.WithLogLevels(slog.DangerLevels),
    handler.WithFilePerm(0644), // <- sets log file permissions
)

slog.PushHandler(h1)

Split files using ModeCreate mode

about RotateMode:

ModeRename By default, every time rename handles rotation.
ModeCreate Create files only by split time

Setting RotateMode=ModeCreate allows log files to be created only by split time.

h1 := handler.MustRotateFile(
    "/tmp/error.log",
    rotatefile.EveryHour, // split by hour
    handler.WithLogLevels(slog.DangerLevels),
    handler.WithRotateMode(rotatefile.ModeCreate), // set RotateMode=ModeCreate
)

slog.PushHandler(h1)

Configure the logfile as /tmp/error.log in the above example. When set to ModeCreate mode, the file will not actually be created,
Instead, it will be created according to the actual split time:

/tmp/error.log.20230618_1500
/tmp/error.log.20230618_1600
/tmp/error.log.20230618_1700
...

Tips: The ModeCreate mode can be applied to command-line tool applications. Because they exit after each execution, ModeRename may not be able to split files on time.

And using ModeRename mode will have the following effect:

/tmp/error.log # <- Logs are always written to this file
/tmp/error.log.20230618_1500
/tmp/error.log.20230618_1600
/tmp/error.log.20230618_1700
...

More usage

GO tool library goutil released v0.6.4

Inhere — Sun, 12 Feb 2023 03:52:39 +0000

gookit/goutil - 💪 Helper Utils For Go: int, byte, string, array/slice, map, struct, dump, convert/format, error, web/http, cli/flag, OS/ENV, filesystem, system, test/assert, time and more.

GitHub: https://github.com/gookit/goutil

Changlog from v0.6.2 to v0.6.4

Fixed

🐛 fix(env, str): fix the envutil test error and update some str util 2e7aa63
🐛 fix(dump): makeslice: cap out of range. fix: #76 4ba9b10

Feature

👔 feat: str - add some check util func 0e4792a
👔 feat: str/textutil - support quick replace vars for give text ecc23cb
👔 feat: sys,proc - add and update some util func aa78114
✨ feat: fs - add more new fs util functions 3352512
✨ feat: map, struct - add new util functions 90af09e
✨ feat: stdio - add new util functions ea243d6
✨ feat: arr - add new util functions for in/notIn check 2a18ca2
✨ feat: testutil - add new util func IsMatchAll() d0dade8
✨ feat: math - add new util func for compare value 176923b
feat: error, test - add some new helper util fuctions 7188216
✨ feat: fs - add more make dir util func c4447cb
✨ feat: env,sys - add new func for get all env info map b3d7669
✨ feat: str - add new func for check ignore case string 746eb35
✨ feat: goutil - add new func for quick run go func 97a2863
✨ feat: arr - add new func for quick convert slice type 75d8d89
✨ feat: reflects - add new func for convert slice value and more util f87fc86
✨ feat: structs - func InitDefaults() support set slice field 948fa70
✨ feat: byte - add StrOrErr(), SafeString() for convert to string 767ed80
✨ feat: cmdr - add new option for output result to OS 6aaea78

Update

👔 up: str, math - add new util func OrElse() cb21fbc
👔 up: str - update some util func and add more tests a3e07f4
🐛 up: textscan - fix multi inline comments parse error bf68c94
👔 up: str,math - update some util func eaf0990
👔 up: str,byte - add and update some util func cf5d34e
👔 up: byte,cflag - update and add some new tests 6e47f69
👔 up(env, str): update the env var parse and strutil.Valid() 5193849
👔 up(str): update some str value get func 676fe4e
✨ up(env,sys): update some func and add new util func 9eaddb5
👔 up(str): update the SplitInlineComment() logic 31445cd
👔 up(sys): update the SearchPath(), support limit result 67cbae1
✅ up(sys,env,map): add more tests case for util func 392536c
👔 up(fs,sys): update some fs and sys util func run logic 7727628
👔 up(struct): update some structs comments and update readme f461852
👔 up(str): update some string util comments and func 796d1fe

Other

build(deps): bump golang.org/x/text from 0.5.0 to 0.6.0 79d7781
doc: re-generate the README docs 42e3084
doc: update the doc parse logic, support generic types 030676d
doc: generate and update README docs f342e92
build(deps): bump golang.org/x/text from 0.6.0 to 0.7.0 1e3ea77

GitHub: https://github.com/gookit/goutil

Lightweight event management, dispatch tool library implemented by Go

Inhere — Thu, 07 Jul 2022 14:37:14 +0000

event - Lightweight event management, dispatch tool library implemented by Go

Support for custom definition event objects
Support for adding multiple listeners to an event
Supports setting the priority of the event listener. The higher the priority, the higher the trigger.
Support for a set of event listeners based on the event name prefix PREFIX.*.
- add app.* event listen, trigger app.run app.end, Both will trigger the app.* event at the same time
Support for using the wildcard * to listen for triggers for all events
Complete unit testing, unit coverage > 95%

Repo and doc

Github: https://github.com/gookit/event
Godoc for github

Install

go install github.com/gookit/event

Quick start

package main

import (
    "fmt"

    "github.com/gookit/event"
)

func main() {
    // Register event listener
    event.On("evt1", event.ListenerFunc(func(e event.Event) error {
        fmt.Printf("handle event: %s\n", e.Name())
        return nil
    }), event.Normal)

    // Register multiple listeners
    event.On("evt1", event.ListenerFunc(func(e event.Event) error {
        fmt.Printf("handle event: %s\n", e.Name())
        return nil
    }), event.High)

    // ... ...

    // Trigger event
    // Note: The second listener has a higher priority, so it will be executed first.
    event.MustFire("evt1", event.M{"arg0": "val0", "arg1": "val1"})
}

Note: The second listener has a higher priority, so it will be executed first.

Using the wildcard

func main() {
    dbListener1 := event.ListenerFunc(func(e event.Event) error {
        fmt.Printf("handle event: %s\n", e.Name())
        return nil
    })

    event.On("app.db.*", dbListener1, event.Normal)
}

Trigger events on other logic:

func doCreate() {
    // do something ...
    // Trigger event
    event.MustFire("app.db.create", event.M{"arg0": "val0", "arg1": "val1"})
}

func doUpdate() {
    // do something ...
    // Trigger event
    event.MustFire("app.db.update", event.M{"arg0": "val0"})
}

Like the above, triggering the app.db.create app.db.update event
will trigger the execution of the dbListener1 listener.

Write event listeners

Using anonymous functions

You can use anonymous function for quick write an event lister.

package mypgk

import (
    "fmt"

    "github.com/gookit/event"
)

var fnHandler = func(e event.Event) error {
    fmt.Printf("handle event: %s\n", e.Name())
    return nil
}

func Run() {
    // register
    event.On("evt1", event.ListenerFunc(fnHandler), event.High)
}

Using the structure method

You can use struct write an event lister, and it should implementation interface event.Listener.

interface:

// Listener interface
type Listener interface {
    Handle(e Event) error
}

example:

Implementation interface event.Listener

package mypgk

import "github.com/gookit/event"

type MyListener struct {
    // userData string
}

func (l *MyListener) Handle(e event.Event) error {
    e.Set("result", "OK")
    return nil
}

Register multiple event listeners

Can implementation interface event.Subscriber for register
multiple event listeners at once.

interface:

// Subscriber event subscriber interface.
// you can register multi event listeners in a struct func.
type Subscriber interface {
    // SubscribedEvents register event listeners
    // key: is event name
    // value: can be Listener or ListenerItem interface
    SubscribedEvents() map[string]interface{}
}

example

Implementation interface event.Subscriber

package mypgk

import (
    "fmt"

    "github.com/gookit/event"
)

type MySubscriber struct {
    // ooo
}

func (s *MySubscriber) SubscribedEvents() map[string]interface{} {
    return map[string]interface{}{
        "e1": event.ListenerFunc(s.e1Handler),
        "e2": event.ListenerItem{
            Priority: event.AboveNormal,
            Listener: event.ListenerFunc(func(e Event) error {
                return fmt.Errorf("an error")
            }),
        },
        "e3": &MyListener{},
    }
}

func (s *MySubscriber) e1Handler(e event.Event) error {
    e.Set("e1-key", "val1")
    return nil
}

Write custom events

If you want to customize the event object or define some fixed event information in advance,
you can implement the event.Event interface.

interface:

// Event interface
type Event interface {
    Name() string
    // Target() interface{}
    Get(key string) interface{}
    Add(key string, val interface{})
    Set(key string, val interface{})
    Data() map[string]interface{}
    SetData(M) Event
    Abort(bool)
    IsAborted() bool
}

examples:

package mypgk

import "github.com/gookit/event"

type MyEvent struct {
    event.BasicEvent
    customData string
}

func (e *MyEvent) CustomData() string {
    return e.customData
}

Usage:

e := &MyEvent{customData: "hello"}
e.SetName("e1")
event.AddEvent(e)

// add listener
event.On("e1", event.ListenerFunc(func(e event.Event) error {
    fmt.Printf("custom Data: %s\n", e.(*MyEvent).CustomData())
    return nil
}))

// trigger
event.Fire("e1", nil)
// OR
// event.FireEvent(e)

Main method

On/Listen(name string, listener Listener, priority ...int) Register event listener
Subscribe/AddSubscriber(sbr Subscriber) Subscribe to support registration of multiple event listeners
Trigger/Fire(name string, params M) (error, Event) Trigger event by name and params
MustTrigger/MustFire(name string, params M) Event Trigger event, there will be panic if there is an error
FireEvent(e Event) (err error) Trigger an event based on a given event instance
FireBatch(es ...interface{}) (ers []error) Trigger multiple events at once
AsyncFire(e Event) Async fire event by 'go' keywords

slog - Lightweight, configurable, extensible Go logging library

Inhere — Thu, 16 Jun 2022 02:33:47 +0000

slog is a lightweight, configurable, extensible Go logging library.

Features

Simple, directly available without configuration
Support common log level processing.
- eg: trace debug info notice warn error fatal panic
Support any extension of Handler Formatter as needed
Supports adding multiple Handler log processing at the same time, outputting logs to different places
Support to custom log message Formatter
- Built-in json text two log record formatting Formatter
Support to custom build log messages Handler
- The built-in handler.Config handler.Builder can easily and quickly build the desired log handler
Has built-in common log write handler program
- console output logs to the console, supports color output
- writer output logs to the specified io.Writer
- file output log to the specified file, optionally enable buffer to buffer writes
- simple output log to the specified file, write directly to the file without buffering
- rotate_file outputs logs to the specified file, and supports splitting files by time and size, and buffer buffered writing is enabled by default
- See ./handler folder for more built-in implementations

Output logs to file

Support enabling buffer for log writing
Support splitting log files by time and size
Support configuration to compress log files via gzip
Support clean old log files by BackupNum BackupTime

Git repository

Github: https://github.com/gookit/slog

Install

go get github.com/gookit/slog

Quick start

package main

import (
    "github.com/gookit/slog"
)

func main() {
    slog.Trace("this is a log message")
    slog.Debug("this is a log message")
    slog.Info("this is a log message")
    slog.Notice("this is a log message")
    slog.Warn("this is a log message")
    slog.Error("this is a log message")
    slog.Fatal("this is a log message")
}

output preview:

Logs to file

Using slog to output logs to files is very convenient, and supports multiple files, splitting by time, etc.

package main

import (
    "github.com/gookit/slog"
    "github.com/gookit/slog/handler"
    "github.com/gookit/slog/rotatefile"
)

func main() {
    defer slog.MustFlush()

    // DangerLevels contains: slog.PanicLevel, slog.ErrorLevel, slog.WarnLevel
    h1 := handler.MustRotateFile("/tmp/logs/app_error.log", rotatefile.EveryHour, 
        handler.WithLogLevels(slog.DangerLevels),
    )

    // NormalLevels contains: slog.InfoLevel, slog.NoticeLevel, slog.DebugLevel, slog.TraceLevel
    h2 := handler.MustRotateFile("/tmp/logs/app_info.log", rotatefile.EveryHour,
        handler.WithLogLevels(slog.NormalLevels),
    )

    slog.PushHandler(h1)
    slog.PushHandler(h2)

    // add logs
    slog.Info("info message text")
    slog.Error("error message text")
}

See logs dir:

$ ls /tmp/logs
app_error.log
app_info.log

More usage

More usage please see README

gookit/goutil - Useful utils package for the Go

Inhere — Mon, 13 Jun 2022 07:40:15 +0000

gookit/goutil 💪 Useful utils package for the Go: int, string, array/slice, map, error, time, format, CLI, ENV, filesystem, system, testing and more.

Sub-packages

arrutil: Array/Slice util functions. eg: check, convert, formatting
dump: Simple variable printing tool, printing slice, map will automatically wrap each element and display the call location
cliutil Command-line util functions. eg: read input, exec command, cmdline parse/build
errorx Provide an enhanced error implements for go, allow with stacktraces and wrap another error.
envutil ENV util for current runtime env information. eg: get one, get info, parse var
fmtutil Format data util functions. eg: data, size
fsutil Filesystem util functions, quick create, read and write file. eg: file and dir check, operate
jsonutil some util functions for quick read, write, encode, decode JSON data.
maputil Map data util functions. eg: convert, sub-value get, simple merge
mathutilMath(int, number) util functions. eg: convert, math calc, random
netutil Network util functions
- netutil/httpreq An easier-to-use HTTP client that wraps http.Client
strutil String util functions. eg: bytes, check, convert, encode, format and more
sysutil System util functions. eg: sysenv, exec, user, process
testutil Test help util functions. eg: http test, mock ENV value
timex Provides an enhanced time.Time implementation. Add more commonly used functional methods
- such as: DayStart(), DayAfter(), DayAgo(), DateFormat() and more.

Git repository

Github: https://github.com/gookit/goutil
Gitee: https://gitee.com/gookit/goutil

Install

go get github.com/gookit/goutil

Usage

goutil/dump

goutil/dump is a golang data printing toolkit that prints beautiful and easy to read go slice, map, struct data.

Examples

//  go run ./dump/_examples/struct.go
func main() {
    s1 := &struct {
        cannotExport map[string]interface{}
    }{
        cannotExport: map[string]interface{}{
            "key1": 12,
            "key2": "abcd123",
        },
    }

    s2 := struct {
        ab string
        Cd int
    }{
        "ab", 23,
    }

    color.Infoln("- Use fmt.Println:")
    fmt.Println(s1, s2)

    color.Infoln("\n- Use dump.Println:")
    dump.P(s1,s2)
}

Output:

goutil/timex

goutil/timex Provides an enhanced time.Time implementation, and add more commonly used functional methods.

such as: DayStart(), DayAfter(), DayAgo(), DateFormat() and more

Create timex instance:

now := timex.Now()

// from time.Time
tx := timex.New(time.Now())
tx := timex.FromTime(time.Now())

// from time unix
tx := timex.FromUnix(1647411580)

Create time for date string:

// auto match layout by datetime
tx, err  := timex.FromString("2022-04-20 19:40:34")
// custom set the datetime layout
tx, err  := timex.FromString("2022-04-20 19:40:34", "2006-01-02 15:04:05")
// use date template as layout
tx, err  := timex.FromDate("2022-04-20 19:40:34", "Y-m-d H:I:S")

Quickly fetch time:

tx := timex.Now()

tx.Yesterday()
tx.Tomorrow()

tx.DayStart() // get time at Y-m-d 00:00:00
tx.DayEnd() // get time at Y-m-d 23:59:59
tx.HourStart() // get time at Y-m-d H:00:00
tx.HourEnd() // get time at Y-m-d H:59:59

tx.AddDay(2)
tx.AddHour(1)
tx.AddMinutes(15)
tx.AddSeconds(120)

Quickly format date：

tx.DateFormat("y/m/d H:I")
date := tx.DateFormat("Y-m-d H:I:S") // Output: 2022-04-20 19:40:34
date = tx.DateFormat("y-m-d H:I:S") // Output: 22-04-20 19:40:34

More usage

More utils and usage please see README https://github.com/gookit/goutil/blob/master/README.md

DEV Community: Inhere

How my Go coding agent keeps a turn-1 constraint across 3 context resets

A session that lasts all day: the hard part is the context reset

Every token is accounted for: fixed prefix, tool descriptions, lazy loading

When something breaks, you can find out why: a thinking-signature bug

Safe by default, and "tests pass" comes from a command, not the model

Working with gofer: how suga gets built

The core embeds in other Go programs

Compared with similar tools

Up and running in 30 seconds

If you read the code, start in these four places

miglite v0.8.0: ship migrations inside the binary

What changed across these releases

Ship migrations inside the binary

--db points one command at another database

exec runs multi-statement SQL in one transaction

Four behaviours that only looked right

Using miglite as a library

Should you upgrade

eget: install GitHub releases without waiting for a central index

Start with a GitHub repository

The repository is the entry point

It is not limited to GitHub

Internal tools can use one reusable rule

Keep frequently used tools in config

Update tools

SDK downloads are built in

Cache mirrors help on team machines

More features are in the GitHub docs

Where eget fits

gookit/gcli v3.5.0 released - easy-to-use, feature-rich Go command line application and tool library

GCli v3.5 Updates: Changes Since v3.3.1

Key Updates

1. Shell Completion Improvements

2. Command Middleware

3. Grouped Help

4. More Flexible Struct Binding

5. Declarative Interactive Input

6. POSIX Short-Option Merging

7. Robustness Fixes

Breaking Changes & Migration

Upgrade & Examples

gookit/goutil v0.7.2 Released: Enhanced Features & Fixes for an Improved Development Experience

🛠️ Key Bug Fixes

✨ New Feature Highlights

Math Utilities

String Utilities

Filesystem Utilities

Array/Slice Utilities

Map Utilities

Testing Utilities

Command-line Utilities

Time Utilities

⚡ Performance Optimizations & Refactoring

🌐 Platform Compatibility & Development Workflow

📝 Other Updates

📦 How to Update

Migration & Compatibility Notes

Example Snippets

Using mathutil.IsInteger / StrictInt

Using strutil.ReplaceVars

Using fsutil.EnsureDir

🤝 Contributing

📖 More Information

gookit/slog - release v0.5.8, Lightweight, configurable, extensible logging library

Highlights of v0.5.8

🛠️ Bug Fixes

✨ New Features

🔄 Updates and Improvements

📦 Dependency Updates

🧪 Improved Test Coverage

Acknowledging New Contributors

Full Changelog

gookit/goutil - released v0.6.10, an extension library of common Go features

v0.6.10 change log

✨ New features

👔 Update Adjustments

Other adjustments

Some feature usage examples

dump - prints custom types

Using `mathutil.IsInteger / StrictInt`

Using `strutil.ReplaceVars`

Using `fsutil.EnsureDir`