DEV Community: Nobuo Miura

Rust CheatSheet

Nobuo Miura — Mon, 24 Aug 2026 14:21:07 +0000

This cheat sheet is based on Rust 1.98 and the Rust 2024 Edition.

Installation and updates
Program structure
Variables, constants, and primitive types
Ownership, borrowing, and slices
Control flow
Functions and closures
Structs, unions, enums, and patterns
Collections and strings
Error handling
Generics, traits, and lifetimes
Iterators
Smart pointers
Modules, packages, and visibility
Concurrency
Macros and attributes
Testing
Standard-library quick reference
Calling external functions: extern and FFI
unsafe Rust
Cargo and dependency management
Tips and common mistakes
Official references

Installation and updates

The recommended way to manage a Rust toolchain is with the official rustup tool. On macOS, Linux, WSL, and other Unix-like systems, run the command published on the official website and follow the prompts:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, download and run rustup-init.exe from the official installation page. Depending on your environment, you may also need the Visual Studio C++ Build Tools.

Restart your terminal after installation, then check the installed versions:

rustc --version
cargo --version
rustup --version

Update the stable toolchain and install the formatter and linter with:

rustup update stable
rustup component add rustfmt clippy

If an existing project contains rust-toolchain.toml or rust-toolchain, follow that project-level toolchain declaration. Libraries can declare their minimum supported Rust version (MSRV) with rust-version in Cargo.toml.

Program structure

fn main() {
    println!("Hello, Rust 1.98!");
}

An executable starts at the main function.
Statements usually end with ;.
A name ending in !, such as println!, is a macro invocation.

Comments

Syntax	Purpose
`// ...`	Regular comment through the end of the line
`/* ... */`	Regular block comment; block comments can be nested
`/// ...`, `/** ... */`	Outer documentation comment for the following item
`//! ...`, `/! ... /`	Inner documentation comment for the containing crate or module

// A line comment
let value = 42;

/* A block comment can
   span multiple lines. */
assert_eq!(value, 42);

Documentation comments are parsed as Markdown and included in the API documentation generated by cargo doc. Their code blocks are normally run as documentation tests by cargo test.

mod math {
    //! Basic arithmetic helpers.

    /// Adds two integers.
    ///
    /// # Examples
    ///
    /// ```
{% endraw %}

    /// assert_eq!(2 + 3, 5);
    ///
{% raw %}

pub fn add(left: i32, right: i32) -> i32 {
    left + right
}

}

assert_eq!(math::add(2, 3), 5);




Create and run a Cargo project with:



```bash
cargo new hello-rust
cd hello-rust
cargo run

New Cargo projects use edition = "2024" in Cargo.toml.

Keywords

The Rust Reference: Keywords

Rust divides keywords into strict keywords, reserved keywords kept for future language features, and weak keywords that are special only in specific contexts.

Strict keywords

Keyword	Primary use
`_`	Ignore a value in a pattern, or ask the compiler to infer a type or value
`as`	Primitive casts, aliases in `use`, and qualified paths
`async`	Define a function, block, or closure that produces a `Future`
`await`	Suspend the current async computation until a `Future` is ready
`break`	Exit a loop, optionally returning a value
`const`	Declare compile-time constants, const functions, blocks, or generics
`continue`	Skip the rest of the current loop iteration
`crate`	Refer to the current crate or its root
`dyn`	Form a dynamically dispatched trait object
`else`	Handle the branch where an `if` or `if let` condition does not match
`enum`	Define a type with multiple variants
`extern`	Work with external ABIs, functions, statics, or crates
`false`	The false `bool` literal
`fn`	Define a function or function-pointer type
`for`	Iterate over a value or implement a trait for a type
`if`	Branch on a Boolean condition
`impl`	Define inherent methods or implement a trait
`in`	Specify the value iterated by a `for` loop
`let`	Bind a value to a pattern
`loop`	Repeat until explicitly stopped
`match`	Perform exhaustive pattern matching
`mod`	Declare or define a module
`move`	Move captured values into a closure or async block
`mut`	Make a binding, reference, or pattern mutable
`pub`	Expose an item outside its default visibility boundary
`ref`	Bind by reference inside a pattern
`return`	Return from a function early
`self`	Refer to a method receiver or the current module
`Self`	Refer to the type currently being defined or implemented
`static`	Declare an item with a fixed storage location
`struct`	Define a named-field, tuple, or unit struct
`super`	Refer to the parent module
`trait`	Define shared behavior for types
`true`	The true `bool` literal
`type`	Define a type alias or associated type
`unsafe`	Mark operations or contracts the compiler cannot fully verify
`use`	Bring a path into scope or re-export an item
`where`	Write generic and lifetime bounds
`while`	Repeat while a Boolean condition remains true

Reserved keywords

abstract, become, box, do, final, gen, macro, override, priv, try, typeof, unsized, virtual, yield

These are reserved for possible future language features. In Rust 1.98, they have no keyword behavior and cannot be used as ordinary identifiers. In particular, typeof is reserved but is not implemented as a type-inspection operator.

Weak keywords

Keyword	Context in which it is special
`'static`	A lifetime valid for the entire program
`macro_rules`	Declare a declarative macro
`raw`	Create raw pointers with `&raw const` or `&raw mut`
`safe`	Mark a function or static as safe inside an `unsafe extern` block
`union`	Define a type whose fields share storage

When an identifier must match a keyword, a raw identifier such as r#type can be used where the grammar permits it.

Variables, constants, and primitive types

Variable declarations

Bindings are immutable by default. Add mut when the value must change.

let name = "Ferris";       // Inferred as &str.
let age: u32 = 10;         // Explicit type.
let mut count = 0;         // Mutable binding.
count += 1;

// Destructure a value with a pattern.
let (x, y) = (10, 20);

// A declaration may omit its initializer if it is definitely initialized before use.
let status: String;
status = String::from("ready");
println!("{status}");

Shadowing

let can declare a new binding with the same name. Unlike mutation, shadowing may also change the type.

let spaces = "   ";
let spaces = spaces.len(); // &str to usize

Constants and statics

const MAX_RETRIES: u32 = 3;
static APPLICATION_NAME: &str = "example";

A const is evaluated at compile time and requires an explicit type.
A static has a fixed memory address for the duration of the program.
Accessing mutable static mut state requires unsafe; prefer synchronization primitives where appropriate.

An atomic type works well for a simple counter shared across threads:

use std::sync::atomic::{AtomicU64, Ordering};

static REQUEST_COUNT: AtomicU64 = AtomicU64::new(0);

fn next_request_count() -> u64 {
    REQUEST_COUNT.fetch_add(1, Ordering::Relaxed) + 1
}

assert_eq!(next_request_count(), 1);
assert_eq!(next_request_count(), 2);

Relaxed is appropriate here because only the atomicity of the counter matters; this counter does not synchronize the ordering of other memory accesses. Choose an ordering or a lock that matches the actual synchronization requirements.

Values and literals

Literals are values written directly in source code. Numeric literals may have a type suffix, and _ can be used as a visual separator.

let integer = 42;              // i32
let unsigned = 42_u64;         // u64
let floating = 3.14_f32;       // f32
let enabled = true;            // bool
let character = 'R';           // char
let text = "Rust";             // &str
let byte = b'R';               // u8
let bytes = b"Rust";           // &[u8; 4]
let raw = r#"A raw string does not escape \"#;
let million = 1_000_000;

assert_eq!(integer, 42);
assert_eq!(bytes, &[82, 117, 115, 116]);
assert!(raw.contains('\\'));
assert_eq!(million, 1_000_000);

Values can also be produced by calls such as String::from("Rust") and by expressions such as left + right. Many Rust constructs are expressions: blocks, if, match, and loop can all produce values.

Scalar types

Category	Types	Notes
Signed integers	`i8`, `i16`, `i32`, `i64`, `i128`, `isize`	Integer literals default to `i32`
Unsigned integers	`u8`, `u16`, `u32`, `u64`, `u128`, `usize`	`usize` is commonly used for sizes and indexes
Floating point	`f32`, `f64`	Defaults to `f64`
Boolean	`bool`	`true` or `false`
Character	`char`	A four-byte Unicode scalar value
Unit	`()`	Represents the absence of another meaningful value

let decimal = 98_222;
let hex = 0xff;
let octal = 0o77;
let binary = 0b1111_0000;
let byte = b'A';
let ratio = 3.5_f64;
let enabled = true;
let crab = '🦀';

Debug builds detect integer overflow at runtime. Use explicit methods when wraparound or saturation is intentional.

let value = u8::MAX;
assert_eq!(value.wrapping_add(1), 0);
assert_eq!(value.saturating_add(1), u8::MAX);
assert_eq!(value.checked_add(1), None);

Compound types

// A tuple can contain values of different types.
let user = ("Ferris", 10, true);
let (name, age, active) = user;
println!("{name}: {age}, active={active}");

// An array has a fixed length that is part of its type.
let numbers: [i32; 3] = [10, 20, 30];
let zeros = [0; 5];
println!("{} {}", numbers[0], zeros.len());

Array indexing with [] panics when the index is out of bounds. Use get when absence is possible.

let values = [10, 20, 30];
match values.get(5) {
    Some(value) => println!("{value}"),
    None => println!("out of bounds"),
}

Type conversion

Rust does not perform implicit numeric conversion. Use as, From, or TryFrom explicitly.

let small: u8 = 42;
let large = u32::from(small); // Lossless conversion.

let integer = 42_i32;
let floating = integer as f64;
assert_eq!(floating, 42.0);

let value: i32 = 300;
let byte = u8::try_from(value); // Result<u8, TryFromIntError>
assert!(byte.is_err());

assert_eq!(char::from_u32(65), Some('A'));

as can truncate a value. Prefer TryFrom when the input range is not guaranteed.

let value = 300_u16;
assert_eq!(value as u8, 44);
assert!(u8::try_from(value).is_err());

Type aliases and newtypes

A type alias gives an existing type another name; it does not create a distinct type.

type UserId = u64;
type IoResult<T> = Result<T, std::io::Error>;

fn load_user(id: UserId) -> IoResult<String> {
    Ok(format!("user-{id}"))
}

let id: UserId = 42;
let raw_id: u64 = id;
assert_eq!(load_user(raw_id).unwrap(), "user-42");

Use the newtype pattern when values must not be mixed accidentally.

struct UserId(u64);
struct ProductId(u64);

fn find_user(id: UserId) {
    println!("user={}", id.0);
}

find_user(UserId(42));
// find_user(ProductId(42)); // Different type: does not compile.

Inspecting a type

Rust has no built-in typeof operator. Use std::any::type_name::<T>() for a known type or std::any::type_name_of_val for a value.

fn type_of<T: ?Sized>(_: &T) -> &'static str {
    std::any::type_name::<T>()
}

let number = 123;
println!("{}", type_of(&number));
println!("{}", std::any::type_name_of_val(&number));

A helper that accepts its argument by value also works:

fn type_of<T>(_: T) -> &'static str {
    std::any::type_name::<T>()
}

let number = 123;
println!("{}", type_of(number));

The by-value version moves non-Copy values such as String, so the borrowed form is usually more convenient. The exact output of type_name is not guaranteed and may change between compiler versions. Use it for diagnostics, not as a stable type identifier or application branching key.

Operators

Category	Operators	Notes
Arithmetic	`+`, `-`, `*`, `/`, `%`	Integer division discards the fractional part
Unary	`-`, `!`	Numeric negation; Boolean negation or integer bitwise complement
Comparison	`==`, `!=`, `<`, `<=`, `>`, `>=`	Uses traits such as `PartialEq` and `PartialOrd`
Logical	`&&`, `\	\
Bitwise	{% raw %}`&`, `\	`,` ^`,` <<`,` >>`
Assignment	`=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `\	=`,` ^=`,` <<=`,` >>=`
Range	`..`, `..=`	Exclusive and inclusive upper bounds
Borrow and dereference	`&`, `&mut`, `*`	Create references and access their targets
Error propagation	`?`	Return early from `Result`, `Option`, and similar types

assert_eq!(7 / 2, 3);
assert_eq!(7.0 / 2.0, 3.5);
assert_eq!(-5_i32, 0 - 5);
assert_eq!(!true, false);

let mut value = 5;
value *= 2;
assert_eq!(value, 10);

let mut flags = 0b0011_u8;
flags |= 0b0100;
flags <<= 1;
assert_eq!(flags, 0b1110);

assert!((1..=10).contains(&value));

User-defined types can support operators by implementing standard traits such as Add, PartialEq, and Index. Rust does not allow arbitrary new operators or custom operator precedence.

Ownership, borrowing, and slices

Rust manages memory without a garbage collector by checking ownership rules at compile time.

Ownership

The three core rules are:

Every value has an owner.
A value has only one owner at a time.
The value is dropped when its owner leaves scope.

let original = String::from("hello");
let moved = original; // Ownership moves to moved.

println!("{moved}");
// println!("{original}"); // Error: original was moved.

Types that implement Copy, such as i32, are copied on assignment.

let x = 5;
let y = x;
println!("{x} {y}");

Use clone when an independent copy of heap-owned data is actually needed.

let original = String::from("hello");
let cloned = original.clone();
println!("{original} {cloned}");

Borrowing and references

A reference borrows a value without taking ownership.

fn length(text: &str) -> usize {
    text.len()
}

let message = String::from("hello");
let size = length(&message);
println!("{message}: {size}");

The main borrowing rules are:

Any number of shared references &T, or one mutable reference &mut T, may be active.
Shared and mutable references to the same value cannot be active at the same time.
A reference must always point to a valid value.

fn append_world(text: &mut String) {
    text.push_str(", world");
}

let mut message = String::from("hello");
append_world(&mut message);
println!("{message}");

Slices

A slice borrows a contiguous portion of a collection without owning the data.

let numbers = [10, 20, 30, 40];
let middle: &[i32] = &numbers[1..3];
assert_eq!(middle, &[20, 30]);

let text = String::from("hello world");
let hello: &str = &text[..5];
assert_eq!(hello, "hello");

String ranges must fall on UTF-8 character boundaries or they panic. Use chars for Unicode scalar values and bytes for bytes.

let text = "日本語";
let characters: Vec<char> = text.chars().collect();
assert_eq!(characters, vec!['日', '本', '語']);
assert_eq!(text.len(), 9);          // UTF-8 bytes
assert_eq!(text.chars().count(), 3); // Unicode scalar values

Lifetime overview

Lifetimes describe how long references remain valid. The compiler infers them in most code.

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() >= y.len() { x } else { y }
}

'a says that the returned reference cannot outlive the shorter-lived input reference. It does not extend the lifetime of either value. A string literal has the 'static lifetime because its data is available for the entire program.

Control flow

`if`, `if let`, and `let else`

if is an expression, so it can produce a value. Its condition must be a bool.

let score = 80;
let grade = if score >= 80 { "A" } else { "B" };

let name = Some("Ferris");
if let Some(value) = name {
    println!("{value}");
}

fn print_name(name: Option<&str>) {
    let Some(name) = name else {
        println!("No name was provided");
        return;
    };
    println!("{name}");
}

`loop`, `while`, and `for`

let mut count = 0;
let result = loop {
    count += 1;
    if count == 3 {
        break count * 10; // break can return a value from loop.
    }
};
assert_eq!(result, 30);

while count > 0 {
    count -= 1;
}

for value in [10, 20, 30] {
    println!("{value}");
}

for number in 1..=5 {
    if number % 2 == 0 {
        continue;
    }
    println!("odd: {number}");
}

for calls into_iter. Passing a collection by value may consume it.

let mut names = vec![String::from("Alice"), String::from("Bob")];

for name in &names {        // iter(): &String
    println!("{name}");
}
for name in &mut names {    // iter_mut(): &mut String
    name.push('!');
}
assert_eq!(names, vec!["Alice!", "Bob!"]);

// for name in names { }    // into_iter(): String; consumes names.

Loop labels

'outer: for x in 0..3 {
    for y in 0..3 {
        if x + y == 3 {
            break 'outer;
        }
    }
}

`match`

match must cover every possible pattern.

let number = 7;

let description = match number {
    0 => "zero",
    1..=9 => "one digit",
    n if n % 2 == 0 => "even",
    _ => "other",
};

println!("{description}");

let point = (0, 5);
match point {
    (0, y) => println!("on the y-axis: {y}"),
    (x, 0) => println!("on the x-axis: {x}"),
    (x, y) => println!("({x}, {y})"),
}

Functions and closures

Function parameter and return types are explicit. The final expression is returned when it has no semicolon.

fn add(left: i32, right: i32) -> i32 {
    left + right
}

fn divide(left: f64, right: f64) -> Option<f64> {
    if right == 0.0 { return None; }
    Some(left / right)
}

let value = { let base = 10; base * 2 };
assert_eq!(value, 20);

Closures can borrow or capture values from their environment. Their types are usually inferred.

let offset = 10;
let add_offset = |value: i32| value + offset;
assert_eq!(add_offset(5), 15);

let message = String::from("hello");
let show = move || println!("{message}");
show();

Closures implement Fn, FnMut, or FnOnce depending on how they use captured values.

fn apply_twice<F>(mut operation: F, value: i32) -> i32
where F: FnMut(i32) -> i32,
{
    let once = operation(value);
    operation(once)
}
assert_eq!(apply_twice(|x| x + 1, 10), 12);

Functions and non-capturing closures can be used as fn pointers.

fn double(value: i32) -> i32 { value * 2 }
fn calculate(operation: fn(i32) -> i32, value: i32) -> i32 { operation(value) }
assert_eq!(calculate(double, 5), 10);

Structs, unions, enums, and patterns

Structs and methods

#[derive(Debug, Clone, PartialEq)]
struct User { name: String, age: u32, active: bool }

let user = User { name: String::from("Ferris"), age: 10, active: true };
let updated = User { age: 11, ..user.clone() };
println!("{updated:?}");

Common derived traits include Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, and Default. Copy cannot be implemented for a type that implements Drop.

struct UserId(u64);          // Tuple struct
struct Point(i32, i32);
struct Marker;               // Unit struct

Methods are defined in impl blocks. &self borrows, &mut self mutably borrows, and self consumes the value.

struct Rectangle { width: u32, height: u32 }

impl Rectangle {
    fn square(size: u32) -> Self { Self { width: size, height: size } }
    fn area(&self) -> u32 { self.width * self.height }
    fn resize(&mut self, width: u32, height: u32) {
        self.width = width; self.height = height;
    }
    fn dimensions(self) -> (u32, u32) { (self.width, self.height) }
}

let mut rectangle = Rectangle::square(10);
rectangle.resize(20, 30);
assert_eq!(rectangle.area(), 600);
assert_eq!(rectangle.dimensions(), (20, 30));

Unions

A union stores all fields in shared storage. It is mainly used for FFI and low-level representations.

#[repr(C)]
union Number { integer: i32, floating: f32 }

let number = Number { integer: 42 };
// SAFETY: number was initialized through integer.
let integer = unsafe { number.integer };
assert_eq!(integer, 42);

Writing a field is safe, but reading is unsafe because the compiler cannot prove that the bits are valid for the selected field. A union does not track an active field. Its fields are restricted to types that do not require ordinary drop glue, references, or wrappers such as ManuallyDrop<T>. Prefer an enum for ordinary safe application data.

Enums and `Option`

Enum variants can hold different shapes of data.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(u8, u8, u8),
}

fn handle(message: Message) {
    match message {
        Message::Quit => println!("quit"),
        Message::Move { x, y } => println!("move to {x}, {y}"),
        Message::Write(text) => println!("{text}"),
        Message::ChangeColor(r, g, b) => println!("rgb({r}, {g}, {b})"),
    }
}
handle(Message::Write(String::from("hello")));

Rust represents optional values with Option<T> rather than null.

fn find_even(values: &[i32]) -> Option<i32> {
    values.iter().copied().find(|value| value % 2 == 0)
}

let value = find_even(&[1, 3, 4, 5]);
assert_eq!(value, Some(4));
assert_eq!(value.map(|n| n * 2), Some(8));
assert_eq!(None::<i32>.unwrap_or(0), 0);

unwrap and expect panic on None. For expected absence, prefer matching, ?, or fallback methods such as unwrap_or.

Collections and strings

`Vec<T>`

let mut values = Vec::with_capacity(4);
values.push(10);
values.extend([20, 30]);
assert_eq!(values[0], 10);              // Panics if out of bounds.
assert_eq!(values.get(1), Some(&20));   // Safe optional access.
assert_eq!(values.pop(), Some(30));

let numbers = vec![1, 2, 3];
let zeros = vec![0; 5];

`String` and `&str`

String owns a growable UTF-8 buffer; &str borrows UTF-8 text. Read-only function parameters generally prefer &str over &String.

let mut message = String::from("Hello");
message.push(',');
message.push_str(" Rust");

fn greet(name: &str) -> String { format!("Hello, {name}!") }
assert_eq!(greet(&message), "Hello, Hello, Rust!");

let first = String::from("Hello");
let second = String::from("Rust");
let joined = format!("{first}, {second}"); // Does not consume either value.
let combined = first + ", " + &second;     // Consumes first.

Maps, sets, and queues

use std::collections::HashMap;

let mut scores = HashMap::new();
scores.insert(String::from("Alice"), 10);
scores.entry(String::from("Carol")).or_insert(0);
*scores.entry(String::from("Alice")).or_insert(0) += 5;

if let Some(score) = scores.get("Alice") { println!("{score}"); }
for (name, score) in &scores { println!("{name}: {score}"); }

Do not depend on HashMap iteration order. Use BTreeMap when key order matters. HashSet stores unique values, and VecDeque supports efficient operations at both ends.

use std::collections::{BTreeMap, HashSet, VecDeque};
let unique: HashSet<_> = [1, 2, 2, 3].into_iter().collect();
let mut sorted = BTreeMap::new(); sorted.insert("b", 2); sorted.insert("a", 1);
let mut queue = VecDeque::new(); queue.push_back("first");
assert_eq!(queue.pop_front(), Some("first"));

Error handling

Rust uses Result<T, E> for recoverable errors and panic! for unrecoverable bugs.

use std::{fs, io};
fn read_config() -> Result<String, io::Error> {
    let contents = fs::read_to_string("config.toml")?;
    Ok(contents)
}

? unwraps a success value and returns an error early, converting it through From when applicable. main may also return Result.

use std::{error::Error, fs};
fn main() -> Result<(), Box<dyn Error>> {
    println!("{}", fs::read_to_string("config.toml")?);
    Ok(())
}

Useful combinators include map, map_err, and_then, unwrap_or, unwrap_or_else, inspect, and inspect_err.

fn parse_number(text: &str) -> Result<i32, String> {
    text.parse::<i32>().map_err(|error| format!("invalid integer: {error}"))
}
assert_eq!(parse_number("42"), Ok(42));

Library APIs usually benefit from a concrete error type callers can inspect. Implement Display, Error, and appropriate From conversions; crates such as thiserror and anyhow may be useful depending on the application.

Use unwrap and expect mainly in tests, examples, or places where failure proves an invariant violation. Use Result or Option for ordinary input failures.

Generics, traits, and lifetimes

fn largest<T: PartialOrd>(values: &[T]) -> Option<&T> {
    let mut iterator = values.iter();
    let mut largest = iterator.next()?;
    for value in iterator { if value > largest { largest = value; } }
    Some(largest)
}
assert_eq!(largest(&[3, 1, 4, 2]), Some(&4));

Traits define shared behavior.

trait Summary {
    fn summarize(&self) -> String;
    fn category(&self) -> &'static str { "general" }
}

struct Article { title: String }
impl Summary for Article {
    fn summarize(&self) -> String { self.title.clone() }
}

Use impl Trait, explicit bounds, or where clauses depending on readability.

use std::fmt::{Debug, Display};
fn print_summary(item: &impl Display) { println!("{item}"); }
fn print_debug<T: Debug>(item: &T) { println!("{item:?}"); }
fn compare_and_print<T, U>(left: &T, right: &U)
where T: Display + PartialOrd<U>, U: Display,
{ println!("{left} / {right}"); }

Associated types select one concrete type per trait implementation.

trait Repository {
    type Item;
    type Error;
    fn find(&self, id: u64) -> Result<Option<Self::Item>, Self::Error>;
}

Generics use static dispatch; dyn Trait uses runtime dispatch through a vtable and allows heterogeneous values.

use std::fmt::Display;
let values: Vec<Box<dyn Display>> = vec![Box::new(42), Box::new(String::from("hello"))];

Lifetime annotations connect the validity of references; they do not extend a value's lifetime.

struct Excerpt<'a> { text: &'a str }
impl<'a> Excerpt<'a> { fn text(&self) -> &str { self.text } }

Owning a String instead of borrowing &str can eliminate lifetime parameters when ownership better matches the design.

Iterators

Iterator adapters are lazy; consumers such as collect, sum, and find drive evaluation.

let result: Vec<i32> = (1..=10)
    .filter(|n| n % 2 == 0)
    .map(|n| n * n)
    .collect();
assert_eq!(result, vec![4, 16, 36, 64, 100]);

iter() yields &T, iter_mut() yields &mut T, and into_iter() usually yields T and consumes the collection.

let mut values = vec![1, 2, 3];
for value in values.iter_mut() { *value *= 2; }
assert_eq!(values, vec![2, 4, 6]);
let total: i32 = values.into_iter().sum();
assert_eq!(total, 12);

Implement Iterator::next to create an iterator.

struct Counter { current: u32, end: u32 }
impl Iterator for Counter {
    type Item = u32;
    fn next(&mut self) -> Option<Self::Item> {
        if self.current >= self.end { return None; }
        self.current += 1; Some(self.current)
    }
}
assert_eq!(Counter { current: 0, end: 3 }.collect::<Vec<_>>(), vec![1, 2, 3]);

Smart pointers

Box<T> places a value on the heap with single ownership.
Rc<T> provides reference-counted shared ownership within one thread.
Arc<T> provides atomic reference-counted ownership across threads.
Cell<T> and RefCell<T> provide interior mutability; RefCell checks borrowing at runtime and panics on violations.

enum List { Cons(i32, Box<List>), Nil }
let list = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Nil))));

use std::{cell::RefCell, rc::Rc};
let shared = Rc::new(String::from("shared"));
let copy = Rc::clone(&shared);
assert_eq!(Rc::strong_count(&shared), 2);

let values = RefCell::new(vec![1, 2]);
values.borrow_mut().push(3);
assert_eq!(*values.borrow(), vec![1, 2, 3]);

Rust uses RAII: resources such as locks and files are released when their owner is dropped. Implement Drop for custom cleanup, and call drop(value) to release a value before the end of its scope.

Modules, packages, and visibility

Term	Meaning
Package	A `Cargo.toml` definition containing one or more crates
Crate	A compilation unit: a binary or library
Module	A namespace and visibility boundary within a crate

Items are private by default. pub, pub(crate), pub(super), and pub(in path) expose progressively scoped APIs.

mod network {
    pub mod client { pub fn connect() { println!("connected"); } }
    fn private_helper() {}
}
use network::client;
fn main() { client::connect(); }

Typical files include src/main.rs for a binary root, src/lib.rs for a library root, and files or subdirectories for modules. Both network.rs plus network/client.rs and the older network/mod.rs layout are supported.

use std::collections::HashMap;
use std::fmt::{self, Display};
use std::io::Result as IoResult;

mod models { pub struct User; }
pub use models::User; // Re-export from a crate root.

Concurrency

Ownership plus the Send and Sync traits lets Rust reject many concurrency mistakes at compile time.

use std::thread;
let values = vec![1, 2, 3];
let handle = thread::spawn(move || values.iter().sum::<i32>());
assert_eq!(handle.join().expect("thread panicked"), 6);

let borrowed = vec![1, 2, 3];
thread::scope(|scope| { scope.spawn(|| println!("{borrowed:?}")); });

The standard mpsc channel supports multiple producers and one consumer.

use std::{sync::mpsc, thread};
let (sender, receiver) = mpsc::channel();
for id in 0..2 {
    let sender = sender.clone();
    thread::spawn(move || sender.send(format!("worker {id}")).unwrap());
}
drop(sender);
for message in receiver { println!("{message}"); }

Use Arc<Mutex<T>> for mutable state shared across threads. Lock guards release automatically when dropped; keep critical sections short and acquire multiple locks in a consistent order.

use std::{sync::{Arc, Mutex}, thread};
let counter = Arc::new(Mutex::new(0));
let handles: Vec<_> = (0..10).map(|_| {
    let counter = Arc::clone(&counter);
    thread::spawn(move || *counter.lock().expect("poisoned mutex") += 1)
}).collect();
for handle in handles { handle.join().unwrap(); }
assert_eq!(*counter.lock().unwrap(), 10);

Send means ownership can move to another thread; Sync means &T can be shared across threads. Manual unsafe impl requires the author to uphold the full safety contract.

Rust supplies Future and async syntax, but the standard library does not provide a general-purpose async runtime. Choose a runtime such as Tokio when the I/O requirements call for one.

async fn fetch_value() -> u32 { 42 }
async fn calculate() -> u32 { fetch_value().await * 2 }

Calling an async fn creates a lazy Future; work progresses only when it is awaited or driven by an executor.

Macros and attributes

Common macros include println!, eprintln!, format!, vec!, assert!, assert_eq!, and assert_ne!. todo!, unimplemented!, and unreachable! panic if executed.

macro_rules! hash_map {
    ($($key:expr => $value:expr),* $(,)?) => {{
        let mut map = std::collections::HashMap::new();
        $(map.insert($key, $value);)*
        map
    }};
}
let scores = hash_map! { "Alice" => 10, "Bob" => 20 };

Procedural macros include custom derives, attribute macros, and function-like macros, and are defined in a separate proc-macro crate.

#[derive(Debug, Clone, PartialEq)]
struct User;

#[cfg(target_os = "linux")]
fn platform_name() -> &'static str { "Linux" }

#[must_use]
fn calculate() -> i32 { 42 }

#[cfg(feature = "json")] enables conditional compilation for Cargo features.

Testing

pub fn add(left: i32, right: i32) -> i32 { left + right }

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn adds_numbers() { assert_eq!(add(2, 3), 5); }

    #[test]
    fn parses_number() -> Result<(), Box<dyn std::error::Error>> {
        assert_eq!("42".parse::<i32>()?, 42); Ok(())
    }
}

Files under tests/ are separate crates that test a library's public API. Documentation code blocks attached to /// comments are tested by default.

cargo test
cargo test name_filter
cargo test -- --nocapture
cargo test -- --ignored
cargo test --doc
cargo test --all-features

Standard-library quick reference

let name = "Ferris";
println!("{name:>8}");
println!("hex: {:x}, binary: {:b}", 10, 10);

let text = "  Hello, Rust  ";
assert_eq!(text.trim(), "Hello, Rust");
assert_eq!("a,b,c".split(',').collect::<Vec<_>>(), vec!["a", "b", "c"]);
assert_eq!(["a", "b", "c"].join("-"), "a-b-c");

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let number: i32 = "42".parse()?;
    let hex = i32::from_str_radix("ff", 16)?;
    assert_eq!((number.to_string(), hex), (String::from("42"), 255));
    Ok(())
}

Use fs::read_to_string and fs::write for small files, or BufReader and BufRead::lines for streaming large files. Build paths with Path and PathBuf. Read arguments with env::args and environment variables with env::var; never print secrets in logs or error messages.

Use Instant for elapsed time, SystemTime for system-clock values, and Duration for spans. Date formatting and time zones generally require a suitable external crate.

OnceLock<T> initializes a global value once; LazyLock<T> initializes it from a closure on first access.

use std::sync::{LazyLock, OnceLock};
static CONFIG: OnceLock<String> = OnceLock::new();
static DEFAULTS: LazyLock<Vec<String>> = LazyLock::new(|| vec![String::from("default")]);
assert_eq!(CONFIG.get_or_init(|| String::from("production")), "production");
assert_eq!(DEFAULTS.len(), 1);

Calling external functions: `extern` and FFI

extern "C" selects the C ABI. In Edition 2024, external blocks must be declared with unsafe extern because Rust cannot verify that their signatures match the foreign definitions.

use std::ffi::c_int;
unsafe extern "C" { fn abs(input: c_int) -> c_int; }
// SAFETY: -42 is a valid c_int input for C abs.
assert_eq!(unsafe { abs(-42) }, 42);

Export a Rust function with a C ABI as follows:

#[unsafe(no_mangle)]
pub extern "C" fn add(left: i32, right: i32) -> i32 { left + right }
assert_eq!(add(2, 3), 5);

At an FFI boundary, verify the ABI and signatures, #[repr(C)] layouts, pointer validity and alignment, string encoding and termination, allocation ownership, and panic or exception behavior. Generated bindings such as bindgen may reduce transcription mistakes.

`unsafe` Rust

unsafe does not disable the borrow checker. It permits a small set of operations whose safety the compiler cannot prove: dereferencing raw pointers, calling unsafe functions, accessing mutable statics, implementing unsafe traits, and reading union fields.

unsafe fn first_unchecked(values: &[i32]) -> &i32 {
    // SAFETY: The caller guarantees that values is non-empty.
    unsafe { values.get_unchecked(0) }
}
let values = [10, 20];
// SAFETY: values contains two elements.
assert_eq!(*unsafe { first_unchecked(&values) }, 10);

Edition 2024 still requires an explicit unsafe block inside an unsafe fn. Keep unsafe regions small, document invariants with SAFETY comments, and ensure every safe wrapper preserves those invariants for all safe callers.

Cargo and dependency management

cargo new app
cargo new --lib my-library
cargo check
cargo build --release
cargo run -- arg1 arg2
cargo test
cargo doc --open
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings

cargo check is fast because it does not produce a final binary. Still run builds and tests before release.

[package]
name = "example"
version = "0.1.0"
edition = "2024"
rust-version = "1.98"

edition selects language compatibility rules; rust-version declares the MSRV actually supported and tested by the package.

cargo add serde --features derive
cargo add --dev tempfile
cargo update
cargo tree
cargo tree -d

Cargo.lock records an exact dependency resolution. Applications normally commit it. Libraries may also commit a workspace lockfile for reproducible development and CI, while consumers still resolve versions from Cargo.toml constraints.

Features should be additive. Test meaningful combinations with --all-features and --no-default-features. A workspace can share edition, rust-version, and dependency declarations through [workspace.package] and [workspace.dependencies]; Edition 2024 workspaces use resolver = "3".

Tips and common mistakes

Avoid reflexive `clone`

Borrow when ownership is unnecessary; cloning may hide a design problem and add allocations.

fn print_name(name: &str) { println!("{name}"); }
let name = String::from("Ferris");
print_name(&name);
println!("{name}");

Prefer slices in read-only APIs

Use &str instead of &String, and &[T] instead of &Vec<T>, unless the concrete container is required.

Use checked indexing for uncertain input

values[index] panics out of bounds; values.get(index) returns Option<&T>.

Remember that strings are UTF-8

let text = "🦀Rust";
assert_eq!(text.len(), 8); // Bytes, not visible characters.
assert_eq!(text.chars().next(), Some('🦀'));

Rust strings have no integer indexing. Use an appropriate Unicode crate when grapheme-cluster processing is required.

Do not hold a synchronous mutex guard across `.await`

use std::sync::Mutex;
async fn async_operation(_value: String) {}
async fn process(shared: &Mutex<String>) {
    let value = { shared.lock().expect("poisoned mutex").clone() };
    async_operation(value).await;
}

Release the guard first, or choose an async-aware mutex when appropriate. Likewise, move blocking I/O or CPU-heavy work off an async executor's worker threads using the runtime's blocking API or dedicated threads.

Document panics in public APIs

Ordinary invalid input should generally return Result or Option. If a public function can panic, document the condition in a # Panics section.

Keep warnings clean

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Review Clippy suggestions before applying them; they can affect semantics or performance. Follow project-specific lint policy where one exists.

Official references

Rust works best when ownership, borrowing, and types make invalid states difficult to represent. Compiler errors are not merely restrictions—they are early feedback about the design.

Prompts Aren't Policies: I Built a Deterministic Tool Gate for Claude Code and Codex

Nobuo Miura — Tue, 11 Aug 2026 11:11:17 +0000

I built an open-source tool called PolicyApprovalGate. It applies deterministic local rules immediately before Claude Code or Codex CLI runs a shell command. It also checks Claude Code's direct Read, Write, and Edit operations and target paths extracted from Codex apply_patch calls.

Updated August 14, 2026: The first version of this article covered shell commands only. PolicyApprovalGate now applies path policies to Claude Code's Read, Write, and Edit tools and to target paths in Codex apply_patch calls. The installation and limitations below have been updated as well.

nobuo-miura / PolicyApprovalGate

Deterministic, LLM-free PreToolUse guardrail for Claude Code and Codex CLI. Applies local policy to shell commands and supported file operations, with deny/ask decisions and audit logs.

PolicyApprovalGate

English | 日本語

PolicyApprovalGate is a PreToolUse hook that checks shell commands against local rules before Claude Code or Codex CLI runs them. On Claude Code, it also checks direct file access through Read, Write, and Edit.

It detects dangerous commands, pushes to protected branches, and access to out-of-project or sensitive paths, then records the decision in an audit log. It does not use AI or an LLM, so the same input always produces the same result.

Important

PolicyApprovalGate complements the host permission model, sandbox, and human review. It is neither a complete shell analyzer nor a security boundary, and should not be your only line of defense.

In this example, PolicyApprovalGate blocks Claude Code from reading ~/.ssh and returns the reason to the host.

Features

Deterministic local decisions without AI or an LLM
Always-on protection against recursive force-deletion of the filesystem root or current user's home
Configurable command…

View on GitHub

Why I Built It

I started this project after Claude Code tried to run a command that I had explicitly told it not to run in CLAUDE.md.

CLAUDE.md is useful for communicating project policies, coding conventions, and preferred workflows. However, writing a prohibition there does not make it an enforceable rule at execution time.

The official Claude Code documentation describes CLAUDE.md as instructions loaded into the model's context, not as a hard enforcement layer. Instructions may not always be followed exactly, especially when they are ambiguous or conflict with one another.

This was particularly concerning in Auto mode, which reduces confirmation prompts so that Claude Code can work on longer tasks with fewer interruptions.

Auto mode currently uses a separate classifier to review each tool call. It also takes CLAUDE.md into account, but the documentation states that this does not guarantee safety.

I therefore decided to add a separate check that runs immediately before a supported tool operation is executed.

I wanted it to do four things:

Immediately reject commands that must never be executed
Require confirmation for selected commands, even when the rest of the task can proceed automatically
Require confirmation before accessing sensitive data
Require confirmation for operations outside specified directories

That is why I built PolicyApprovalGate.

What Is PolicyApprovalGate?

PolicyApprovalGate is a policy gate written in Go that runs as a PreToolUse hook for Claude Code and Codex CLI.

When an agent attempts a supported operation, PolicyApprovalGate receives the tool call through standard input and checks it against the configured rules. Shell commands are checked against command rules and path policies. Claude Code's Read, Write, and Edit tools are checked against path policies.

It returns one of the following results:

Decision	Claude Code	Codex CLI
`deny`	Rejects the command	Rejects the command
`ask`	Prompts the user for confirmation	Converts the result to `deny` because standalone `ask` is not supported
No decision	Delegates to the normal approval flow	Delegates to the normal approval flow

PolicyApprovalGate never executes the operation itself. It only inspects the command string or file path, then returns a decision to the host.

What Does It Check?

The built-in rules check operations such as:

Recursive force deletion targeting / or the current user's home directory
Formatting a filesystem or writing directly to a block device
Downloading content and piping it directly into a shell
Force-pushing to or deleting protected branches
Writing to or deleting files outside the project
Accessing .env files, SSH keys, credential files, and other sensitive paths
Writing to PolicyApprovalGate itself or to hook configuration files

PolicyApprovalGate parses shell syntax with mvdan.cc/sh rather than relying solely on simple regular expressions.

This allows it to track cases such as the following where possible:

Relative paths after changing directories, as in cd /tmp && rm -rf target
Symbolic links that point outside the project
Wrappers such as env and command
Pushes performed with git -C
Commands using cp -t or install --target-directory
Quoted paths that contain spaces

However, PolicyApprovalGate is not a complete shell interpreter. Unsupported syntax and operations that cannot be determined statically are delegated to the host's normal approval flow by default.

Keeping Sensitive Data Out of the Agent Context

Preventing commands from modifying or deleting data is only part of the problem. It is equally important to avoid letting the agent read secrets into its context.

PolicyApprovalGate's built-in configuration treats paths such as the following as sensitive_paths:

.env files and their variants
.ssh directories and SSH keys
.pem, .p12, .pfx, and .key files
AWS credential files
Authentication files such as .netrc

By default, supported reads return ask, while writes and deletions return deny. Claude Code asks for confirmation before a read, while Codex CLI converts ask to deny.

If you do not want these files to be read even after confirmation, keep the existing patterns generated by policygate init and change sensitive_paths.policy.read to deny in ~/.policygate/config.yaml:

 sensitive_paths:
   policy:
-    read: "ask"
+    read: "deny"
     write: "deny"
     delete: "deny"

After changing the setting, you can use evaluate to check the decision without reading the actual file:

policygate check-config
policygate evaluate --host claude --command 'cat ~/.ssh/id_rsa'

PolicyApprovalGate also applies the same path policies to Claude Code's direct Read, Write, and Edit tools. It does not currently inspect Grep, Glob, or every other tool call, and it cannot prevent every read performed through unsupported commands or arbitrary child processes.

To prevent Claude Code's own file tools from reading sensitive files under your home directory, configure the standard permissions.deny rules as well:

{
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(~/.gnupg/**)",
      "Read(~/.config/gh/**)",
      "Read(**/.env*)"
    ]
  }
}

The Claude Code permissions documentation explains that Read deny rules apply not only to built-in file tools but also to Bash file commands that Claude Code recognizes, including cat, head, tail, and sed. They do not cover arbitrary subprocesses, such as Python or Node.js programs that access files directly. If every child process must be restricted at the OS level, combine these controls with Claude Code's sandbox filesystem restrictions, a container, or a dedicated operating-system user.

In other words, the responsibilities are divided across these layers:

Use permissions.deny for host-native restrictions on Claude Code's file tools and recognized Bash file commands
Use PolicyApprovalGate's sensitive_paths for an independent policy and audit layer over supported shell commands and Claude Code's Read, Write, and Edit tools
Use sandboxing or OS permissions when stronger restrictions must also cover arbitrary child processes

PolicyApprovalGate does not completely protect secrets on its own. It is an additional layer designed to work alongside existing permission controls.

Deny Rules and Confirmation Rules

PolicyApprovalGate stores its configuration in YAML.

For example, you can add an ask rule when you always want confirmation before git push:

ask:
  - pattern: '(^|[;&|])\s*(/\S*/)?git\s+push\b'
    reason: "Confirm before pushing to a remote"

When this rule matches in Claude Code, the PreToolUse hook returns ask.

According to the Claude Code Hooks documentation, an ask result from a PreToolUse hook forces a confirmation prompt even in Auto mode, so the classifier cannot silently approve the command. A deny result rejects the command itself.

Codex CLI does not support a standalone ask decision from PreToolUse. PolicyApprovalGate therefore converts ask to deny when invoked with --host codex, choosing the safer behavior instead of allowing the command to proceed without confirmation.

File Tools and Codex apply_patch

Claude Code passes a file path, rather than a command string, to its Read, Write, and Edit tools. PolicyApprovalGate applies sensitive_paths, protected_paths, path_scope, and its self-protection rules to those paths. It deliberately does not apply command-oriented regular expressions to file names.

Codex edits files with apply_patch. In observed Codex CLI behavior, the patch reaches the PreToolUse hook as a Bash command. PolicyApprovalGate extracts paths from *** Add File:, *** Update File:, *** Delete File:, and *** Move to: markers before applying command rules and path policies.

This is still bounded static inspection. If the target path exists only in a separate file or dynamically generated input and does not appear in the command received by the hook, PolicyApprovalGate cannot inspect it.

You can test a file-tool decision without accessing the file:

policygate evaluate --host claude --tool Read --file-path ~/.ssh/id_rsa

Install and Try It Without Running a Command

Install the latest release after reviewing the installer:

curl -fsSLO https://raw.githubusercontent.com/nobuo-miura/PolicyApprovalGate/main/install.sh
less install.sh
sh install.sh

Create the configuration file:

policygate init
policygate check-config

The evaluate command lets you check the decision without executing the command being evaluated:

policygate evaluate --host claude --command 'rm -rf /'

It returns a deny decision as JSON. For readability, the example below is formatted and omits the matched_by field included in the actual output:

{
  "decision": "deny",
  "reason": "Recursive force-delete of / or $HOME",
  "source": "deny_rule"
}

Instead of enabling the hook immediately after changing the configuration, you can first use check-config and evaluate to verify that it produces the intended decisions.

Register It with Claude Code and Codex CLI

Use the built-in installer so the required matchers and the current binary path are registered correctly:

policygate install-hook --host claude
policygate install-hook --host codex
policygate doctor

For Claude Code, the command registers Bash, PowerShell, Read, Write, and Edit. Project-local registration uses .claude/settings.local.json; add --user to register in the user settings instead. For Codex, it updates ~/.codex/config.toml. Run /hooks in Codex and trust the displayed hook before relying on it.

How It Fits with Claude Code's Native Deny Rules

If you only use Claude Code and need to reliably block a simple command or path, the standard permissions.deny rules should be your first choice. Managed settings are also available when an organization needs to enforce these rules.

PolicyApprovalGate is intended for cases such as:

Using the same policy with both Claude Code and Codex CLI
Taking protected branches, working directories, and symbolic links into account
Recording the reason for each decision in a local audit log
Adding an independent layer alongside existing permission settings

You do not have to choose one or the other. PolicyApprovalGate is intended to be layered onto the areas where it is needed while retaining the host's standard permission controls and sandbox.

Limitations

PolicyApprovalGate is a defense-in-depth guardrail, not a security boundary.

It covers shell commands on both hosts, including Codex apply_patch, and Claude Code's Read, Write, and Edit tools; other tool calls remain out of scope
File tools receive path-policy checks only; command-oriented deny, ask, allow, and unknown.action rules are not applied to file names
An apply_patch target cannot be inspected if it does not appear in the command string received by the hook
An ask decision prompts for confirmation in Claude Code but is converted to deny in Codex, so the same policy can prompt on one host and reject the command on the other
It cannot fully handle obfuscated commands or dynamically determined command names
It does not resolve Git aliases, so a push hidden behind an alias can bypass the protected-branch check; use remote branch protection when that rule must hold
Unknown commands and shell syntax that cannot be parsed follow unknown.action and parse_error.action; both default to defer and can be changed to ask or deny. Claude Code prompts for an ask fallback, while Codex converts it to deny
An invalid explicit policy configuration returns deny for a valid Bash hook call; hook input, decision-output, and audit-log failures are reported to standard error but cannot always produce or replace the host decision
PowerShell input on Windows is experimental

It is not a replacement for remote branch protection, OS permissions, sandboxing, or human review.

Closing

Writing a prohibition in CLAUDE.md and mechanically enforcing a rule immediately before execution serve different purposes. A prompt communicates intent; it is not a policy enforcement mechanism.

You can use CLAUDE.md to communicate everyday development policies, while a PreToolUse hook checks hard boundaries such as “never execute this command” or “always ask before doing this.” PolicyApprovalGate brings this two-layer approach to both Claude Code and Codex CLI.

nobuo-miura / PolicyApprovalGate

Deterministic, LLM-free PreToolUse guardrail for Claude Code and Codex CLI. Applies local policy to shell commands and supported file operations, with deny/ask decisions and audit logs.

PolicyApprovalGate

English | 日本語

Important

PolicyApprovalGate complements the host permission model, sandbox, and human review. It is neither a complete shell analyzer nor a security boundary, and should not be your only line of defense.

In this example, PolicyApprovalGate blocks Claude Code from reading ~/.ssh and returns the reason to the host.

Features

Deterministic local decisions without AI or an LLM
Always-on protection against recursive force-deletion of the filesystem root or current user's home
Configurable command…

View on GitHub

I Got Tired of Recreating GitHub Rulesets, So I Built a GitHub CLI Extension

Nobuo Miura — Mon, 20 Jul 2026 10:41:38 +0000

Every time I created a new repository, I found myself configuring the same rules for its default branch again:

Require changes to go through pull requests
Block force pushes
Prevent branch deletion
Require status checks when needed

None of this is difficult for a single repository. But as the number of repositories grows, repeatedly opening the same settings page and recreating the same ruleset becomes tedious. It also becomes harder to tell which repositories still share the same configuration.

I wanted a way to save one repository ruleset as a reusable template, apply it elsewhere, and check whether the deployed rulesets still matched it.

So I built gh-rulekit, an open-source GitHub CLI extension for saving, editing, and reusing repository rulesets.

nobuo-miura / gh-rulekit

GitHub CLI extension to save, edit, and bulk-apply repository rulesets across all your repos

gh-rulekit

English | 日本語

A gh extension for saving GitHub repository rulesets locally, editing them, and applying the same ruleset across multiple repositories.

Features

Export repository rulesets to a local library
Review and edit saved rulesets as JSON
Preview changes before applying them
Create or update a ruleset in one or many repositories
Replace an old ruleset only after the new one has been applied successfully
Delete saved rulesets locally or from one or many repositories
Compare repository rulesets with locally saved versions

Requirements

GitHub CLI installed and authenticated with gh auth login
Read access to repositories you export or inspect
Repository admin access, or a custom role with permission to edit repository rules, when applying or deleting rulesets on GitHub
Go is required only when installing from source

Install

From a release (recommended)

Install the latest release:

gh extension install nobuo-miura/gh-rulekit

From source

git clone https://github.com/nobuo-miura/gh-rulekit.git
cd gh-rulekit
go

…

View on GitHub

What gh-rulekit Does

gh-rulekit provides a small local library for GitHub repository rulesets. It can:

Export an existing repository ruleset
Store and edit the exported ruleset as JSON
Preview target repositories and whether each ruleset will be created or updated
Apply the same ruleset to one or many repositories
Compare rulesets on GitHub with locally saved versions

The basic workflow looks like this:

# 1. Save a ruleset under a convenient local name
gh rulekit export owner/source-repo --name main --as protect-default

# 2. Preview the targets and actions
gh rulekit apply protect-default --all --dry-run

# 3. Apply the ruleset
gh rulekit apply protect-default --all

# 4. Check whether the deployed rulesets still match
gh rulekit status

Installation

gh-rulekit requires GitHub CLI and an authenticated session created with gh auth login.

Install the extension with:

gh extension install nobuo-miura/gh-rulekit

Then check the available commands:

gh rulekit --help

The help text follows your locale: Japanese locales receive Japanese help, while other locales receive English help.

Exporting a Ruleset

Start by creating the ruleset you want in one repository through GitHub. Then export it into the local library.

For example, this command exports the main ruleset from owner/source-repo and saves it locally as protect-default:

gh rulekit export owner/source-repo --name main --as protect-default

The --as option changes only the name in the local library. It does not rename the ruleset on GitHub. When the saved ruleset is applied elsewhere, its GitHub name remains main.

You can inspect and manage saved rulesets with:

gh rulekit list
gh rulekit show protect-default
gh rulekit edit protect-default

edit opens the JSON file in $EDITOR and validates the file after it is saved. This makes it possible to review or adjust the API representation directly without maintaining a separate configuration format.

Previewing a Bulk Apply

Applying configuration across many repositories is useful, but it is also an operation worth reviewing first.

With --dry-run, gh-rulekit lists each target and shows whether it would create a new ruleset or update an existing ruleset with the same name. It does not modify anything.

gh rulekit apply protect-default --all --dry-run

Targets can be filtered by visibility:

gh rulekit apply protect-default --all --public --dry-run
gh rulekit apply protect-default --all --private --dry-run

You can also target an organization:

gh rulekit apply protect-default --all --owner my-org --dry-run

Archived repositories are skipped because they are read-only.

Always review the output of --dry-run before using --all. A bulk apply can modify many repositories.

Applying the Ruleset

After reviewing the targets, remove --dry-run to apply the ruleset:

gh rulekit apply protect-default --all

If a repository already has a ruleset with the same GitHub name, gh-rulekit updates it. Otherwise, it creates a new one.

To change only one repository, use --repo:

gh rulekit apply protect-default --repo owner/repo

Rulesets that target GitHub's ~DEFAULT_BRANCH placeholder can be reused without knowing whether each repository uses main, master, or another default branch name. There is no need to rewrite the saved JSON for every repository.

Detecting Configuration Drift

Bulk application solves only half of the problem. I also wanted to know whether repository rulesets still matched the version I had saved locally.

The status command compares ruleset contents with the local library:

gh rulekit status

Its output uses three states:

== local:<name> — the content matches a locally saved ruleset
!= local:<name> — a local ruleset with the same name exists, but its content differs
-- (no local match) — no corresponding local ruleset was found

The first comparison is content-based, so it can find a match even when the local saved name differs from the ruleset name on GitHub.

To inspect a single repository:

gh rulekit status --repo owner/repo

This provides a quick way to spot repositories whose settings have diverged after a manual change.

Why Not Use Organization Rulesets?

GitHub already supports organization-level rulesets, and they are the natural choice when you want centralized enforcement across repositories in one organization and your plan supports them.

gh-rulekit is aimed at a different set of cases:

You maintain multiple repositories under a personal account
You want to reuse a repository ruleset across different owners or organizations
You want the ruleset available locally as editable JSON
You want to compare current repository settings with a saved reference

It does not replace GitHub Rulesets. It makes repository-level rulesets easier to save, reuse, and inspect.

Notes for v0.1.0

Exporting and inspecting rulesets requires read access to the target repositories
Applying rulesets requires repository admin access or a custom role with permission to edit repository rules
Rulesets on private repositories require an eligible GitHub paid plan
--dry-run previews targets and create/update actions, but it does not show a field-by-field diff
A bulk operation continues after individual failures and reports a non-zero exit status at the end
Successful changes are not automatically rolled back if another repository fails

For a first run, I recommend filtering the targets, checking --dry-run, and applying the ruleset to a small number of repositories before using it more broadly.

Closing

gh-rulekit came from a very small annoyance: configuring the same default-branch rules every time I created a repository.

The settings themselves were not complicated. They were simply repetitive. Turning that repetition into a reusable CLI workflow has made creating and reviewing repositories much easier for me.

gh-rulekit is still at v0.1.0. If you try it and find a bug or have an idea for improving the workflow, feedback and issues are welcome.

nobuo-miura / gh-rulekit

GitHub CLI extension to save, edit, and bulk-apply repository rulesets across all your repos

gh-rulekit

English | 日本語

A gh extension for saving GitHub repository rulesets locally, editing them, and applying the same ruleset across multiple repositories.

Features

Export repository rulesets to a local library
Review and edit saved rulesets as JSON
Preview changes before applying them
Create or update a ruleset in one or many repositories
Replace an old ruleset only after the new one has been applied successfully
Delete saved rulesets locally or from one or many repositories
Compare repository rulesets with locally saved versions

Requirements

GitHub CLI installed and authenticated with gh auth login
Read access to repositories you export or inspect
Repository admin access, or a custom role with permission to edit repository rules, when applying or deleting rulesets on GitHub
Go is required only when installing from source

Install

From a release (recommended)

Install the latest release:

gh extension install nobuo-miura/gh-rulekit

From source

git clone https://github.com/nobuo-miura/gh-rulekit.git
cd gh-rulekit
go

…

View on GitHub

Building a Local-Only Browser Extension That Translates GitHub's UI—Not Your Content

Nobuo Miura — Sat, 11 Jul 2026 01:51:23 +0000

Built-in browser translation is convenient, but it is often too broad for developer tools. It can translate repository content along with the interface, turning terms such as "branch" into awkward words and making technical pages harder to read.

There is also a more serious concern in corporate environments: depending on the translation feature or service being used, page content may be sent to an external translation provider. That can be unacceptable when a page contains private repository code, internal issue discussions, or other confidential information.

I wanted a narrower and more predictable solution:

Translate only GitHub's fixed interface labels
Leave README files, issues, comments, and source code untouched
Never send text to an external translation API or cloud translation service
Perform the entire translation locally in the browser

So I built GitHub UI Translator, an open-source browser extension for Chrome and Firefox.

nobuo-miura / github-ui-translator

A browser extension for Chrome, Edge, and Firefox that translates GitHub's UI into multiple languages using local dictionaries. No external APIs — all translation runs locally.

GitHub UI Translator

English | 日本語

GitHub UI Translator is a browser extension for Chrome, Edge, and Firefox that translates GitHub's English UI into Japanese, Simplified Chinese, Spanish, German, Brazilian Portuguese, or Korean using a local dictionary It does not rely on external translation APIs or cloud services; all translation runs locally in the browser.

Features

Performs all translation locally without sending page content or settings to external services
Translates fixed GitHub UI text such as navigation items and buttons while avoiding user-created content areas such as READMEs, issues, comments, and code blocks
Lets you turn translation on or off from the extension popup
Translates the global header after GitHub's React hydration completes to reduce the risk of interfering with the global search; this can be turned off from the popup

Documentation

Translation scope (Japanese)

Limitations

Japanese, Simplified Chinese, Spanish, German, Brazilian Portuguese, and Korean are currently supported…

View on GitHub

The initial bundled dictionary translates GitHub's interface into Japanese, but the design is not tied to any particular language.

The Main Design Goal: Decide What Not to Translate

A straightforward translation extension could scan every text node on the page and replace matching strings. The problem is that GitHub pages contain both interface text and user-generated content.

Translating the whole page could modify:

README files
Issue and pull request descriptions
Comments
Code blocks
Repository file content

For this extension, leaving those areas untouched is more important than translating every possible label.

Instead of scanning the entire document, the extension starts with an allowlist of semantic UI elements:

const BASE_SELECTOR = [
  'nav',
  'header',
  'button',
  'input[type="submit"]',
  'input[type="button"]',
  'input[type="reset"]',
  '[role="tab"]',
  '[role="menuitem"]',
  '[role="menuitemradio"]',
  '[role="menuitemcheckbox"]',
  '[role="menu"]',
  '[role="dialog"]',
  '[role="listbox"]',
  '[role="button"]',
  '[aria-label]'
];

These selectors describe the meaning of an element rather than GitHub's visual implementation. CSS class names and data-testid values can change during a refactor, while elements such as nav and ARIA roles are more closely tied to how the interface works.

Some GitHub pages, including Settings and Issue or Pull Request screens, contain fixed interface text in headings, labels, and links. On those pages, the extension expands the allowlist based on the URL. Content containers such as .markdown-body are still explicitly excluded.

This approach is intentionally conservative. Missing a label is preferable to modifying content written by a user.

Exact Matches Instead of Machine Translation

The extension does not use a machine translation model. It replaces text only when the complete string matches an entry in its bundled dictionary.

For example:

{
  "language": "ja",
  "name": "日本語",
  "translations": {
    // Repository navigation
    "Code": "コード",
    "Issues": "イシュー",
    "Pull requests": "プルリクエスト",

    // Repository actions
    "Watch": "ウォッチ",
    "Star": "スター"
  }
}

Dynamic strings such as 3 commits or opened 2 days ago do not match a dictionary entry, so they remain in English.

That limits translation coverage, but it also provides a useful safety property: unknown text is displayed exactly as GitHub provided it. There is no generated translation that can unexpectedly change the meaning of a technical term.

Translation is not limited to visible text nodes: matching aria-label values, placeholder attributes, and button value attributes are also translated, so relevant labels used by assistive technologies are covered as well.

Keeping Confidential Content Away from Translation Services

The dictionary is bundled with the extension. Translation is a local string-matching operation performed inside the browser.

The extension does not send page text to an external translation API or cloud translation service. It does not need to upload a README, issue discussion, pull request description, or source file to produce a translation.

This distinction matters in organizations where private repositories contain confidential code or internal discussions. Even when an external translation service is useful, company policy may prohibit sending repository content to it.

GitHub UI Translator reduces that concern in two complementary ways:

User-generated content is excluded from translation targets.
The interface text that is translated is processed locally with a bundled dictionary.

The goal is not to replace general-purpose translation. It is to provide a small, auditable tool for one specific job: translating predictable interface labels without involving repository content.

Why the Dictionary Uses Commented Sections

The Japanese dictionary contains nearly 1,000 entries. A flat JSON file quickly becomes difficult to maintain because it is not obvious which GitHub screen each label belongs to.

The dictionary therefore uses JSON with line comments to group entries by screen or feature. Before parsing the file, the extension removes the comment lines and passes the remaining content to JSON.parse.

This makes it easier to find and update the relevant section when GitHub changes an interface label. It also keeps language contributions approachable: adding another language mainly involves supplying another dictionary rather than changing the translation logic.

Current Trade-Offs

The conservative design comes with some limitations:

Japanese is currently the only included language.
Dynamic labels containing numbers, dates, or usernames remain in English.
GitHub Enterprise domains are not currently supported.
The extension has been tested on Chrome and Firefox, but not on other Chromium-based browsers.
GitHub can introduce new UI structures or labels that are not yet in the allowlist or dictionary.

These are acceptable trade-offs for the initial version. The fallback is always the original GitHub text, not a guessed translation.

What's Next

I would like to expand the dictionary coverage and add more languages while keeping the same local-only, UI-only approach.

If you are interested in contributing a dictionary, reporting an untranslated GitHub label, or reviewing the implementation, the project is available on GitHub:

nobuo-miura / github-ui-translator

A browser extension for Chrome, Edge, and Firefox that translates GitHub's UI into multiple languages using local dictionaries. No external APIs — all translation runs locally.

GitHub UI Translator

English | 日本語

Features

Performs all translation locally without sending page content or settings to external services
Translates fixed GitHub UI text such as navigation items and buttons while avoiding user-created content areas such as READMEs, issues, comments, and code blocks
Lets you turn translation on or off from the extension popup
Translates the global header after GitHub's React hydration completes to reduce the risk of interfering with the global search; this can be turned off from the popup

Documentation

Translation scope (Japanese)

Limitations

Japanese, Simplified Chinese, Spanish, German, Brazilian Portuguese, and Korean are currently supported…

View on GitHub

Protect Non-Email Domains from Spoofing with DNS Records

Nobuo Miura — Wed, 24 Jun 2026 14:18:58 +0000

Domains used exclusively for web services, or acquired for future use through domain parking, can still be used in phishing and email-spoofing campaigns, even when they neither send nor receive email.

This article explains how to configure three DNS records — MX / SPF / DMARC — to prevent abuse of non-email domains.

Why Non-Email Domains Are Targeted

Attackers scan for domains with missing or weak SPF and DMARC records to use in the From: address. Domains that never send email are the most likely to be unconfigured, making them easy targets.

A common attack scenario:

example.com is a web-only domain — no email is ever sent from it
An attacker sends phishing emails with From: support@example.com
Because SPF / DMARC are not configured, receiving servers have no policy to apply and the message may be delivered

Records to Configure

Record	Value	Purpose
MX	`0 .`	Explicitly declare that this domain accepts no mail (null MX)
SPF (TXT)	`v=spf1 -all`	Declare no authorized senders exist
DMARC (TXT)	`v=DMARC1; p=reject; sp=reject; adkim=s; aspf=s; rua=mailto:...`	Enforce policy and collect reports

Setting Up Each Record

1. MX Record — Null MX (RFC 7505)

example.com.  MX  0  .

0 . (zero, dot) is the standard way to explicitly signal that this domain accepts no mail (RFC 7505).
Publishing an explicit null MX is preferable to omitting the MX record entirely, as it removes ambiguity for sending servers.
Note that a null MX must not coexist with any other MX records — it must be set as the sole MX record for the domain.

2. SPF Record — Declare No Authorized Senders

example.com.  TXT  "v=spf1 -all"

-all (hard fail) declares that no authorized mail servers exist for this domain, resulting in an SPF evaluation of Fail.
This produces a stronger result than ~all (soft fail, SoftFail), making it easier for receivers to apply policy.
However, the final decision to reject a message is left to the receiving server.

3. DMARC Record — Policy Enforcement

_dmarc.example.com.  TXT  "v=DMARC1; p=reject; sp=reject; adkim=s; aspf=s; rua=mailto:dmarc-reports@yourdomain.com"

Tag breakdown:

Tag	Value	Meaning
`p`	`reject`	Request that receivers reject messages failing DMARC evaluation
`sp`	`reject`	Apply the same policy to subdomains (same value as `p=reject`, but explicit)
`adkim`	`s` (strict)	DKIM `d=` tag must exactly match the From domain
`aspf`	`s` (strict)	SPF `MAIL FROM` must exactly match the From domain
`rua`	`mailto:...`	Destination for aggregate reports

About `rua` (Report Destination)

Setting up reporting is recommended especially for non-email domains.
Aggregate reports are sent in periodic batches by DMARC-compliant receivers — immediate detection is not guaranteed — but they can help you identify patterns of spoofing attempts.
Use an email address you can monitor, or an external DMARC reporting service, to receive and review these reports.

If your reporting address is on a different domain, you need to authorize it with a TXT record in that domain's DNS zone:

example.com._report._dmarc.yourdomain.com.  TXT  "v=DMARC1"

Note: This TXT record must be added to the DNS zone of yourdomain.com (the report receiver), not to example.com (the protected domain).

A Note on `adkim=s` / `aspf=s` (strict)

In strict mode, DKIM aligns only when its d= domain exactly matches the RFC5322.From domain; SPF aligns only when its MAIL FROM domain exactly matches it. For example, a DKIM signature with d=example.com will not satisfy alignment for From: sub.example.com under strict mode.
If you ever start sending legitimate email from this domain in the future, consider switching to adkim=r; aspf=r (relaxed).

Optional: Revoking DKIM Keys for Past Selectors

If the domain previously sent email and the DKIM selectors used at that time are known, you can explicitly revoke those keys.

default._domainkey.example.com.  TXT  "v=DKIM1; p="

An empty p= signals key revocation (RFC 6376), causing any DKIM signature referencing that selector to be treated as invalid.
Note that there is no verification difference between a revoked record and a deleted record, and this provides no defense against unknown selectors.
Consider this only when you want to explicitly retire a selector that was actively used in the past.

Verifying Your Configuration

Use dig to confirm the records are live:

# MX
dig MX example.com

# SPF
dig TXT example.com

# DMARC
dig TXT _dmarc.example.com

Expected output:

;; ANSWER SECTION:
example.com.        300  IN  MX   0  .
example.com.        300  IN  TXT  "v=spf1 -all"
_dmarc.example.com. 300  IN  TXT  "v=DMARC1; p=reject; sp=reject; adkim=s; aspf=s; rua=mailto:dmarc-reports@yourdomain.com"

Summary

These three records form a recommended baseline for protecting a non-email domain from spoofing:

example.com.         MX   0  .
example.com.         TXT  "v=spf1 -all"
_dmarc.example.com.  TXT  "v=DMARC1; p=reject; sp=reject; adkim=s; aspf=s; rua=mailto:dmarc-reports@yourdomain.com"

On receivers that implement DMARC and enforce policies, messages spoofing this domain can be expected to be rejected.
Take a few minutes to audit all the domains you own — the ones you're not actively using are the most likely to be missing these records.

Go 1.27 Cheat Sheet

Nobuo Miura — Tue, 23 Jun 2026 12:29:32 +0000

This cheat sheet is based on Go 1.27.

Program structure
Variables, constants, and types
Control flow
Functions
Arrays, slices, and maps
Structs, methods, and tags
Interfaces
Errors
Goroutines, channels, and synchronization
Context
Generics
Iterators
Testing
Standard-library quick reference
Tips and common mistakes
Modules and packages
Further reading

Program structure

package main  // Every executable must be in package main.

import (
    "fmt"
    "os"
)

func main() {
    fmt.Println("Hello, Go 1.27")
    os.Exit(0)
}

Every Go source file starts with a package declaration.
An executable program uses package main and a main function.
Group standard-library and third-party imports separately.

Variables, constants, and types

Variable declarations and inference

// var can infer the type from an initializer.
var name = "Gopher" // string
var age int          // No initializer: specify a type. Zero value: 0.
var id int64 = 42    // Use an explicit type when int is not what you want.

// Short declaration: inside functions only.
city := "Tokyo"

// Declare multiple variables in a block.
var (
    x, y int = 1, 2
    msg  string
)

Use var name = "Gopher" when an initializer makes the type clear. Without an initializer, write the type explicitly. A := declaration is only valid inside a function, and at least one name on its left side must be new.

Types and zero values

Category	Types	Zero value
Numbers	integers, floats, complex numbers	`0` (`0 + 0i` for complex)
Strings	`string`	`""`
Booleans	`bool`	`false`
Arrays	`[N]T`	every element is `T`'s zero value
Structs	`struct`	every field has its zero value
Reference-containing types	pointers, slices, maps, channels, functions, interfaces	`nil`
Defined types	e.g. `type UserID int`	the underlying type's zero value

Category	Types	Notes
Boolean	`bool`	`true` or `false`
String	`string`	immutable sequence of bytes (usually UTF-8, but invalid UTF-8 is allowed)
Signed integers	`int`, `int8`, `int16`, `int32`, `int64`	`int` is platform-sized (32 or 64 bit)
Unsigned integers	`uint`, `uint8`, `uint16`, `uint32`, `uint64`, `uintptr`	`uintptr` holds a pointer's raw bits
Aliases	`byte`, `rune`	aliases for `uint8` and `int32`
Floating point	`float32`, `float64`	IEEE 754
Complex	`complex64`, `complex128`	float32 or float64 real and imaginary parts

var i8 int8 = 127             // -128 to 127
var f64 float64 = 3.141592653589793
var c complex128 = 1 + 2i

s := "こんにちは"
runes := []rune(s) // Unicode code points
bytes := []byte(s) // raw bytes

// rune = int32 alias for a Unicode code point
var ch rune = '🐹'

Conversion and constants

i := 42
f := float64(i)              // Conversions are always explicit; no implicit coercion.
text := fmt.Sprintf("%d", i) // Number to string.
n, err := strconv.Atoi("123") // String to number.

const Pi = 3.14159

// iota: auto-incremented integer constant.
type Weekday int

const (
    Sunday Weekday = iota // 0
    Monday                // 1
    Tuesday               // 2
)

// Bit-flag pattern.
type Permission uint

const (
    Read    Permission = 1 << iota // 1
    Write                          // 2
    Execute                        // 4
)

Pointers

x := 10
p := &x  // Take the address of x.
*p = 20  // Dereference the pointer.
fmt.Println(x) // 20

p1 := new(int) // *int; the pointed-to value is 0.

// Go 1.26+: new accepts an expression as well as a type.
// This does not compile with Go 1.25 or earlier.
p2 := new(42)               // *int; the pointed-to value is 42.
p3 := new(Person{Name: "Alice"}) // *Person initialized with a literal.

Control flow

if

// An initialization statement is scoped to this if/else chain.
if err := doSomething(); err != nil {
    return fmt.Errorf("do something: %w", err)
}

if x > 0 {
    fmt.Println("positive")
} else if x < 0 {
    fmt.Println("negative")
} else {
    fmt.Println("zero")
}

for

// C-style loop.
for i := 0; i < 5; i++ {
}

// Go has no while keyword; use for instead.
for n > 0 {
    n--
}

// Infinite loop.
for {
    if done {
        break
    }
}

// range returns an index and a value for slices and arrays.
for i, v := range []int{10, 20, 30} {
    fmt.Println(i, v) // 0 10 / 1 20 / 2 30
}

// Discard the index.
for _, v := range slice {
}

// Strings range over Unicode code points (runes), not bytes.
for i, r := range "日本語" {
    fmt.Printf("%d: %c\n", i, r)
}

// Maps.
for k, v := range m {
    fmt.Println(k, v) // Iteration order is unspecified.
}

switch

// Expression switch (fallthrough requires an explicit keyword).
switch os := runtime.GOOS; os {
case "darwin":
    fmt.Println("macOS")
case "linux":
    fmt.Println("Linux")
default:
    fmt.Println("Other")
}

// Condition-less switch is a cleaner alternative to a long if-else chain.
switch {
case x > 100:
    fmt.Println("big")
case x > 10:
    fmt.Println("medium")
default:
    fmt.Println("small")
}

// Type switch: identify the dynamic type of an interface value.
func describe(i any) {
    switch v := i.(type) {
    case int:
        fmt.Printf("int: %d\n", v)
    case string:
        fmt.Printf("string: %q\n", v)
    default:
        fmt.Printf("unknown: %T\n", v)
    }
}

defer

defer schedules a call to run just before the surrounding function returns. Use it for cleanup: closing files, response bodies, mutexes, and contexts. Deferred calls run in LIFO order.

func writeFile(path string) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    defer f.Close() // Runs when writeFile returns, regardless of how.

    defer fmt.Println("third")
    defer fmt.Println("second")
    defer fmt.Println("first")
    // Prints: first, second, third.
    return nil
}

Note
Deferred call arguments are evaluated when defer is encountered. In a long-running loop, a deferred cleanup does not run until the function returns, so resources accumulate. Close them promptly or move the loop body into a helper function.

Functions

Basic

// Multiple return values.
func divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, errors.New("division by zero")
    }
    return a / b, nil
}

result, err := divide(10, 3)

// Named return values (useful as documentation for short functions).
func minMax(nums []int) (min, max int) {
    min, max = nums[0], nums[0]
    for _, n := range nums[1:] {
        if n < min {
            min = n
        }
        if n > max {
            max = n
        }
    }
    return // Naked return.
}

Variadic functions

func sum(nums ...int) int {
    total := 0
    for _, n := range nums {
        total += n
    }
    return total
}

sum(1, 2, 3)
nums := []int{1, 2, 3}
sum(nums...) // Spread a slice into variadic arguments.

First-class functions and closures

Functions are values in Go: you can assign them to variables, pass them as arguments, and return them. A closure captures variables from its surrounding scope and keeps them alive after the outer function returns.

// Assign a function to a variable.
add := func(a, b int) int { return a + b }

// Pass a function as an argument.
apply := func(f func(int, int) int, x, y int) int {
    return f(x, y)
}
fmt.Println(apply(add, 3, 4)) // 7

// This closure captures n.
func counter() func() int {
    n := 0
    return func() int {
        n++
        return n
    }
}

c := counter()
c() // 1
c() // 2

init

An init function runs automatically while a package is initialized, before main. A package may have more than one init function. Prefer explicit initialization in main for ordinary application setup; reserve init for package-level registration.

// Runs automatically at package initialization.
func init() {
    // Register a driver or handler.
}

Arrays, slices, and maps

Memory layout

Array (fixed length, value type)
┌───┬───┬───┬───┬───┐
│ 0 │ 1 │ 2 │ 3 │ 4 │  ← contiguous memory (placement decided by the compiler)
└───┴───┴───┴───┴───┘

Slice (variable-length view)
┌────────┬──────┬──────┐
│ ptr    │ len  │ cap  │  ← 3-word slice header
└────┬───┴──────┴──────┘
     ↓
┌───┬───┬───┬───┬───┬───┐
│ 0 │ 1 │ 2 │ 3 │   │   │  ← underlying array
└───┴───┴───┴───┴───┴───┘
     ↑           ↑
    len=4       cap=6

Note: actual placement (stack/heap) is decided by escape analysis.

Arrays

Arrays have a fixed length, and that length is part of their type: [3]int and [4]int are different types. Arrays are values, so assigning or passing one copies all its elements.

var a [3]int              // [0 0 0]
b := [3]int{1, 2, 3}
c := [...]int{4, 5, 6}   // Length inferred from the literal.

// Arrays are copied by value.
d := b
d[0] = 99 // b is unchanged.

Slices

A slice is a variable-length view over part or all of an underlying array. Unlike an array, its length is not part of its type. Assigning a slice copies only its header, so two slices may share elements.

// Create a slice.
s := []int{1, 2, 3}
s2 := make([]int, 5)     // len=5, cap=5
s3 := make([]int, 3, 10) // len=3, cap=10

// append may allocate a new backing array when cap is exceeded.
s = append(s, 4, 5)
s = append(s, []int{6, 7}...)

// Slicing shares the backing array.
sub := s[1:3]            // s[1] and s[2]; shares s's array.
limited := s[1:3:3]      // Third index limits the resulting cap.

// copy produces an independent slice.
clone := make([]int, len(s))
copy(clone, s)

// Delete element at index i while preserving order.
i := 2
s = append(s[:i], s[i+1:]...)

fmt.Println(len(s), cap(s))

Caution
A subslice shares its backing array with the original. Mutating one can mutate the other. Use copy when an independent slice is required.

Maps

Maps associate keys with values. Iteration order is unspecified. Keys must be comparable; slices, maps, and functions cannot be map keys.

// Create a map.
m := map[string]int{"a": 1, "b": 2}
m2 := make(map[string]int)

m["c"] = 3
delete(m, "a") // delete is a built-in function.

// Check for key existence.
v, ok := m["missing"] // ok is false when the key is absent.
if ok {
    fmt.Println(v)
}

// Iteration order is unspecified.
for k, v := range m {
    fmt.Println(k, v)
}

Caution
The zero value of a map is nil. Reading from a nil map is safe, but writing to one panics. Initialize it with make or a map literal first.

Structs, methods, and tags

Structs and embedding

type Person struct {
    Name string // Exported: accessible from other packages.
    Age  int
    addr string // Unexported: package-private.
}

// Named-field initialization (preferred).
p1 := Person{Name: "Alice", Age: 30}
p2 := new(Person) // *Person; all fields are zero values.

// Embedding promotes fields and methods.
type Employee struct {
    Person            // Fields and methods of Person are promoted.
    Department string
}

e := Employee{Person: Person{Name: "Carol", Age: 28}, Department: "Eng"}
fmt.Println(e.Name) // Transparent access to Person.Name.

// Go 1.27+: promoted fields can be used directly as literal keys.
e2 := Employee{Name: "Eve", Age: 32, Department: "Sales"}

Starting with Go 1.27, a struct literal key may be any valid field selector for the struct type. Here, Name and Age are promoted from the embedded Person field.

Methods

// Value receiver: p is a copy of the caller.
func (p Person) Greet() string {
    return "Hi, I'm " + p.Name
}

// Pointer receiver: can modify the original Person.
func (p *Person) Birthday() {
    p.Age++
}

p := Person{Name: "Dave", Age: 20}
p.Birthday()       // Go automatically passes &p.
fmt.Println(p.Age) // 21

When to use pointer receivers

The method needs to modify the receiver → pointer receiver.

The struct is large (avoid copy overhead) → pointer receiver.

Otherwise, either works.

Keep receiver kinds consistent across all methods of one type.

Struct tags

Struct tags are metadata attached to fields. The language does not interpret them; packages such as encoding/json and ORMs read them through reflection.

type User struct {
    ID    int    `json:"id" db:"user_id"`
    Email string `json:"email,omitempty"` // Omitted from JSON when empty.
}

// encoding/json reads tags through reflection.
data, _ := json.Marshal(User{ID: 1, Email: ""})
// → {"id":1}   (Email omitted by omitempty)

Interfaces

An interface defines a set of methods. A type satisfies an interface implicitly — no implements keyword. This lets code depend on behavior rather than a concrete type.

interface value layout (the internal representation is not part of the spec)

var s Shape = Circle{Radius: 5}

  s (interface value)
  ┌──────────────┬──────────────┐
  │  type info   │  value/ptr   │
  │  (Circle)    │  {Radius:5}  │
  └──────────────┴──────────────┘

  If either part is nil while the other is not, the interface value itself is not nil.
  (See nil interface trap in Tips.)

type Shape interface {
    Area() float64
    Perimeter() float64
}

type Circle struct{ Radius float64 }

func (c Circle) Area() float64      { return math.Pi * c.Radius * c.Radius }
func (c Circle) Perimeter() float64 { return 2 * math.Pi * c.Radius }

// Circle implicitly satisfies Shape.
var s Shape = Circle{Radius: 5}
fmt.Println(s.Area())

Type assertions and type switches

// Safe type assertion; the single-result form panics on failure.
c, ok := s.(Circle)
if ok {
    fmt.Println("radius:", c.Radius)
}

// any is an alias for interface{} (Go 1.18+).
func printAny(v any) {
    fmt.Printf("%T: %v\n", v, v)
}

Small interfaces used everywhere

// io.Reader and io.Writer are the most widely used interfaces in the stdlib.
type Reader interface { Read(p []byte) (n int, err error) }
type Writer interface { Write(p []byte) (n int, err error) }

// Implementing fmt.Stringer controls how fmt.Println prints a value.
type Stringer interface { String() string }

func (p Person) String() string {
    return fmt.Sprintf("%s (%d)", p.Name, p.Age)
}

fmt.Println(Person{Name: "Eve", Age: 22}) // Eve (22)

Errors

// error is a built-in interface: type error interface { Error() string }

f, err := os.Open("file.txt")
if err != nil {
    return fmt.Errorf("open file: %w", err) // %w wraps err for errors.Is/As.
}
defer f.Close()

Custom errors

type NotFoundError struct {
    Resource string
    ID       int
}

func (e *NotFoundError) Error() string {
    return fmt.Sprintf("%s (id=%d) not found", e.Resource, e.ID)
}

func findUser(id int) (*User, error) {
    if id <= 0 {
        return nil, &NotFoundError{Resource: "user", ID: id}
    }
    // ...
    return nil, nil
}

errors package

import "errors"

// Sentinel error for errors.Is comparisons.
var ErrNotFound = errors.New("not found")

func fetchUser(id int) (*User, error) {
    if id <= 0 {
        return nil, fmt.Errorf("fetchUser: %w", ErrNotFound) // Wrap with %w.
    }
    return nil, nil
}

_, err := fetchUser(-1) // fetchUser returns (*User, error); discard the value.

// errors.Is traverses the error chain to find a matching sentinel.
if errors.Is(err, ErrNotFound) {
    fmt.Println("not found")
}

// errors.As traverses the chain and extracts a value of the target type.
func findItem(id int) error {
    return fmt.Errorf("findItem: %w", &NotFoundError{Resource: "item", ID: id})
}

var nfe *NotFoundError
if errors.As(findItem(42), &nfe) {
    fmt.Println("resource:", nfe.Resource) // "item"
}

// Go 1.26+: a type-safe generic alternative to errors.As.
if nfe, ok := errors.AsType[*NotFoundError](findItem(42)); ok {
    fmt.Println("resource:", nfe.Resource) // "item"
}

// errors.Join combines multiple errors into one (Go 1.20+).
err1 := errors.New("err1")
err2 := errors.New("err2")
combined := errors.Join(err1, err2)

panic and recover

Use panic for broken program invariants or truly unrecoverable situations; return error for expected failures. recover only works when called directly from a deferred function.

func mustPositive(n int) int {
    if n <= 0 {
        panic(fmt.Sprintf("must be positive, got %d", n))
    }
    return n
}

func safeDiv(a, b int) (result int, err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("recovered: %v", r)
        }
    }()
    return a / b, nil
}

Goroutines, channels, and synchronization

GMP model (Go runtime scheduler)

G = Goroutine (lightweight thread; initial stack ~2 KB, grows as needed)
M = OS thread
P = Processor (controlled by GOMAXPROCS)

  P1                P2
  ┌────────────┐   ┌────────────┐
  │ G1 running │   │ G3 running │
  │ ┌────────┐ │   │ ┌────────┐ │
  │ │ G2     │ │   │ │ G4     │ │ ← local run queue
  │ │ G5     │ │   └────────────┘
  └────────────┘
       M1               M2        ← OS threads

Goroutines

// go keyword: start a function concurrently.
go func() {
    fmt.Println("goroutine")
}()

// Wait for goroutines to finish.
var wg sync.WaitGroup
for i := 0; i < 5; i++ {
    wg.Add(1)
    go func(n int) {
        defer wg.Done()
        fmt.Println(n)
    }(i) // Pass i as an argument to avoid closure capture issues.
}
wg.Wait()

Channels

ch := make(chan int)       // Unbuffered: send blocks until a receiver is ready.
bch := make(chan int, 10)  // Buffered: send blocks only when the buffer is full.

// Unbuffered: send and receive must be in separate goroutines.
go func() { ch <- 42 }()
v := <-ch

// Buffered: send and receive can be in the same goroutine within capacity.
bch <- 1
bch <- 2
fmt.Println(<-bch, <-bch) // 1 2

// Receiving from a closed, drained channel returns (zero, false).
v, ok := <-ch // ok is false when the channel is closed and empty.

// range receives values until the channel is closed and drained.
ch2 := make(chan int, 3)
ch2 <- 1; ch2 <- 2; ch2 <- 3
close(ch2) // The sender closes the channel.
for v := range ch2 {
    fmt.Println(v) // 1, 2, 3
}

Channel direction

// Directional types make intent explicit and catch mistakes at compile time.
func producer(ch chan<- int) { // Send-only.
    for i := 0; i < 5; i++ {
        ch <- i
    }
    close(ch)
}

func consumer(ch <-chan int) { // Receive-only.
    for v := range ch {
        fmt.Println(v)
    }
}

ch := make(chan int)
go producer(ch)
consumer(ch)

select

// select waits on multiple channel operations simultaneously.
// It picks one ready case at random when several are ready.
select {
case v := <-ch1:
    fmt.Println("ch1:", v)
case v := <-ch2:
    fmt.Println("ch2:", v)
case ch3 <- data:
    fmt.Println("sent to ch3")
case <-time.After(1 * time.Second):
    fmt.Println("timeout")
default:
    fmt.Println("no channel ready") // Non-blocking.
}

sync and atomic

// Mutex: protect shared state from concurrent access.
var mu sync.Mutex
var count int

mu.Lock()
count++
mu.Unlock()

// RWMutex: more efficient when reads are much more frequent than writes.
var rw sync.RWMutex
rw.RLock()  // Multiple goroutines can read simultaneously.
// ... read ...
rw.RUnlock()

// Once: run an initialization function exactly once.
var once sync.Once
once.Do(func() { /* called only the first time */ })

// atomic: low-overhead operations for simple counters and flags.
var n atomic.Int64
n.Add(1)
fmt.Println(n.Load())

Avoid goroutine leaks
When a goroutine sends on a channel, always give it a way to stop if the receiver exits early.

select {
case ch <- result:
case <-ctx.Done(): // Exit when the caller cancels.
    return
}

Context

Context tree

context.Background()
    └── WithCancel → ctx, cancel
            └── WithTimeout(ctx, 5s) → ctx2, cancel2
                    └── WithValue(ctx2, key, val) → ctx3
                                    ↓
                       Cancellation and deadlines propagate to child contexts.

Use context.Context to propagate deadlines, cancellation, and request-scoped metadata. Call the returned cancel function even when a timeout will eventually fire.

import "context"

// Timeout context.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel() // Always call cancel to release resources.

req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.com", nil)
if err != nil {
    return err
}

resp, err := http.DefaultClient.Do(req)
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        fmt.Println("timeout")
    }
    return err
}
defer resp.Body.Close()

// Cancellable context.
ctx2, cancel2 := context.WithCancel(context.Background())
go func() {
    <-ctx2.Done() // Block until cancelled.
    fmt.Println("cancelled:", ctx2.Err())
}()
cancel2()

// context.WithValue carries request-scoped metadata.
// Use it only for small amounts of data; never as a substitute for function parameters.
type ctxKey string
const userKey ctxKey = "user"

ctx3 := context.WithValue(context.Background(), userKey, "alice")
user, ok := ctx3.Value(userKey).(string) // Type-assert with an ok check.

Generics

Go 1.18 introduced type parameters for reusable, type-safe code.

Type parameters

// T and U can be any type.
func Map[T, U any](s []T, f func(T) U) []U {
    result := make([]U, len(s))
    for i, v := range s {
        result[i] = f(v)
    }
    return result
}

doubled := Map([]int{1, 2, 3}, func(n int) int { return n * 2 })
// [2 4 6]

Type constraints

import "cmp"

// cmp.Ordered allows <, >, ==  (int, float64, string, etc.).
func Min[T cmp.Ordered](a, b T) T {
    if a < b {
        return a
    }
    return b
}

Min(3, 5)       // 3 (int)
Min(3.14, 2.71) // 2.71 (float64)
Min("b", "a")   // "a" (string)

// Custom constraint with ~ for underlying types.
type Number interface {
    ~int | ~int64 | ~float64
}

func Sum[T Number](nums []T) T {
    var total T
    for _, n := range nums {
        total += n
    }
    return total
}

Generic types

type Stack[T any] struct {
    items []T
}

func (s *Stack[T]) Push(v T) {
    s.items = append(s.items, v)
}

func (s *Stack[T]) Pop() (T, bool) {
    if len(s.items) == 0 {
        var zero T
        return zero, false // Return the zero value of T.
    }
    v := s.items[len(s.items)-1]
    s.items = s.items[:len(s.items)-1]
    return v, true
}

s := Stack[string]{}
s.Push("Go")
s.Push("Generics")
v, _ := s.Pop() // "Generics"

Generic methods (Go 1.27+)

Starting with Go 1.27, a method can declare its own type parameters. This lets an operation associated with a type work with multiple argument types.

type Converter struct{}

func (Converter) Convert[T any](v T) T {
    return v
}

c := Converter{}
n := c.Convert(42)       // T = int
s := c.Convert("hello") // T = string

Interface methods cannot declare type parameters, and a generic method cannot implement an interface method.

Generic function inference (Go 1.27+)

Type arguments can now be inferred from the destination function type in assignments, conversions, composite literals, and channel sends.

func Stringify[T any](v T) string {
    return fmt.Sprint(v)
}

type IntFormatter func(int) string

var format IntFormatter = Stringify
formatters := []IntFormatter{Stringify}

ch := make(chan IntFormatter, 1)
ch <- Stringify

Iterators

Since Go 1.23, a function returning iter.Seq can be ranged over directly. When the caller breaks early, yield returns false so the producer can stop.

import "iter"

// Backward yields n-1 through 0.
func Backward(n int) iter.Seq[int] {
    return func(yield func(int) bool) {
        for i := n - 1; i >= 0; i-- {
            if !yield(i) { // Caller broke out of the loop.
                return
            }
        }
    }
}

for i := range Backward(3) {
    fmt.Println(i) // 2, 1, 0
}

// maps.Keys returns an iter.Seq; slices.Collect converts it to a slice.
keys := slices.Collect(maps.Keys(m))

Testing

// Place tests in xxx_test.go files.
package mypackage_test

import (
    "testing"

    "github.com/yourname/yourproject/mypackage"
)

func TestAdd(t *testing.T) {
    got := mypackage.Add(2, 3)
    if got != 5 {
        t.Errorf("Add(2, 3) = %d; want 5", got)
    }
}

// Table-driven tests are the idiomatic Go pattern.
func TestDivide(t *testing.T) {
    tests := []struct {
        name    string
        a, b    float64
        want    float64
        wantErr bool
    }{
        {"normal", 10, 2, 5, false},
        {"division by zero", 10, 0, 0, true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := mypackage.Divide(tt.a, tt.b)
            if (err != nil) != tt.wantErr {
                t.Errorf("unexpected error: %v", err)
            }
            if got != tt.want {
                t.Errorf("got %v, want %v", got, tt.want)
            }
        })
    }
}

// Benchmark: run with go test -bench=.
func BenchmarkAdd(b *testing.B) {
    b.ReportAllocs() // Report memory allocations per operation.
    for i := 0; i < b.N; i++ {
        mypackage.Add(2, 3)
    }
}

Test helpers

// t.Helper makes failures report the caller's line, not the helper's.
func requireNoError(t *testing.T, err error) {
    t.Helper()
    if err != nil {
        t.Fatal(err)
    }
}

func TestWriteFile(t *testing.T) {
    t.Setenv("APP_ENV", "test") // Restored automatically after the test.
    dir := t.TempDir()           // Deleted automatically after the test.
    t.Cleanup(func() {
        // Register arbitrary cleanup: reset mocks, close clients, etc.
    })

    path := filepath.Join(dir, "output.txt")
    requireNoError(t, os.WriteFile(path, []byte("hello"), 0o644))
}

go test ./...          # Run all tests.
go test -race ./...    # Detect data races.
go test -cover ./...   # Show coverage.

Standard-library quick reference

fmt

// Output.
fmt.Print("no newline")
fmt.Println("with newline")
fmt.Printf("formatted %s %d %v\n", "str", 42, true)
fmt.Fprintf(os.Stderr, "error: %v\n", err)

// Build strings.
s := fmt.Sprintf("Hello, %s!", name)
msg := fmt.Errorf("wrap: %w", err)

// Common format verbs.
// %v   default             %+v  struct with field names  %#v  Go syntax
// %T   type name           %d   decimal integer          %f   floating-point
// %s   string              %q   quoted string            %x   hexadecimal
// %p   pointer address     %b   binary                   %e   exponent

strings

import "strings"

strings.Contains("Hello", "ell")                    // true
strings.HasPrefix("Hello", "He")                    // true
strings.HasSuffix("Hello", "lo")                    // true
strings.Count("cheese", "e")                        // 3
strings.Index("Hello", "ll")                        // 2
strings.Replace("oink oink", "oink", "moo", 1)     // "moo oink"
strings.ReplaceAll("oink oink", "oink", "moo")      // "moo moo"
strings.ToUpper("hello")                            // "HELLO"
strings.ToLower("HELLO")                            // "hello"
strings.TrimSpace("  hello  ")                      // "hello"
strings.Trim("##hello##", "#")                      // "hello"
strings.Split("a,b,c", ",")                         // ["a" "b" "c"]
strings.Join([]string{"a", "b"}, "-")               // "a-b"
strings.Fields("a  b\tc")                           // ["a" "b" "c"]

// strings.Builder is efficient for repeated concatenation in a loop.
// A plain + is fine for a small number of concatenations.
var sb strings.Builder
for i := 0; i < 5; i++ {
    fmt.Fprintf(&sb, "%d", i)
}
sb.String() // "01234"

strconv

import "strconv"

strconv.Itoa(42)                       // "42"
strconv.Atoi("42")                     // 42, nil
strconv.ParseFloat("3.14", 64)         // 3.14, nil
strconv.FormatFloat(3.14, 'f', 2, 64)  // "3.14"
strconv.ParseBool("true")              // true, nil
strconv.FormatBool(true)               // "true"

sort and slices

import "sort"

nums := []int{5, 2, 4, 1, 3}
sort.Ints(nums)                              // [1 2 3 4 5]

words := []string{"b", "a", "c"}
sort.Strings(words)

// Custom sort.
sort.Slice(nums, func(i, j int) bool {
    return nums[i] > nums[j] // Descending.
})

import (
    "cmp"
    "slices"
)

slices.Sort(nums)                                            // Ascending.
idx, found := slices.BinarySearch(nums, 3)                  // Requires sorted input.

// cmp.Compare avoids integer overflow in comparison functions.
slices.SortFunc(nums, func(a, b int) int { return cmp.Compare(b, a) }) // Descending.

maps (Go 1.21+)

import (
    "maps"
    "slices"
)

m := map[string]int{"a": 1, "b": 2}
m2 := maps.Clone(m)        // Shallow copy.
maps.Copy(m2, m)            // Copy all entries from m into m2.
delete(m, "a")              // delete is a built-in function.
keys := slices.Collect(maps.Keys(m)) // Collect keys into a slice.

time

import "time"

now := time.Now()
t := time.Date(2026, 6, 1, 12, 0, 0, 0, time.Local)

// Go uses a reference time (Mon Jan 2 15:04:05 MST 2006) as the layout.
now.Format("2006-01-02 15:04:05")
now.Format(time.RFC3339)                      // "2026-06-22T12:00:00+09:00"
parsed, _ := time.Parse("2006-01-02", "2026-06-22")

later := now.Add(24 * time.Hour)
diff := later.Sub(now)     // time.Duration
fmt.Println(diff.Hours())  // 24.0

time.Sleep(100 * time.Millisecond)
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()

os and filepath

import (
    "os"
    "path/filepath"
)

// File I/O.
data, err := os.ReadFile("file.txt")
err = os.WriteFile("out.txt", data, 0644)

// Directory operations.
entries, _ := os.ReadDir(".")
for _, e := range entries {
    fmt.Println(e.Name(), e.IsDir())
}
os.MkdirAll("a/b/c", 0755)
os.Remove("file.txt")
os.RemoveAll("dir/")

// Environment variables.
home := os.Getenv("HOME")
os.Setenv("KEY", "value")

// Path manipulation.
filepath.Join("a", "b", "c")       // "a/b/c"
filepath.Base("/a/b/file.txt")      // "file.txt"
filepath.Dir("/a/b/file.txt")       // "/a/b"
filepath.Ext("file.txt")            // ".txt"
abs, _ := filepath.Abs("relative")  // Absolute path.

encoding/json

import "encoding/json"

type Point struct {
    X int `json:"x"`
    Y int `json:"y"`
}

// Encode.
data, err := json.Marshal(Point{X: 1, Y: 2})           // []byte
pretty, err := json.MarshalIndent(Point{X: 1}, "", "  ")

// Decode.
var p Point
err = json.Unmarshal(data, &p)

// Streaming.
enc := json.NewEncoder(os.Stdout)
enc.Encode(p)

dec := json.NewDecoder(os.Stdin) // Accepts any io.Reader.
dec.Decode(&p)

// When the type is unknown.
var v any
json.Unmarshal(data, &v)
m := v.(map[string]any)

`encoding/json/v2` (Go 1.27+)

encoding/json/v2 is a new JSON API whose behavior can be configured with options. It has stricter defaults than encoding/json, including rejecting invalid UTF-8 and duplicate names in JSON objects.

import jsonv2 "encoding/json/v2"

type Config struct {
    Port int `json:"port"`
}

data, err := jsonv2.Marshal(Config{Port: 8080})

var cfg Config
err = jsonv2.Unmarshal(
    data,
    &cfg,
    jsonv2.RejectUnknownMembers(true),
)

The existing encoding/json package remains supported, so migration to v2 is not required. Its existing API behavior is preserved, although error message text may change because of the new underlying implementation.

`uuid` (Go 1.27+)

import "uuid"

id := uuid.New()    // Use when no specific UUID version is required.
id7 := uuid.NewV7() // UUID v7 is convenient for chronological sorting.

parsed, err := uuid.Parse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6")
if err != nil {
    log.Fatal(err)
}

fmt.Println(id, id7, parsed)

uuid.MustParse panics on invalid input, so it is best suited to constants and tests.

net/http

import (
    "bytes"
    "context"
    "errors"
    "io"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
)

// Always set a timeout; the default client has none.
client := &http.Client{Timeout: 10 * time.Second}

// GET request.
resp, err := client.Get("https://example.com")
if err != nil {
    return err
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)

// Custom request with context.
req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(jsonData))
if err != nil {
    return err
}
req.Header.Set("Content-Type", "application/json")
resp2, err := client.Do(req)
if err != nil {
    return err
}
defer resp2.Body.Close()

// HTTP server with timeouts (required in production).
mux := http.NewServeMux()
mux.HandleFunc("GET /hello/{name}", func(w http.ResponseWriter, r *http.Request) {
    name := r.PathValue("name") // Path parameters (Go 1.22+).
    fmt.Fprintf(w, "Hello, %s!", name)
})

server := &http.Server{
    Addr:              ":8080",
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,
    ReadTimeout:       30 * time.Second,
    WriteTimeout:      30 * time.Second,
    IdleTimeout:       60 * time.Second,
}
go func() {
    if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
        log.Printf("server error: %v", err)
    }
}()

// Graceful shutdown on SIGINT / SIGTERM.
shutdownCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-shutdownCtx.Done()

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := server.Shutdown(ctx); err != nil {
    log.Printf("shutdown error: %v", err)
}

log/slog (Go 1.21+)

import "log/slog"

// Default logger writes text to stderr.
slog.Info("server started", "port", 8080)
slog.Error("request failed", "err", err)

// JSON handler for structured logging (e.g., cloud environments).
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelDebug,
}))
logger.Info("user logged in", "userID", 42, "ip", "127.0.0.1")
// {"time":"...","level":"INFO","msg":"user logged in","userID":42,"ip":"127.0.0.1"}

// Add fields shared across multiple log calls.
logger.With("requestID", "abc123").Info("processing")

Tips and common mistakes

Goroutine leak

// Bad: the goroutine blocks forever if no one receives from ch.
go func() {
    ch <- result
}()

// Good: always provide a cancellation path.
go func() {
    select {
    case ch <- result:
    case <-ctx.Done():
        return
    }
}()

nil interface trap

// Bad: even when *MyError is nil, the interface value is non-nil.
func getError() error {
    var err *MyError = nil
    return err // The returned error interface is non-nil!
}

if getError() != nil { // true — this branch is taken unexpectedly.
    fmt.Println("this prints unexpectedly")
}

// Good: return nil directly.
func getError() error {
    return nil
}

Pre-allocate slice capacity

// Bad: append may reallocate the backing array many times.
result := []int{}
for i := 0; i < 10000; i++ {
    result = append(result, i)
}

// Good: allocate the full capacity upfront.
result := make([]int, 0, 10000)
for i := 0; i < 10000; i++ {
    result = append(result, i)
}

for-loop variable capture (fixed in Go 1.22)

// Go 1.21 and earlier: all goroutines share the same i variable.
for i := 0; i < 5; i++ {
    go func() { fmt.Println(i) }() // May print 5 five times.
}

// Go 1.22+: each iteration creates a new i variable.
// The above code now correctly prints 0, 1, 2, 3, 4 in some order.

// Workaround for Go 1.21 and earlier.
for i := 0; i < 5; i++ {
    i := i // Shadow i with a new variable for this iteration.
    go func() { fmt.Println(i) }()
}

Modules and packages

# Initialize a module.
go mod init github.com/yourname/yourproject

# Go 1.27
go get go@1.27

go get github.com/some/package@v1.2.3   # Add a dependency.
go mod tidy                              # Remove unused dependencies.
go mod vendor                            # Vendor dependencies.
go build ./...                           # Build.
go test ./...                            # Test.
go test -race ./...                      # Detect data races.
go vet ./...                             # Static analysis.
go fmt ./...                             # Format.

DEV Community: Nobuo Miura

Rust CheatSheet

Table of Contents

Installation and updates

Program structure

Comments

Keywords

Strict keywords

Reserved keywords

Weak keywords

Variables, constants, and primitive types

Variable declarations

Shadowing

Constants and statics

Values and literals

Scalar types

Compound types

Type conversion

Type aliases and newtypes

Inspecting a type

Operators

Ownership, borrowing, and slices

Ownership

Borrowing and references

Slices

Lifetime overview

Control flow

if, if let, and let else

loop, while, and for

Loop labels

match

Functions and closures

Structs, unions, enums, and patterns

Structs and methods

Unions

Enums and Option

Collections and strings

Vec<T>

String and &str

Maps, sets, and queues

Error handling

Generics, traits, and lifetimes

Iterators

Smart pointers

Modules, packages, and visibility

Concurrency

Macros and attributes

Testing

Standard-library quick reference

Calling external functions: extern and FFI

unsafe Rust

Cargo and dependency management

Tips and common mistakes

Avoid reflexive clone

Prefer slices in read-only APIs

Use checked indexing for uncertain input

Remember that strings are UTF-8

Do not hold a synchronous mutex guard across .await

Document panics in public APIs

Keep warnings clean

Official references

Prompts Aren't Policies: I Built a Deterministic Tool Gate for Claude Code and Codex

nobuo-miura / PolicyApprovalGate

Deterministic, LLM-free PreToolUse guardrail for Claude Code and Codex CLI. Applies local policy to shell commands and supported file operations, with deny/ask decisions and audit logs.

PolicyApprovalGate

Features

Why I Built It

What Is PolicyApprovalGate?

What Does It Check?

Keeping Sensitive Data Out of the Agent Context

Deny Rules and Confirmation Rules

File Tools and Codex apply_patch

Install and Try It Without Running a Command

Register It with Claude Code and Codex CLI

How It Fits with Claude Code's Native Deny Rules

Limitations

Closing

nobuo-miura / PolicyApprovalGate

Deterministic, LLM-free PreToolUse guardrail for Claude Code and Codex CLI. Applies local policy to shell commands and supported file operations, with deny/ask decisions and audit logs.

PolicyApprovalGate

`if`, `if let`, and `let else`

`loop`, `while`, and `for`

`match`

Enums and `Option`

`Vec<T>`

`String` and `&str`

Calling external functions: `extern` and FFI

`unsafe` Rust

Avoid reflexive `clone`

Do not hold a synchronous mutex guard across `.await`

About `rua` (Report Destination)

A Note on `adkim=s` / `aspf=s` (strict)