Skip to content

quick-start.md

Latest commit

 

History

History
202 lines (143 loc) · 6.54 KB

quick-start.md

File metadata and controls

202 lines (143 loc) · 6.54 KB
Raw

Quick Start Guide (5 Minutes)

Get started with msr, nin, and vscode-msr aliases in under 5 minutes.

Want comprehensive documentation? See msr User Guide, nin User Guide, vscode-msr User Guide.

Looking for download links? See Download Links.

Table of Contents

Installation

Option A: VS Code Extension (Recommended)

Install vscode-msr — it auto-downloads both msr and nin and sets up all aliases.

Option B: Manual Download

Download the single binary for your platform — see Download Links. No dependencies, no installer — just download and run.

Platform Architecture Tool
Windows x86_64, x86_32, Arm64 msr.exe, nin.exe (MinGW); Cygwin uses msr.cygwin, nin.cygwin
Linux x86_64, x86_32, Arm64 msr, nin
macOS Arm64 msr, nin
FreeBSD x86_64 msr, nin

Choose Your First Tool (30 Seconds)

Use this decision table to start from the most practical entry point:

If your immediate goal is... Start with Why
Search/replace text in files msr Most direct workflow with preview-by-default
Dedup / diff / top distribution nin Native set operations and Pareto analysis
Code search in VS Code with minimal setup gfind-xxx aliases Git-scoped, low-noise shortcuts 
# Search/replace first
msr -rp . -f "\.cs$" -t "\bOldSymbol\b" -o "NewSymbol"

# Set analysis first
nin error.log nul "(\w+Exception)" -pd --sum -H 10

# VS Code alias first (gfind-small covers all file types ≤1.6MB)
gfind-small -t "\bTODO\b"

msr in 2 Minutes — Search and Replace

Search Files

# Search for "TODO" in all code files recursively
msr -rp . -f "\.(cs|py|js)$" -x "TODO" -c

# Search with regex pattern, ignore case
msr -rp . -f "\.log$" -it "error|warning|exception"

# List only matching file paths
msr -rp . -f "\.config$" -x "password" -l

# Get clean output (no path prefix, no color; keeps summary on stderr)
msr -rp . -f "\.txt$" -x "keyword" -PIC

Replace Text (Preview First)

# Step 1: Preview (default — no -R, no file changes)
msr -rp . -f "\.cs$" -t "\bOldSymbol\b" -o "NewSymbol"

# Step 1b: Preview changes only (show ONLY lines that actually change)
msr -rp . -f "\.cs$" -t "\bOldSymbol\b" -o "NewSymbol" -j

# Step 2: Apply with backup (-R = replace, -K = backup)
msr -rp . -f "\.cs$" -t "\bOldSymbol\b" -o "NewSymbol" -RK

Key safety features:

  • Preview by default — without -R, nothing is written
  • Skip-write if unchanged — files with identical content are NOT written
  • Backup with -K — timestamp-named backup, collision-proof

Common Output Flags

Flags Meaning (msr) Use Case
-PIC No path, no extra info, no color (keeps summary) Scripts and piping
-C No color (keeps path + summary) Alias output for agents
-c Show command Debug your command
-l List files (with match count) Get matching file paths
-j Changes only See what would change
-H N -J Stop after N matches Fast existence check

⚠️ Note: -P and -I have different meanings in msr vs nin. See Parameter Semantic Differences for the full comparison.

nin in 1 Minute — Set Operations and Distribution

# Unique lines (dedup)
nin file.txt nul -u

# Frequency distribution (like SQL GROUP BY + ORDER BY COUNT DESC)
nin file.txt nul "(\w+)" -pd

# Top 10 with cumulative percentage (Pareto analysis)
nin file.txt nul "(\w+)" -pd --sum -H 10

# Set difference: lines in file1 not in file2
nin file1.txt file2.txt "^(\S+)"

# Set intersection: lines in both files
nin file1.txt file2.txt "^(\S+)" -m

Key features:

  • No pre-sorting required (unlike comm or uniq)
  • Regex key extraction via capture groups
  • Cumulative Pareto analysis with --sum

vscode-msr Aliases in 1 Minute

After installing the vscode-msr extension, open a terminal in VS Code:

# Search Python files
gfind-py -t "\bTargetSymbol\b"

# Search across all file types (≤1.6MB, safe broad search)
gfind-small -t "\bTODO\b"

# Find class definitions
gfind-cs-def MyClass

# Find references
gfind-java-ref myMethod

# Discover available aliases
find-alias keyword

Three scope levels:

  • find-xxx — recursive directory traversal (-rp .)
  • gfind-xxx — git-tracked files only (faster for small repos)
  • rgfind-xxx — cross-repository search

msr + nin Together

# Search → Analyze: find errors, then get distribution
msr -rp logs/ -f "\.log$" -t "(\w+Exception)" -PIC | nin nul "(\w+Exception)" -pd --sum -H 20

# Extract → Dedup: extract values, then deduplicate
msr -rp . -f "\.yaml$" -t "image:\s+(\S+)" -o "\1" -PIC | nin nul "(\S+)" -ui

# Sort logs from multiple files by timestamp
msr -rp logs/ -f "\.log$" -F "\d{4}-\d{2}-\d{2}\D\d+:\d+:\d+[\.,]?\d*"

What's Next?

Goal Document
Learn msr in depth msr User Guide
Learn nin in depth nin User Guide
Learn vscode-msr aliases vscode-msr User Guide
See real-world examples Use Cases and Comparisons
Compare with other tools Tool Comparisons
Optimize performance Performance Tuning
Use with AI agents AI Agent Usage Guide
Environment, encoding & colors msr and nin Shared Reference
Download for your platform Download Links