SchemaSpy is my preferred tool for generating browsable HTML docs and ER diagrams from SQL databases. I’ve already shown how to configure it with SQLite, but SQL Server’s LocalDB edition introduces a completely different set of quirks.

LocalDB is a lightweight SQL Server runtime used by tools like Lansweeper and Visual Studio. Unlike full SQL Server or Express, which run as services and listen on TCP, LocalDB doesn’t accept TCP connections at all. It only exposes a named pipe endpoint, and it only works with Windows integrated authentication (NTLM/SSPI).

That’s why most SchemaSpy guides skip LocalDB entirely — Microsoft’s official JDBC driver expects TCP, and Java has no built-in NTLM support. The workaround is to use the older jTDS driver, which still supports named pipes, plus its companion ntlmauth.dll for NTLM authentication.

After a lot of trial and error, I found a reliable combination: SchemaSpy 6.1.0 + jTDS 1.3.3 + ntlmauth.dll + Graphviz 2.38. It’s fiddly, but once you have the pieces in place, you can generate a complete HTML schema doc site for any LocalDB-backed application.

The Pieces You Need

Heads-up Microsoft’s official JDBC driver cannot connect to LocalDB — it only works over TCP. That’s why jTDS is required.

Suggested Setup (Windows)

Keep everything SchemaSpy needs in one folder so paths are consistent:

C:\bin\SchemaSpy\
  schemaspy-6.1.0.jar     # SchemaSpy itself
  jtds-1.3.3.jar          # JDBC driver
  ntlmauth.dll            # From jTDS zip, for Windows SSO

Install Graphviz to its default location:

C:\Program Files (x86)\Graphviz2.38\

Important About ntlmauth.dll
The jTDS 1.3.3 zip includes three versions:

• x86\ntlmauth.dll → use if you run 32-bit Java
• x64\ntlmauth.dll → use if you run 64-bit Java (most common today)
• ia64\ntlmauth.dll → legacy Itanium, almost never needed

Copy the correct DLL into your C:\bin\SchemaSpy\ folder. When running SchemaSpy, add:

-Djava.library.path="C:\bin\SchemaSpy"

If the bitness doesn’t match, you’ll see UnsatisfiedLinkError or “Login failed” errors.

Step 1: Find the LocalDB Instance Pipe

LocalDB doesn’t have a fixed hostname like localhost,1433. Instead, every time it starts, Windows assigns it a unique named pipe. That pipe is what jTDS connects to.

To check the pipe, open PowerShell or Command Prompt on Windows (on the same machine that’s running LocalDB) and run:

SqlLocalDB start LSInstance
SqlLocalDB info  LSInstance

This will print details about the LocalDB instance, including the Instance pipe name. For example:

np:\\.\pipe\LOCALDB#SH964109\tsql\query

The important part is the instance token (LOCALDB#SH964109). You’ll pass that value into SchemaSpy with:

-instance "LOCALDB#SH964109"

Heads-up: The token changes every time LocalDB restarts. If SchemaSpy suddenly stops connecting, rerun SqlLocalDB info to grab the updated string.

Step 2: Authentication Options

SQL Server supports two authentication modes, but only one works with LocalDB:

• Windows Integrated (SSO)
  LocalDB uses Windows credentials instead of SQL usernames. The account that runs SchemaSpy must be a Windows user who has been granted access to the database.

  By default, this is the same account that installed or created the LocalDB instance (for example, the Windows user who installed Lansweeper). If you run SchemaSpy as a different user — even another local admin — you may get Login failed for user until that account is explicitly added as a login in SQL Server Management Studio.

  To make NTLM authentication work in Java, you also need ntlmauth.dll from the jTDS package. Without it, SchemaSpy will fail to authenticate even if the Windows account has access.

• SQL Login (username/password)
  This works on full SQL Server or Express, where TCP/IP is enabled and you can create dedicated logins. LocalDB does not allow this mode out of the box, so you can’t rely on -u/-p against a stock LocalDB instance.

Step 3: The Working Command

With SchemaSpy, jTDS, and Graphviz in place, you’re ready to run the actual command. This is where everything comes together.

Important SchemaSpy appends \bin\dot to whatever you provide via -gv. Always pass the Graphviz install root folder, not the path to dot.exe.

Option 1: Windows Integrated Authentication (SSO)

This is the normal way to connect to LocalDB. SchemaSpy will log in as the Windows account you’re running under (make sure that account has database access). You also need ntlmauth.dll and -Djava.library.path.

If you’re running from cmd.exe:

java -Djava.library.path="C:\bin\SchemaSpy" -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" ^
  -t mssql-jtds-instance ^
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" ^
  -host . ^
  -instance "LOCALDB#SH964109" ^
  -db lansweeperdb ^
  -s dbo ^
  -sso ^
  -connprops "namedPipe\=true" ^
  -o "C:\bin\SchemaSpy\output" ^
  -gv "C:\Program Files (x86)\Graphviz2.38"

If you’re running from PowerShell:

java -Djava.library.path="C:\bin\SchemaSpy" -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" `
  -t mssql-jtds-instance `
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" `
  -host . `
  -instance "LOCALDB#SH964109" `
  -db lansweeperdb `
  -s dbo `
  -sso `
  -connprops "namedPipe\=true" `
  -o "C:\bin\SchemaSpy\output" `
  -gv "C:\Program Files (x86)\Graphviz2.38"

Heads-up Use ^ in Command Prompt and ` (backtick) in PowerShell. Mixing them up will cause errors like '-t' is not recognized as an internal or external command.

Option 2: SQL Login (if one exists in LocalDB)

Some applications (like Lansweeper) create a SQL login inside LocalDB (lansweeperuser). If such a login exists, you can use it with -u/-p instead of SSO. The continuation rules are the same as above.

java -jar "C:\bin\SchemaSpy\schemaspy-6.1.0.jar" ^
  -t mssql-jtds-instance ^
  -dp "C:\bin\SchemaSpy\jtds-1.3.3.jar" ^
  -host . ^
  -instance "LOCALDB#SH964109" ^
  -db lansweeperdb ^
  -s dbo ^
  -u lansweeperuser -p "SuperSecret" ^
  -connprops "namedPipe\=true" ^
  -o "C:\bin\SchemaSpy\output" ^
  -gv "C:\Program Files (x86)\Graphviz2.38"

Note If no SQL login exists in your LocalDB instance, this will fail with Login failed for user. In that case, you must use SSO.

Flag Breakdown

• -t mssql-jtds-instance → use the jTDS SQL Server driver profile.
• -dp → path to the jTDS JAR file.
• -host . + -instance "LOCALDB#..." → connect via the LocalDB named pipe.
• -db lansweeperdb → database name to document.
• -s dbo → schema to include (typically dbo).
• -sso → use Windows integrated authentication.
• -u/-p → alternative, if a SQL login exists.
• -connprops "namedPipe=true" → critical: forces jTDS to use named pipes instead of TCP.
• -gv "<GraphvizRoot>" → Graphviz install root (SchemaSpy appends \bin\dot).
• -o → output directory for the generated site.

What Normal Output Looks Like

SchemaSpy is chatty. A successful run doesn’t just say “Connected” — you’ll see:

• ASCII-art SchemaSpy banner and license text.
• Warnings about restricted methods (expected with jTDS + modern Java).
• A line like:

  INFO  - Connected to Microsoft SQL Server - 16.00.xxxx
  

• Long “Gathering schema details…” progress lines with dots.
• Occasional warnings about sysproperties (safe to ignore — SQL Server 2016+ removed it).
• Graphviz messages about “graph is too large for cairo-renderer” with scaling (also safe).
• A final summary like:

  Wrote relationship details of 1274 tables/views to directory 'C:\bin\SchemaSpy\output'
  View the results by opening C:\bin\SchemaSpy\output\index.html
  

The key thing to look for is that output files get written and you see a final “View the results…” line. Everything else (warnings, scaling errors, missing comments) is normal noise.

The output directory will contain a full HTML site with:

• index.html → overview page
• tables/ → per-table pages
• columns/ → per-column detail pages
• relationships/ → ER diagrams (static images + clickable maps)

Open index.html in your browser to start exploring.

Why This Works

• SchemaSpy 6.1.0 preserves working integration with mssql-jtds-instance.
• jTDS 1.3.3 supports named pipes and Windows SSO (critical for LocalDB).
• -connprops "namedPipe=true" routes through the LocalDB pipe.
• Graphviz 2.38 is the last hassle-free version for SchemaSpy 6.x.
• ntlmauth.dll provides NTLM/SSPI so SSO works from Java.

Troubleshooting Matrix

Even with the right jars and flags, LocalDB is fiddly. Here’s a quick reference for the most common errors and how to resolve them:

Links & Stuff

• SchemaSpy
  📥 SchemaSpy v6.1.0 JAR (GitHub)
  SchemaSpy Documentation

• jTDS JDBC Driver (1.3.3)
  📥 Download jTDS 1.3.3 (SourceForge)
  Archived jTDS project site

• Graphviz (2.38 for Windows)
  📥 Graphviz 2.38 Windows installer (archive)
  Graphviz site & docs

• SQL Server LocalDB
  Microsoft Docs – SQL Server Express LocalDB

• SQL Server Management Studio (SSMS)
  📥 Download SSMS (Microsoft)
  Handy for browsing your LocalDB, verifying database names (e.g. lansweeperdb), and checking which logins exist.

(For long-term use, consider mirroring the required JARs and DLLs internally so your team isn’t chasing archive sites years later.)

Conclusion

LocalDB’s named-pipe-only quirk trips up the usual JDBC approach. The dependable combo is:

SchemaSpy 6.1.0  +  jTDS 1.3.3  +  -connprops "namedPipe=true"  +  Graphviz 2.38

With that in place — and the LocalDB instance pipe refreshed as needed — you’ll get clean, searchable HTML docs and ERDs for any LocalDB-backed app (e.g. Lansweeper, Visual Studio projects).

If you run into an edge case I didn’t cover, send it my way feedback@adminjitsu.com and I’ll expand the troubleshooting matrix.

Tcpdump is the Swiss Army knife of packet capture. It’s lean, scriptable, and ships with almost every Unix-like system. That makes it ideal for automation, troubleshooting, or handing to a customer when you need a reproducible capture without walking them through a GUI.

Most people analyze captures in something like Wireshark, a solid open-source packet analyzer. But tcpdump is often the better tool for actually collecting the data in the first place since it can be scripted, shared as a one-liner, and run with minimal instructions.

Packet captures are rarely trivial though: they can result in big files, require various permissions, approvals, and scheduled maintenance windows. They’re not something you want to repeat needlessly. The goal is to get it right the first time .

Where to Capture?

Before worrying about command flags, it helps to think about point of view you need to target. Packet captures are always relative. What you see depends on where you’re listening from.

If you’re debugging a client/server exchange, you could capture on the client to confirm whether requests are leaving, or on the server to see if they arrive. Sometimes you need both perspectives: one to prove the client sent the packet, the other to prove the server received it (or didn’t).

The network itself matters too. On a flat LAN or broadcast domain, a capture may show you traffic between many hosts. But on a switched or routed network, you’ll only see packets destined to or from the machine you’re capturing on. That’s why capturing on the endpoint itself is often the simplest, most reliable approach.

For complex problems, it’s common to gather multiple captures — one at the client, one at the server, perhaps one taken at a switch or router. When you line them up by timestamp, you can follow the packet’s journey across the path and pinpoint where things break down.

Once you know where you need to capture from, you can follow a simple workflow:

• Start capture
• Start Repro (it’s really helpful to take notes and record the time you start, when you notice a behavior or error etc)
• Stop capture
• Analyze in Wireshark or a similar tool

Choosing the Right Interface

Once you know where you want to capture from you’ll need to choose the correct interface. This varies by system but typically you want Ethernet or Wi-fi. On modern systems, there can be a lot of interfaces for things like VPN tunnels, virtual intefaces and so on.

List available interfaces with:

tcpdump -D

On my system i get this potentially confusing list:

1.loopback0 [Up, Running, Connected]
2.eth2 [Up, Running, Connected]
3.eth0 [Up, Running, Connected]
4.any (Pseudo-device that captures on all interfaces) [Up, Running]
5.lo [Up, Running, Loopback]
6.docker0 [Up, Disconnected]
7.bluetooth-monitor (Bluetooth Linux Monitor) [Wireless]
8.nflog (Linux netfilter log (NFLOG) interface) [none]
9.nfqueue (Linux netfilter queue (NFQUEUE) interface) [none]
10.dbus-system (D-Bus system bus) [none]
11.dbus-session (D-Bus session bus) [none]
12.eth1 [none, Disconnected]
13.eth3 [none, Disconnected]
14.eth4 [none, Disconnected]

Most of these aren’t very interesting, like loopback, D-Bus, netfilter hooks etc. You typically want your Ethernet or Wi-Fi interface (the eth0, eth2.. interfaces in my list. You might see ens33 or wlan0 or en0 on yours).

You can get a more helpful list with a simple filter on the interface flags:

tcpdump -D | grep Connected

That returns a much more reasonable list although loopback is always a valid connected interface so it remains:

└─$ tcpdump -D | grep Connected
1.loopback0 [Up, Running, Connected]
2.eth2 [Up, Running, Connected]
3.eth0 [Up, Running, Connected]

You usually won’t be interested in loopback so that leaves two ethernet connections to choose from. If you’re not sure, you can usually just check to see which one has the ip address you want to capture on:

ifconfig eth0

On a lot of newer linuxes, the command is:

ip addr show eth0

If it’s still not clear, you can check to see which of the interfaces is “busy” and take a peek at the traffic. To check an interface you can grab a quick capture with:

sudo tcpdump -i eth0 -c 20

On my system, both eth0 and eth2 are active but within seconds of watching tcpdump on eth2 i could recognize familiar ips and dns names from my lan.

Gathering a Solid Capture

Now that you’ve thought about where to capture and how to focus your test, the next step is setting up tcpdump to record everything you need without losing detail.

Save to a File

For later analysis in Wireshark or another tool, always write to a .pcap:

sudo tcpdump -i eth0 -s 0 -w capture.pcap

• -s 0 → capture the entire packet, not just the default snap length.
• -w → write raw packets to a file (not human-readable).
• Use Ctrl+C to stop when you’ve got enough.

Quick Checks

Sometimes you only need a small slice:

sudo tcpdump -i eth0 -s 0 -c 500 -w sample.pcap

• -c stops after N packets.
• Great for reproducible test runs.

Reading It Back

To verify or skim without Wireshark:

tcpdump -r capture.pcap

Pro Tips

• Always run with sudo (or root).
• Watch disk space — captures grow quickly.
• Time matters: make sure your system clock is accurate for useful logs.

Capturing Mobile Traffic

Both iOS and Android expose interfaces that tcpdump can hook into from a computer. In both cases you’ll need the device plugged in with a USB cable.

iOS (macOS host required)

On macOS, Apple provides a Remote Virtual Interface (RVI) that exposes iPhone or iPad network traffic over USB. The device must be unlocked and you’ll need to tap Trust this computer the first time you connect. Once enabled, the phone appears as a virtual interface (rvi0) that you can capture from with tcpdump.

The only catch: you need the device’s UDID (Unique Device Identifier). You can get it a few ways:

• System Profiler (built-in):
  Plug in your device, then run:

  system_profiler SPUSBDataType | grep -w "Serial Number"
  

  This prints the serial numbers of connected USB devices. For iPhones and iPads, that string is the UDID.

• libimobiledevice (third-party tools):
  If you have libimobiledevice installed, you can run:

  idevice_id -l
  

  which lists all connected iOS devices by UDID.

Pro-Tip If you’re giving instructions to someone else, you can make it a one-liner:

rvictl -s $(system_profiler SPUSBDataType | awk '/Serial Number/{print $3; exit}')

That command automatically grabs the first iOS device’s UDID and passes it to rvictl.

Once the RVI is active, check with:

rvictl -l

When finished, tear it down with:

rvictl -x <device-udid>

At that point, rvi0 behaves like any other interface. You can capture traffic from it just like you would on Ethernet or Wi-Fi:

sudo tcpdump -i rvi0 -s 0 -w iphone.pcap

This gives you a complete packet trace of the phone’s traffic.

Android (USB required)

Android doesn’t expose an RVI, but you can capture traffic via the Android Debug Bridge (adb). Your phone must be plugged in over USB with USB debugging enabled. On many devices this works out of the box, but some builds require a tcpdump binary installed on the phone and root privileges to run it.

• macOS:

  brew install android-platform-tools
  

• Debian/Ubuntu:

  sudo apt install android-tools-adb
  

• Fedora:

  sudo dnf install android-tools
  

• Windows:
  Download Android Platform Tools from Google.

With adb installed and your phone connected by USB (with USB debugging enabled), verify the device is detected:

adb devices

You may need to accept a prompt on the phone.

From there, you have two approaches:

• Capture directly on the device:

  adb shell tcpdump -i any -s 0 -w /sdcard/capture.pcap
  adb pull /sdcard/capture.pcap
  

  This writes a .pcap file to the device and then pulls it back to your computer.

• Stream packets live to your desktop:

  adb exec-out tcpdump -i any -s 0 -w - > android.pcap
  

  This writes the capture directly to your computer for later analysis in Wireshark (or the moral equivalent).

Filtering for Relevance

Captures get big quickly so it’s important to filter out as much noise as possible. Tcpdump uses the Berkeley Packet Filter (BPF) syntax, which is fairly simple once you know a few basics.

In practice, you’ll usually want to capture full packets and write them to a file for later analysis in Wireshark. For example:

sudo tcpdump -i eth0 -s 0 -w capture.pcap 'tcp port 443 and host example.com'

• -s 0 → capture the entire packet
• -w capture.pcap → write to a file instead of printing to the screen
• Filter expression in quotes → what traffic to capture

For the examples below, we’ll omit the -s 0 -w ... parts to keep things short, but remember to include them when you’re running a real capture.

Common Filters

# Host-based
tcpdump host 192.168.1.50
tcpdump src host 10.0.0.5
tcpdump dst host example.com

# Port-based
tcpdump port 80
tcpdump tcp port 443

# Protocol
tcpdump icmp
tcpdump arp
tcpdump udp

Practical Filtering Recipes

# DNS traffic only
tcpdump -i eth0 port 53

# HTTP traffic to a specific host
tcpdump -i eth0 tcp port 80 and host example.com

# HTTPS traffic to a specific host
tcpdump -i eth0 tcp port 443 and host 203.0.113.42

# All web traffic (HTTP + HTTPS) from one client
tcpdump -i eth0 host 192.168.1.25 and \( port 80 or port 443 \)

# Capture traffic in a subnet
tcpdump net 192.168.1.0/24

# Capture all but one noisy host
tcpdump not host 192.168.1.10

# SSH traffic to or from a specific server
tcpdump tcp port 22 and host bastion.example.com

# ICMP (pings) except from a certain host
tcpdump icmp and not src host 10.0.0.5

# Multiple conditions: HTTPS to a subnet, but ignore one host
tcpdump tcp port 443 and net 10.0.0.0/24 and not host 10.0.0.50

Tips

• Use parentheses () when combining multiple expressions (escape them in shells with \( \)).
• Add -n to prevent tcpdump from resolving hostnames (faster, less noise).
• Increase detail with -v, -vv, or -vvv when reviewing packets live.
• Filters in tcpdump (BPF) are not the same as Wireshark display filters — capture filters decide what packets are saved, while display filters decide what you see later.

Links & Stuff

Essential Documentation:

• Tcpdump man page
• Tcpdump & Libpcap homepage
• Wireshark Display Filters

Further Reading:

• Tcpdump Zine by Julia Evans — a fun, visual guide that complements this article.
• Packet Life Cheat Sheets — quick reference sheets for tcpdump, Wireshark, and more.

Conclusion

pcaps or it didn’t happen!

If you found this post useful or if you have questions, I’d love to hear from you: feedback@adminjitsu.com

Unix isn’t a lonely single-player game

Even when adventuring on your personal laptop, you’re never alone. A whole party of user accounts travels with you: root with absolute power, daemon running background jobs, nobody handling scraps, and dozens of service identities (mysql, www-data, postfix). They own files, run processes, and enforce boundaries between users.

Unix was built around the idea of a multiuser, shared environment. In the 1970s, a single minicomputer would act as a hub for dozens of dumb terminals (green-screen VT100s, Teletypes, or glass TTYs) all wired in over RS-232 serial lines. Later, SLIP and PPP links carried those sessions across early networks. Everyone logged in concurrently, sharing the same CPU, disks, and memory. To survive in that environment, the OS enforced strict user separation: each login session mapped to a unique UID, file ownership was enforced at the kernel level, and processes were isolated by identity.

This guide explains:

• History and concepts of Unix users
• Where identities live (/etc/passwd, /etc/shadow, /etc/group, /etc/sudoers)
• A cross-platform, task-based cheatsheet covering everything from inspecting to creating, modifying, and deleting users, plus group management and sudo.
• Historical tidbits, gotchas, and modern tricks
• All the pertinent documentation and links

NOTE By the end you’ll have your own player’s screen — every user-related command condensed into one place and neatly organized by task.

So, What is a User?

In Unix, a “user” is just an identity (a user principal) that the kernel uses to decide what’s allowed. Every process runs as someone, every file is owned by someone, and the system enforces permissions based on those identities.

At the machine level, a user boils down to three things:

• UID (User ID): a unique integer (UID). This is what the kernel actually checks. UID 0 is hard-coded as root, the all-powerful superuser.
• GID (Group ID): groups are collections of users, identified by their own numeric IDs (GID). Group permissions are checked alongside individual user permissions.
• Username: a human-friendly alias for a UID. When you type alice at a login prompt, the system maps that to UID 1000 (or whatever number was assigned).

The kernel doesn’t care about names, only numbers. When you run ls -l, it looks up UIDs and GIDs in /etc/passwd and /etc/group just to display friendlier, human-readable names.

NOTE If you delete a user but keep their files, ownership doesn’t vanish. The UID stays behind, and you’ll see files owned by 1001 or 2000, etc. That’s like the ghost of a user. The identity is gone, but the number persists in the filesystem.

This split between human-friendly names and machine-level numbers is deliberate. It means accounts can be automated, identities can be isolated, and multiuser systems don’t collapse into chaos.

History & Tidbits

Unix grew up in a world where multiuser systems were the norm.

• 1970s multiuser terminals: A single PDP-11 or VAX might have dozens of dumb terminals (Teletypes, VT100s, Wyse displays) connected over serial lines. Each terminal was just a keyboard and screen; all the real computing happened on the host. Later, SLIP and PPP carried terminal sessions over early TCP/IP links, making multiuser logins possible from remote sites.
• Strict separation of users: Because many people were logged in simultaneously, the kernel had to enforce sharp boundaries. Each session mapped to a unique UID; processes couldn’t touch each other’s files; and permissions were checked on every system call.
• UID 0: Always root. The kernel literally has “if (uid == 0)” checks hard-coded in privileged operations. This convention has survived intact for 50+ years.
• System accounts: Services needed their own identities to run safely. Instead of everything being root, daemons like mail, www-data, and mysql got UIDs of their own. That way, a web server compromise didn’t instantly mean total system takeover.
• Different OS ranges:
  • Linux: human users typically start at UID 1000 today (but 500 on older RHEL/CentOS). Below that are system accounts.
  • macOS: human users start at 501; everything below is reserved. Apple prefixes many system accounts with underscores (_spotlight, _windowserver).
  • BSD: similar to Linux, but ranges vary; users typically start at UID 1001; service accounts and reserved IDs are well documented in the BSD handbooks.
• “Nobody” user: UID 65534 (or sometimes -2) is a special identity with the least privilege possible. It exists to run processes with almost no rights at all.

The User Database

So where do these identities actually live? In classic Unix, they’re just flat text files:

• /etc/passwd — the account roster. Username, UID, GID, home directory, shell, and a password placeholder. World-readable.
• /etc/shadow — password hashes and aging rules. Only root can read it. If this file leaks, the system is blown.
• /etc/group — group definitions and memberships. Controls shared access.
• /etc/sudoers — the privilege ledger. Defines who can become root (and how).

On modern enterprise systems, these files often act as a front-end to NSS (Name Service Switch), which may pull identities from LDAP, NIS, Kerberos, or Active Directory. That’s why tools like getent are preferred over cat /etc/passwd .They return the whole picture not just a local slice of it.

Think of these files as the bones of an identity. The commands you run (like passwd, useradd, dscl, visudo) are the muscles that safely move those bones around.

And above it all sits the kernel, acting as the nervous system.
It doesn’t care whether an identity came from a flat file or a directory
service; all it sees are UIDs and GIDs. That abstraction is the secret
that lets Unix scale from a single laptop to a campus full of machines
while keeping the rules of identity consistent.

Permissions & Ownership Recap

Users only matter because the kernel enforces who owns what and who can do what. That enforcement happens at two levels: files and processes.

File Permissions

Every file has two owners:

• a user owner (UID)
• a group owner (GID)

And three sets of permissions: user (u), group (g), and other (o).

Example:

-rwxr-sr-- 1 alice devs 532 Sep 21 13:01 script.sh

Breakdown:

• - → type of file. (- = regular file, d = directory, l = symlink, c/b = device, s = socket, p = named pipe)
• rwx → permissions for the user/owner (alice): read, write, execute.
• r-s → permissions for the group (devs): read + execute, plus s meaning setgid is set.
• r-- → permissions for others: read only.
• 1 → hard link count. Directories show how many subdirs + self + parent.
• alice → the owner (mapped from UID).
• devs → the group (mapped from GID).
• 532 → file size in bytes.
• Sep 21 13:01 → last modification time.
• script.sh → filename.

Other permission bits:

• setuid (s on user perms): program runs with file owner’s UID. Example: /usr/bin/passwd runs as root.
• setgid (s on group perms): files created in this directory inherit the group; executables run with group’s GID.
• sticky bit (t on others perms): on directories, only file owners can delete their files. /tmp uses this.

💡 Gotcha: Permissions are checked on every system call (open(), execve(), etc). There’s no “once at login” caching — enforcement is continuous.

Process Ownership

Every process runs as a user and carries both a real UID (who started it) and an effective UID (who it’s acting as).

ps -u alice
UID   PID  CMD
1000  2345 bash
1000  2371 vim
0     2402 sudo
0     2403 systemctl

Here:

• Alice owns her bash and vim processes.
• When she runs sudo systemctl, the new process has UID 0 (root).

Key fields:

• Real UID/GID → the account that launched the process.
• Effective UID/GID → what the kernel uses for permission checks. (Setuid/setgid binaries modify this.)
• Saved UID → allows a process to drop and later regain privileges (common in daemons).

💡 Example: Apache (httpd) starts as root to bind to port 80, then immediately drops privileges to www-data. If the web server is compromised, the attacker only gains the limited www-data rights, not root.

Why It Matters

• Every file belongs to someone. Delete the account, and the UID lingers.
• Every process runs as someone. If that process is compromised, its UID defines the blast radius.
• Least privilege works only if users and groups are defined properly. Services should almost never run as root.

This is the backbone of Unix security. Once you grasp how file permissions and process ownership interact, the user management commands in the cheatsheet will make more sense. You’re really just moving numbers and labels around to control who owns what and who can act as whom.

Cheatsheet

Task-based, cross-platform, and hopefully complete. Each section expands with commands from basic to advanced.

Inspect Users & Groups

Check who you are, who exists on the system, and what groups users belong to.

# === Current identity ===
whoami                    # show effective username
id                        # UID, GID, groups
id -u                     # numeric UID only
id -g                     # numeric GID only
id -nG                    # group names only
id -G                     # numeric GIDs only
groups                    # list groups (Linux, BSD)
groups alice              # groups for another user

# === System-wide queries ===
getent passwd             # all users (NSS-aware: local, LDAP, AD)
getent passwd alice       # one user entry
getent group              # all groups
getent group sudo         # details of one group
getent group | grep alice # all groups containing alice

# === Local file lookups (local-only, not NSS-aware) ===
cut -d: -f1 /etc/passwd   # usernames only
awk -F: '$3 < 1000 {print $1, $3}' /etc/passwd   # system accounts
awk -F: '$3 >= 1000 {print $1, $3}' /etc/passwd  # human accounts

# === macOS Directory Services ===
dscl . -list /Users             # all users
dscl . -read /Users/alice       # full record for 'alice'
id alice                        # UID/GID/groups still works

# === BSD variants ===
pw usershow alice               # FreeBSD: show one user
pw groupshow wheel              # FreeBSD: show one group

Create Users

Create human accounts or service accounts.

# === Linux (Debian/Ubuntu) ===
sudo adduser alice                  # interactive, sets password, creates home, shell

# === Linux (RHEL/Fedora) ===
sudo useradd -m -s /bin/bash alice  # create with home and shell
sudo passwd alice                   # set password

# === Service/system accounts ===
sudo useradd -r -s /usr/sbin/nologin -d /var/www www-data

# === macOS 10.13+ ===
sudo sysadminctl -addUser alice -fullName "Alice Smith" -password -
# Legacy alternative:
sudo dscl . -create /Users/alice
sudo dscl . -create /Users/alice UserShell /bin/zsh
sudo dscl . -create /Users/alice RealName "Alice Smith"
sudo dscl . -create /Users/alice UniqueID "501"
sudo dscl . -create /Users/alice PrimaryGroupID 20
sudo dscl . -create /Users/alice NFSHomeDirectory /Users/alice
sudo dscl . -passwd /Users/alice password

Modify Users

Change passwords, shells, groups, or lock accounts.

# === Passwords ===
passwd alice                # change password

# === Shell ===
chsh -s /bin/zsh alice      # change login shell

# === Groups ===
usermod -aG sudo alice      # add alice to group (Linux)
gpasswd -a alice developers # alternative on some distros
gpasswd -d alice developers # remove from group

# === Lock/Unlock ===
usermod -L alice            # lock account (Linux)
usermod -U alice            # unlock account (Linux)
passwd -l alice             # lock via passwd tool
passwd -u alice             # unlock

# === macOS ===
dscl . -change /Users/alice UserShell /bin/bash /bin/zsh  # only works if shell is *currently* `/bin/bash`
dscl . -append /Groups/admin GroupMembership alice

Delete Users

Remove accounts and clean up files.

# === Linux ===
sudo userdel alice               # delete user, keep files
sudo userdel -r alice            # delete user and home directory
sudo deluser alice               # Debian helper
sudo deluser --remove-home alice # remove home too

# === Find orphaned files ===
find / -nouser -o -nogroup 2>/dev/null

# === macOS ===
sudo sysadminctl -deleteUser alice
# Or, with dscl:
sudo dscl . -delete /Users/alice

Manage Groups

Groups define shared access.

# === Linux ===
groupadd developers           # create group
groupdel developers           # delete group
usermod -aG developers alice  # add to group
gpasswd -d alice developers   # remove from group

# === BSD ===
pw groupadd developers
pw groupmod developers -m alice

# === macOS ===
dscl . -create /Groups/devs
dscl . -append /Groups/devs GroupMembership alice
dscl . -delete /Groups/devs

Classic Multiuser Tools

Old-school, but still around.

who              # list logged-in users
w                # list logged-in users + what they’re doing
users            # just usernames
last             # login history
write bob        # message another user
wall "msg"       # broadcast to all users
talk bob         # split-screen chat
finger bob       # show user info (if finger service enabled)

Sudo & visudo

The /etc/sudoers file decides who can act as root (or another user).
Always use visudo to edit it — it locks the file and checks syntax so you don’t brick sudo.

# === Change default editor (defaults to vi) ===
export EDITOR=nano
sudo visudo

# === Rule format ===
user_or_%group   host = (run_as) command_list

# Parts of a rule:
# - user_or_%group → single user (alice) or group (%wheel)
# - host           → usually ALL unless restricted to specific hosts
# - run_as         → ALL (default root) or another user (postgres, deploy)
# - command_list   → full path(s) to allowed commands

# === Open and validate sudoers ===
sudo visudo            # edit main sudoers file safely
sudo visudo -c         # check config syntax only
sudo visudo -f /etc/sudoers.d/webadmins   # edit a drop-in file

# === Give one user full root powers ===
alice ALL=(ALL) ALL

# === Group-based full access ===
%wheel ALL=(ALL) ALL      # common on RHEL/BSD
%sudo  ALL=(ALL) ALL      # common on Debian/Ubuntu
%admin ALL=(ALL) ALL      # common on macOS

# === Limit bob to restarting nginx only ===
bob ALL=(ALL) /usr/bin/systemctl restart nginx

# === Let webadmins group manage nginx + apache ===
%webadmins ALL=(ALL) /usr/bin/systemctl restart nginx, \
                     /usr/bin/systemctl restart apache2

# === Allow package updates only ===
dave ALL=(ALL) /usr/bin/apt update, /usr/bin/apt upgrade
dave ALL=(ALL) /usr/bin/yum update
dave ALL=(ALL) /usr/bin/dnf upgrade

# === Run Docker commands without full root ===
carol ALL=(ALL) /usr/bin/docker ps, /usr/bin/docker restart *

# === Run commands as a different user (deploy) ===
carol ALL=(deploy) /usr/bin/git pull, /usr/bin/git checkout

# === Force password every time (no caching) ===
Defaults timestamp_timeout=0

# === Allow passwordless sudo (⚠️ dangerous) ===
alice ALL=(ALL) NOPASSWD: ALL

Troubleshooting

When a user can’t log in, can’t write files, or sudo mysteriously fails, these checks will save you.

# === File permission issues ===
ls -l file                  # check ownership + rwx bits
id alice                    # confirm UID + GIDs
groups alice                # confirm group memberships

# === Login problems ===
passwd -S alice             # Linux: check password status (L=locked, P=usable)
chage -l alice              # Linux: check password aging + expiry
grep ^alice: /etc/passwd    # check home dir + shell field
dscl . -read /Users/alice   # macOS: inspect account record

# === Orphaned files or groups ===
find / -nouser -o -nogroup 2>/dev/null   # files with no matching UID/GID

# === Process ownership ===
ps -u alice                 # all processes owned by alice
pgrep -u alice              # list PIDs only
pkill -u alice              # kill all processes for alice (⚠️ destructive)

# === Sudo debugging ===
sudo -l                     # list sudo rights for current user
sudo -v                     # refresh credentials (prompts password)
sudo -k                     # expire cached credentials

Advanced Topics

Defaults & Templates

When a new account is created, the system applies defaults: skeleton files, UID ranges, shells, and the default mask (umask). These define how a fresh user’s environment looks and how secure their files are.

# === Skeleton files ===
ls -A /etc/skel          # files copied into new home dirs
# .bashrc  .profile  .bash_logout

# Add a custom file for all new users
sudo cp /etc/motd /etc/skel/welcome.txt

# === Default umask ===
umask                    # show current mask
# 0022 → new files 644 (-rw-r--r--) and dirs 755 (drwxr-xr-x)

# Change umask for tighter privacy (per shell session)
umask 0077
touch secret.txt && ls -l secret.txt
# -rw------- 1 alice users 0 Sep 21 16:10 secret.txt

# === Global login defaults (Linux) ===
grep -E 'UID_MIN|UID_MAX|GID_MIN|GID_MAX' /etc/login.defs
# UID_MIN 1000, UID_MAX 60000

Name Service Switch & Domains

On modern systems, /etc/passwd is just one source of truth. Enterprises often keep users in LDAP, Kerberos realms, or Active Directory. The Name Service Switch (NSS) decides where the system looks when resolving usernames, groups, and hosts.

# === NSS lookup order (Linux) ===
grep passwd /etc/nsswitch.conf
# passwd: files systemd sss
# "files" = /etc/passwd, "systemd" = local systemd users, "sss" = SSSD (LDAP/AD)

# === Query via NSS (all backends) ===
getent passwd alice          # works even if alice is in LDAP/AD
getent group devs            # query group membership

# === Show only local file (not NSS aware) ===
cat /etc/passwd | grep alice # will miss LDAP/AD users

# === Join an AD domain (Linux, via realmd/SSSD) ===
realm discover example.com   # discover domain controllers
sudo realm join example.com  # join domain
systemctl status sssd        # domain users now available via SSSD

# === Test a domain account ===
id alice@example.com
# uid=123456789(alice@example.com) gid=123456789(domain users) groups=...

Access Control Lists (ACLs)

The classic Unix model (user/group/other) is simple but limited. What if you want multiple users with different rights on the same file, without changing ownership or creating new groups? That’s where Access Control Lists (ACLs) come in. ACLs add fine-grained permissions on top of the traditional model.

# === See current permissions (no ACL yet) ===
ls -l project.txt
# -rw-r----- 1 alice devs 42 Sep 21 17:00 project.txt

# Only alice (owner) has rw, devs group has r, others none.

# === Add bob with RW access via ACL ===
setfacl -m u:bob:rw project.txt
getfacl project.txt
# file: project.txt
# owner: alice
# group: devs
user::rw-
user:bob:rw-          # new ACL entry
group::r--
mask::rw-
other::---

# === Remove bob's entry later ===
setfacl -x u:bob project.txt

# === Default ACL on a directory ===
setfacl -d -m g:devs:rwx /srv/project
ls -ld /srv/project
# drwxrwxr-x+ 2 root root 4096 Sep 21 17:05 /srv/project
# (+ indicates ACLs are set)
getfacl /srv/project
# default:group:devs:rwx

# Now any file created under /srv/project inherits group rwx.

# === macOS NFSv4 ACLs ===
ls -le project.txt
-rw-r-----+ 1 alice staff 42 Sep 21 17:10 project.txt
 0: user:bob allow read,write

chmod +a "bob allow read,write" project.txt

Linux Capabilities

Traditionally, if a program needed any privileged action (like opening a raw socket or binding to a low port), it had to be setuid root. That gave it full root power, even if it only needed one small permission.

Linux capabilities break root’s powers into fine-grained units — like CAP_NET_RAW (raw sockets) or CAP_SYS_ADMIN (system-wide admin). You can then grant a binary just the slice it needs instead of all-or-nothing root.

# === Traditional setuid ping ===
ls -l /bin/ping
# -rwsr-xr-x 1 root root ...
# setuid root: ping runs as full root just to open raw sockets.

# === Replace with capability ===
sudo chmod u-s /bin/ping                   # remove setuid bit
sudo setcap cap_net_raw+ep /bin/ping       # give only raw socket ability
getcap /bin/ping
# /bin/ping = cap_net_raw+ep

# === Test that it works ===
ping -c1 127.0.0.1                         # works without setuid

# === Drop capabilities from a running process (demo with sleep) ===
sleep 100 &
pid=$!
grep CapEff /proc/$pid/status              # shows effective caps (usually 0000000000000000)

Systemd Dynamic Users

Normally, services run under pre-created system accounts like www-data or mysql. But that clutters /etc/passwd with dozens of long-lived identities that stick around even if the service is removed.

Dynamic users solve this: systemd can allocate a throwaway UID/GID at runtime when the service starts. When the service stops, the UID disappears. It’s perfect for daemons that don’t need persistent files or shells.

# /etc/systemd/system/web.service
[Service]
ExecStart=/usr/bin/mydaemon
DynamicUser=yes                    # allocate ephemeral UID at runtime
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes

Rootless Containers & Subuids

Normally, containers run as root, which maps directly to the host’s root — a big risk if the container is compromised. Rootless containers avoid this by mapping container UIDs/GIDs to high-numbered “subuids” and “subgids” on the host.

That way, root inside the container is really just UID 100000+ on the host — isolated, unprivileged, and unable to harm the real system.

# === Show subuid/subgid allocation ===
grep alice /etc/subuid /etc/subgid
# alice:100000:65536
# means: user 'alice' gets a block of 65,536 UIDs/GIDs starting at 100000.

# === Run a rootless container ===
podman run --rm alpine id
uid=0(root) gid=0(root) groups=0(root)

# From inside the container it looks like root,
# but on the host it's actually UID 100000+ from /etc/subuid.

# === Inspect namespace mapping ===
podman unshare cat /proc/self/uid_map
# 0 100000 65536
# "container UID 0 maps to host UID 100000, size 65536"

Password Policy & Lockouts

User accounts also have lifespans and safety rules.

Password policy defines how often a user must change their password, how complex it must be, and how many failed logins before the account locks.

This is enforced through shadow file aging fields (Linux/Unix), PAM modules for lockouts, and platform-specific tools on macOS and BSD.

# === Linux: show password aging/expiry ===
chage -l alice
# Last password change                                    : Sep 21, 2025
# Password expires                                       : Nov 20, 2025
# Password inactive                                      : never
# Account expires                                        : never
# Minimum number of days between password change         : 0
# Maximum number of days between password change         : 60
# Number of days of warning before password expires      : 7

# === Linux: check failed logins ===
faillock --user alice
# alice:
# When        Type  Source
# 2025-09-21  TTY   ssh:notty
# 2025-09-21  TTY   ssh:notty

# Lock out after 3 failures (RHEL/Ubuntu with pam_faillock)
sudo faillock --setdeny=3

# === BSD: enforce minimum password age ===
passwd -n 30 alice     # must wait 30 days before changing again

# === macOS: show password policy ===
pwpolicy -u alice -getpolicy
# prints dictionary of rules:
# usingHistory=15 minChars=8 requiresMixedCase=1 requiresNumeric=1

# Set stricter policy on macOS
sudo pwpolicy -u alice -setpolicy "minChars=12 requiresMixedCase=1 requiresNumeric=1 requiresSymbol=1"

Audit & Logs

When a user can’t log in, sudo fails, or permissions seem wrong, the logs tell the story. Different Unix-like systems store them in different places, but the principles are the same: check authentication logs, check system journals, and look at login history.

# === Debian/Ubuntu: SSH & sudo events ===
tail -f /var/log/auth.log
# Sep 21 17:40 server sshd[2345]: Failed password for bob from 192.168.1.20 port 55312 ssh2
# Sep 21 17:42 server sudo:   alice : TTY=pts/0 ; PWD=/home/alice ; USER=root ; COMMAND=/bin/ls

# === RHEL/Fedora equivalents ===
tail -f /var/log/secure

# === systemd journal: filter by UID ===
journalctl _UID=1000 --since today
# shows all messages generated by UID 1000 (alice)

# === systemd journal: filter by command ===
journalctl _COMM=sudo -S today
# shows all sudo invocations since today

# === Login history: successful ===
last
# alice   pts/0        192.168.1.20     Sun Sep 21 17:00   

# === Login history: failed ===
lastb
# bob     ssh:notty    192.168.1.20     Sun Sep 21 17:40   

SSH Key Restrictions

SSH public keys don’t just allow or deny login — you can control what they’re allowed to do. This is especially useful for automation accounts (backups, deploy scripts, CI/CD) where you don’t want full shell access.

Restrictions are written in ~/.ssh/authorized_keys before the key itself. Multiple restrictions can be combined with commas.

# === Restrict login to a specific subnet ===
from="192.168.1.0/24" ssh-ed25519 AAAAC3Nza...

# === Force a command (ignore user input) ===
command="/usr/local/bin/backup.sh" ssh-ed25519 AAAAC3Nza...
# When this key logs in, it *always* runs backup.sh — no shell access.

# === Disable shell/TTY allocation ===
no-pty,command="/usr/bin/rsync --server --sender ..." ssh-ed25519 AAAAC3Nza...
# Useful for file transfers only.

# === Combine multiple restrictions ===
from="10.0.0.5",no-pty,command="/usr/local/bin/deploy.sh" ssh-ed25519 AAAAC3Nza...
# Only works from 10.0.0.5, no interactive shell, forced deploy script.

# === Log key usage for auditing ===
environment="DEPLOY_KEY_ID=ci-runner" ssh-ed25519 AAAAC3Nza...
# Adds DEPLOY_KEY_ID to environment for logging in scripts.

Other OS-Specific Nuggets

Not every Unix-like does user management the same way. Here are a few platform-specific details that matter when you step outside Linux.

# === macOS: FileVault & SecureToken ===
# Check if a user has SecureToken (needed to unlock FileVault at boot)
sysadminctl -secureTokenStatus alice

# Grant FileVault unlock rights to an existing account
sudo fdesetup add -usertoadd alice

# List all FileVault-enabled users
fdesetup list

# === BSD: doas instead of sudo ===
# Install and configure a simple allow rule for wheel group
echo "permit :wheel" | sudo tee /usr/local/etc/doas.conf

# Test it
doas whoami
# root

# === Linux/systemd: user sessions ===
# List all active systemd user sessions
loginctl list-users

# Show details for a single user session
loginctl user-status alice

Links & Stuff

Core Resources

• man 5 passwd, man 5 shadow, man 5 group, man 5 sudoers
• Linux User Management Guide (Arch Wiki, applies broadly)
• FreeBSD Handbook: Users and Basic Account Management

macOS-Specific Resources

• Add a user or group on Mac - Apple Support
• Change Users & Groups settings on Mac - Apple Support
• dscl Man Page - SS64.com — comprehensive dscl reference
• dscl Examples - University of Utah — practical dscl usage
• Additional Features - Apple Developer Archive — includes user creation examples

History & Lore

• Why is root UID 0?
• The nobody user

Conclusion

Every file belongs to someone. Every process runs as someone.

Email me if you found this guide useful or if I missed something:
feedback@adminjitsu.com

Happy administering

“A rolling stone gathers momentum.” – anonymous fortune

Git is one of those tools that grows with you. At a certain point I wondered what you could customize and found a number of quality of life improvements. You can tweak aliases, set safer defaults, and customize color schemes.

This guide is the companion piece to Git-Fu. That one focused on commands and workflows. This one goes under the hood: git config, what lives in the config files, and how you can bend Git to your will.

How git config Works

Git’s configuration is layered into three scopes:

• System: applies to all users
  • Linux/Mac: /etc/gitconfig
  • Windows: C:\Program Files\Git\etc\gitconfig
• Global: applies to you
  • Primary: ~/.gitconfig
  • Alternative: ~/.config/git/config (XDG standard)
• Local: applies to a single repo (.git/config)

Git reads these in order, with more specific scopes overriding broader ones. So a local setting beats a global one, which beats a system one.

The safe way to set values is with the git config command, which writes to the correct file for you. For example:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Use --system, --global, or --local to control the scope. Handy flags include --get, --unset, and --list.

See everything Git knows about you right now with:

git config --list --show-origin

Where git config Lives (Persistence, Saving & Resetting)

When you run git config, you’re not changing runtime state — you’re editing a config file. That’s why these tweaks persist across reboots and repos.

Saving Your Config

Back up everything:

git config --global --list > my-gitconfig.txt

Or just a subset:

git config --global --get-regexp '^alias\.' > my-aliases.txt

Restoring a Config

Reapply from a dump:

while read key value; do
  git config --global "$key" "$value"
done < my-gitconfig.txt

Or just copy ~/.gitconfig between machines.

Resetting to Defaults

Remove a section:

git config --global --remove-section alias

Unset a single key:

git config --global --unset core.editor

Full reset:

mv ~/.gitconfig{,.bak}   # quick backup

# or, if you’re feeling reckless
rm ~/.gitconfig

⚠️ Nukes everything—identity, aliases, colors, etc.
Use the mv method unless you’re 100% sure. Back up first!

Takeaways

• git config is persistent because it writes to config files.
• You can save and restore with simple dump/reapply steps.
• Resetting can be surgical (--unset) or nuclear (rm ~/.gitconfig).

Cheatsheet: Useful Git Config Commands

The examples below use git config commands, but you can also open your config file directly with:

git config --edit

Quick Start: 5 Safe Defaults

If you only set a handful of Git configs, make it these. They improve safety, keep repos tidy, and save you headaches later:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

git config --global init.defaultBranch main   # new repos start on 'main'
git config --global push.default simple       # safer pushes
git config --global fetch.prune true          # auto-clean dead branches

That’s it—your identity + three defaults. You can stop here and still have a nicer Git.
When you’re ready, scroll down for more customization (aliases, pretty logs, colors, etc.).

Identity

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Usability Defaults

git config --global init.defaultBranch main   # new repos start with 'main'
git config --global push.default simple       # safer pushes
git config --global fetch.prune true          # auto-clean old branches
git config --global pull.rebase false         # or true if you’re a rebasing fan

Editor

git config --global core.editor "nano"  # or vim, code --wait, etc.
git config --global diff.tool vimdiff     # or your preferred diff tool
git config --global merge.tool vimdiff    # or your preferred merge tool

Pretty Logs

git config --global format.pretty oneline
git config --global log.abbrevCommit true
git config --global log.date relative

Safer Merges

git config --global merge.ff only
git config --global diff.mnemonicprefix true
git config --global rerere.enabled true  # reuse recorded resolutions

Aliases (muscle memory FTW)

Aliases let you shorten Git commands into quick shorthands. For example:

git config --global alias.st status

Now instead of typing git status, you can just type:

git st

That’s all aliases do—they don’t add new features, but they save keystrokes and speed up common commands. Aliases can point to any Git verb, including ones with arguments. For example:

git config --global alias.lg "log --oneline --decorate --graph --all"
git lg   # expands to 'git log --oneline --decorate --graph --all'

And here’s the cool part: if your alias starts with !, Git treats it as a raw shell command instead of a Git subcommand. That means you can make Git run non-Git commands—or Git commands wrapped in shell logic:

git config --global alias.today '!date'
git today   # runs your system 'date' command

git config --global alias.root '!git rev-parse --show-toplevel'
git root    # prints the repo’s root directory

Note:
Aliases that start with ! run exactly as written in your shell. They don’t take extra arguments the way normal Git commands do—git root sub/dir won’t work. For more flexibility, write a shell script and call it from your alias.

Here are some popular everyday aliases you can copy straight in:

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm 'commit -m'
git config --global alias.lg "log --oneline --decorate --graph --all"

🎨 How Git Colors Work

Git doesn’t store colors itself—it just spits out ANSI escape codes. Your terminal decides what “yellow” or “cyan” actually looks like. That’s why the default yellow sometimes looks like Dijon mustard depending on your theme.

Git supports three kinds of values:

• Named ANSI colors: red, green, blue, cyan, yellow, magenta, white, black
• Attributes: bold, ul (underline), reverse, blink
• Hex RGB (#rrggbb) since Git 2.16 — the most reliable way to get exact shades across terminals

Quick Test

If you just want to see Git output in color, enable it globally:

git config --global color.ui always

Now run git status or git diff — you’ll get Git’s built-in red/green/yellow scheme.

# Test your new colors
git status
git log --oneline --decorate -10
git diff HEAD~1 HEAD
git branch -a
git grep "function" # (if you have any code files)

Sample Theme: “Cool Dark”

Here’s a complete theme you can paste in to try out. It uses golden yellow, light cyan/blue, mint green, and bright grey accents chosen for a black terminal background.

Paste the whole block into your terminal (or save as a script). VS Code’s inline color picker (which appears when you hover over hex colors like #ffd75f) makes customizing these colors especially easy.

git config --global color.ui always

# ── Branches ──
# Affects 'git branch' output and branch decorations in 'git log'
git config --global color.branch.current "#ffd75f"   # golden yellow (current branch)
git config --global color.branch.local   "#5fd7ff"   # light cyan (local branches)
git config --global color.branch.remote  "#87afff"   # soft sky blue (remotes)

# ── Diffs ──
# Affects 'git diff' output
git config --global color.diff.meta       "#ffd75f"  # metadata (index info, etc.)
git config --global color.diff.frag       "#5fd7ff"  # hunk headers
git config --global color.diff.old        "#ff5f5f"  # red for removed lines
git config --global color.diff.new        "#87ffaf"  # mint green for added lines
git config --global color.diff.whitespace "#ff5f87"  # pink highlight for whitespace errors
git config --global color.diff.commit     "#5fd7ff"  # commit hashes in 'git log --oneline' (older Git)

# ── Status ──
# Affects 'git status' output
git config --global color.status.added     "#87ffaf" # mint green (staged new files)
git config --global color.status.changed   "#ffd75f" # yellow (modified files)
git config --global color.status.untracked "#5fd7ff" # cyan (new untracked files)
git config --global color.status.branch    "#bcbcbc" # grey (branch info line)

# ── Grep ──
# Affects 'git grep' output
git config --global color.grep.match      "#ffd75f"  # yellow (matches)
git config --global color.grep.filename   "#5fd7ff"  # cyan (filenames)
git config --global color.grep.linenumber "#bcbcbc"  # grey (line numbers)

# ── Log / Decorations ──
# Affects 'git log --decorate' output
git config --global color.decorate.head         "#87ffaf" # mint green (HEAD)
git config --global color.decorate.branch       "#5fd7ff" # cyan (local branches)
git config --global color.decorate.remoteBranch "#ffd75f" # yellow (remote branches)
git config --global color.decorate.tag          "#ff5f87" # pink (tags)

# ── Interactive ──
# Affects interactive commands (git rebase -i, git add -p)
git config --global color.interactive.prompt "#ffd75f" # yellow (prompts)
git config --global color.interactive.header "#87afff" # blue (section headers)
git config --global color.interactive.help   "#bcbcbc" # grey (help text)
git config --global color.interactive.error  "#ff5f5f" # red (errors)

# ── Pager highlight ──
# Affects search matches inside 'less'
git config --global color.pager.highlight "#87afff"   # soft blue

[color]
    ui = always

[color "branch"]
    current = #ffd75f
    local   = #5fd7ff
    remote  = #87afff

[color "diff"]
    meta       = #ffd75f
    frag       = #5fd7ff
    old        = #ff5f5f
    new        = #87ffaf
    whitespace = #ff5f87
    commit     = #5fd7ff   # commit hashes (older Git)

[color "status"]
    added     = #87ffaf
    changed   = #ffd75f
    untracked = #5fd7ff
    branch    = #bcbcbc

[color "grep"]
    match      = #ffd75f
    filename   = #5fd7ff
    linenumber = #bcbcbc

[color "decorate"]
    head         = #87ffaf
    branch       = #5fd7ff
    remoteBranch = #ffd75f
    tag          = #ff5f87


[color "interactive"]
    prompt = #ffd75f
    header = #87afff
    help   = #bcbcbc
    error  = #ff5f5f

[color "pager"]
    highlight = #87afff

Resetting to Defaults

If you want Git’s classic red/green/yellow back, just clear your overrides:

git config --global --remove-section color.branch   2>/dev/null
git config --global --remove-section color.diff     2>/dev/null
git config --global --remove-section color.status   2>/dev/null
git config --global --remove-section color.interactive 2>/dev/null
git config --global --remove-section color.grep     2>/dev/null
git config --global --remove-section color.pager    2>/dev/null
git config --global --unset color.ui                2>/dev/null

📚 Further Reading

• Git Book: Customizing Git
• Git Documentation: git-config
• ANSI color codes explained

Conclusion

If you’ve got tips, tricks, or a cool theme of your own, drop me a line: feedback@adminjitsu.com

I’ve been using git almost daily for years now and I can’t imagine working on anything serious without it. I avoided learning git for ages though and just took my chances and used lots of backup folders and notes until my projects began to strain under their own weight.

Git can feel cryptic at first with numerous commands, it’s own terminology, and plenty of “oh no, what did I just do?” moments. Luckily you don’t need to know every dark corner of Git to use it well. With a few key concepts, a solid cheatsheet, and some helper scripts, Git becomes a trusted and powerful tool.

What is Git?

At its heart, Git is a time machine for text files.
It lets you move backward and forward through the history of a project, explore alternate timelines, and share those timelines with others.

• Commits are snapshots.
  Each commit is like a photograph of your project at a moment in time.
  It doesn’t just save what changed, but how the whole directory looked so you can always step back to that state.
  Specifically, Git stores full snapshots (not just diffs) and shows diffs only when you compare snapshots.

• Branches are pointers.
  A branch isn’t a copy of your work — it’s just a movable label pointing to a commit.
  This makes branching lightweight and cheap, so you can spin off experiments freely without bloating your repo.
  The HEAD is a pointer too—it tells Git where you’re currently standing. Switching branches just moves HEAD (your current position) to a different branch reference.

• Merging is weaving timelines.
  When two branches diverge, merging pulls their histories together into a single story.
  Sometimes this is automatic; other times you have to resolve conflicts where the timelines disagree.
  Sometimes Git can simply fast-forward a branch if there’s no divergence—no new merge commit needed.

• Rebasing is replaying commits.
  Instead of weaving two histories together, rebasing lifts your commits and replays them onto a different base.
  The result is a cleaner-looking history where events flow in a straight line.

• Remotes are copies of the archive.
  A remote (like GitHub, GitLab, or Gitea) is just another place your repo lives.
  You can fetch from it, push to it, or clone it elsewhere. Remotes make collaboration and backup possible.

Think of it as a Directed graph of changes where you always have a way back to safety

Key Concepts

• Repos: local vs remote
  A local repo is your working copy with a .git/ folder inside it.
  A remote is just another full copy of the repo, usually hosted on a server (GitHub, GitLab, Gitea).
  By default, the first remote is called origin. You can rename it, or add others (upstream, backup, etc).

• Staging area
  Also called the index. This is where you prepare changes before committing. Think of it as a shopping cart or draft tray: you can stage some edits, leave others unstaged, and commit only what you want.

• Commits
  Immutable snapshots with parent pointers. Each has a SHA-1 ID (SHA-256 is becoming standard), author info, and message. Together they form a graph (specifically a 🔗directed acyclic graph or DAG ) of your project history.

• Branches
  Lightweight movable labels pointing at commits. Switching branches just moves the HEAD pointer to a different branch reference.

• Rebase vs Merge

  • Merge combines two histories into one, preserving all bumps. Good for shared branches where others can see your work. Leaves a merge commi.
  • Rebase rewrites your commits so they look like they happened on top of another branch, creating a cleaner chain of history.

• Upstream/Tracking branches
  When a local branch “tracks” a remote one, Git knows where to pull and push by default.

The Local Git Repo

When you git init in a folder, Git creates a hidden directory called .git/.
That directory is the repository. All of your other files are just working copies.

This is what makes Git powerful and portable: if you copy a project folder with its .git/ intact, you’ve copied the entire history as well as branches, tags, and settings. You don’t need a server, a database, or any special tooling.

Anatomy of .git/ (simplified)

└─$ tree -L 1 .git/
.git/
├── COMMIT_EDITMSG
├── FETCH_HEAD
├── HEAD
├── ORIG_HEAD
├── branches
├── config
├── description
├── hooks
├── index
├── info
├── logs
├── objects
├── packed-refs
└── refs

• HEAD → a text file that tells Git which branch you’re currently on.
• config → local repo configuration (remotes, branch tracking, custom settings).
• objects/ → the actual data store. Commits, trees, and blobs (file contents) live here, addressed by their SHA-1 hash.
• refs/ → pointers to commits: branches, tags, remotes.
• logs/ → the reflog, Git’s “black box recorder” of branch movements.
• index → the staging area, stored as a binary file.
• hooks/ → scripts you can run automatically on events (commits, pushes, merges).

Most of the time you never touch these directly, but it’s useful to know they exist.
Thankfully it’s just a folder full of plain-text files and hashed objects. (Peek at COMMIT_EDITMSG if you ever want to see the last commit message you wrote.)

Why it matters

• Portability → copy the folder to a USB stick, another machine, or zip it up, and you’ve moved the repo with its entire history.
• Independence → no central server required; you always have a complete copy locally.
• Transparency → advanced users can inspect .git/config or .git/refs/heads/ to see what’s really happening under the hood.

Cheatsheet

Git has a lot of commands so I like to group them into related tasks to make it easier to find what you need based on what you’re trying to do.

Getting Started: Init & Remotes

Every Git journey starts by either creating a new repo or cloning an existing one.
Then, if you want to sync with a remote (GitHub, GitLab, Gitea), you connect it.

# === Create a new repo ===

# Initialize a repo in the current folder
git init

# Clone an existing repo
git clone https://github.com/user/project.git
git clone git@github.com:user/project.git   # SSH form


# === Check current remotes ===
git remote -v

# Add a new remote (usually 'origin')
git remote add origin https://github.com/user/project.git

# Change the remote URL (e.g., switch to SSH)
git remote set-url origin git@github.com:user/project.git

# Remove a remote
git remote remove origin


# === First push ===

# Push the current branch to 'origin' and set it as upstream
git push -u origin main

# After upstream is set, future pushes are simpler:
git push
git pull

Daily Workflow: Add, Commit, Push, Pull

Most of the time you’re just making changes, saving them, and syncing with a remote.
These are the everyday Git commands you’ll run dozens of times a week.

# === Checking status ===
git status          # See which files changed, staged, or untracked

# === Staging changes ===
git add file.txt    # Stage one file
git add -A          # Stage all changes (tracked + untracked)

# === Committing ===
git commit -m "Message here"   # Save staged changes with a message
git commit --amend             # Fix last commit (message or staged content)

# === Pushing to remote ===
git push            # Send local commits to upstream
git push origin main  # Explicit remote + branch

# === Pulling updates ===
git pull            # Fetch + merge changes from upstream
git pull --rebase   # Fetch + replay your commits on top (cleaner history)

Branching & Merging

Branches let you explore ideas without messing up your main line of work.
Merging and rebasing are how you bring those timelines back together.

# === Working with branches ===
git branch               # List local branches
git branch -r            # List remote branches
git branch new-feature   # Create a new branch (stays on current)
git checkout new-feature # Switch to a branch (old syntax)
git switch new-feature   # Switch to a branch (new syntax)
git switch -c bugfix     # Create + switch in one step

# === Merging ===
git checkout main
git merge new-feature    # Merge branch into main

# Merge conflicts: Git marks conflicts in files
# Edit manually, then:
git add conflicted-file
git commit               # Finish the merge

# === Rebasing ===
git checkout new-feature
git rebase main          # Replay commits on top of main

# If conflicts happen during rebase:
git status               # See what’s wrong
git add fixed-file
git rebase --continue    # Resume rebase

# Abort if it goes sideways
git merge --abort        # during a merge
git rebase --abort       # during a rebase

Undo & Rescue

Everyone makes mistakes in Git from time to time. Luckily,
Git has a time machine and a safety net built in. These commands let you undo changes, roll back commits, and recover “lost” history.

# === Unstaging changes ===
git restore --staged file.txt    # Unstage a file (leave working copy alone)
git reset HEAD file.txt          # Older syntax, same effect

# === Discarding local changes ===
git restore file.txt             # Throw away unstaged changes
git checkout -- file.txt         # Old form, still works

# === Undoing commits ===
git commit --amend               # Edit last commit (message or staged content)
git reset --soft HEAD~1          # Undo last commit, keep changes staged
git reset --mixed HEAD~1         # Undo last commit, keep changes unstaged
git reset --hard HEAD~1          # Rewind + throw away changes (⚠️ destructive)

# === Reverting commits safely ===
git revert <commit>              # Create a new commit that undoes the given one

# === Reflog (magic undo history) ===
git reflog                       # Show where HEAD has been (local movements)
git checkout <commit-hash>       # Recover a commit from reflog

# === Aborting operations ===
git merge --abort                # Cancel a merge in progress
git rebase --abort               # Cancel a rebase in progress

Remotes & Sync

Remotes are just other copies of your repo (GitHub, GitLab, Gitea, etc.).
You fetch changes from them, push your commits to them, and pull to stay in sync.

# === Checking remotes ===
git remote -v                   # Show remotes and their URLs

# Add a remote (commonly 'origin')
git remote add origin https://github.com/user/project.git

# Change URL (switch HTTPS ↔ SSH)
git remote set-url origin git@github.com:user/project.git


# === Fetching & pulling ===
git fetch                       # Download commits/branches from remote (no merge)
git pull                        # Fetch + merge remote changes into current branch
git pull --rebase               # Fetch + replay your commits on top (cleaner history)


# === Pushing ===
git push                        # Push current branch to its upstream
git push -u origin main         # First push: set upstream branch
git push origin feature         # Push a different branch by name

# Push all tags
git push --tags

# Delete a remote branch
git push origin --delete old-branch

Tags & Releases

Tags mark important points in history — often used for releases (v1.0, v2.1.3).
Unlike branches, they don’t move: they’re permanent labels on commits.

# === Creating tags ===
git tag v1.0.0                 # Lightweight tag on latest commit
git tag -a v1.0.0 -m "Release" # Annotated tag (with message, recommended)
git tag v1.0.0 <commit>        # Tag a specific commit

# === Listing & inspecting ===
git tag                        # List all tags
git show v1.0.0                # Show commit + info behind a tag

# === Pushing tags ===
git push origin v1.0.0         # Push one tag
git push --tags                # Push all tags

# === Deleting tags ===
git tag -d v1.0.0              # Delete local tag
git push origin --delete v1.0.0 # Delete remote tag

Cleanup & Maintenance

Over time, branches pile up, and Git’s object database grows.
These commands keep your repo tidy and lean.

# === Branch cleanup ===
git branch -d feature          # Delete local branch (safe, only if merged)
git branch -D feature          # Force delete local branch
git push origin --delete old   # Delete remote branch

# === Pruning ===
git fetch --prune              # Remove local refs to deleted remote branches
git remote prune origin        # Same effect, manual trigger

# === Garbage collection ===
git gc                         # Cleanup loose objects & optimize repo
git gc --prune=now             # Aggressive cleanup (⚠️ careful)

# === Checking size ===
git count-objects -vH          # Show object counts + repo size

Tricky Areas Demystified

There are a few tricky situations that hopefully save a lot of head-scratching.

Merge vs Rebase

Both are ways of bringing one branch’s changes into another, but they tell different stories:

• Merge → preserves history. Two timelines come together, and the graph shows the divergence + merge point.

  • Good for shared branches (everyone sees the real history).
  • Downside: history can look “messy” with lots of merge commits.

• Rebase → rewrites history. Your commits are replayed as if they happened after the other branch.

  • Good for private branches you haven’t shared yet (keeps history linear).
  • Downside: don’t rebase commits you’ve already pushed/shared — it confuses collaborators.

💡 Rule of thumb: Merge when collaborating, rebase when cleaning up your own local work.

How Git Diff Works

Diffs compare snapshots, not files directly. That’s why you can run diffs between:

• Working directory vs staging → git diff
• Staging vs last commit → git diff --cached
• Any two commits → git diff <commit1> <commit2>
• Current branch vs remote → git diff origin/main

This flexibility comes from Git’s DAG of commits. A “diff” is just “what would I need to apply to one snapshot to make it look like another?”

Detached HEAD

When you check out a commit by hash (not a branch), HEAD points directly at that commit.
You can poke around safely, but new commits won’t belong to any branch unless you explicitly create one.

• Checking out a commit: git checkout abc123
• Getting back to a branch: git switch main
• Saving your detached work: git switch -c experiment

The Safety Net: Reflog

Every time HEAD moves, Git logs it in .git/logs/HEAD.
That means even after a reset, rebase, or branch delete, you can usually recover.

git reflog              # Show recent HEAD movements
git checkout <hash>     # Jump back to a lost commit

Think of it as Git’s black box recorder. When all else fails, check the reflog.

gcheck: A Friendly Git Status Report

Over time I found myself running the same few Git commands again and again:

• git status to see what’s staged
• git fetch to check for updates
• git log or git diff to compare with upstream

That’s a lot of typing just to answer the question: “What’s the state of this repo?”

So I wrote a little Bash function called gcheck. It gives you a clear, human-readable summary of your current repository, including whether you’re ahead or behind your remote branch. I’ve been using it daily for months now and it’s become second nature.

gcheck() {
  if ! git rev-parse --show-toplevel &>/dev/null; then
    echo "🚫 Not inside a Git repository."
    return 1
  fi

  echo "🔍 Checking Git repo status for: $(basename "$(git rev-parse --show-toplevel)")"
  echo "------------------------------------------"
  
  git status || return 1
  
  echo -e "\n📡 Fetching updates from remote..."
  git fetch || return 1

  local branch current remote
  current=$(git symbolic-ref --short HEAD)
  remote=$(git for-each-ref --format='%(upstream:short)' "refs/heads/$current")

  if [ -z "$remote" ]; then
    echo "⚠️  No remote tracking branch set for '$current'"
    return 1
  fi

  echo -e "\n🔄 Comparing local '$current' with '$remote'..."
  local ahead behind
  ahead=$(git rev-list --count "$remote"..HEAD)
  behind=$(git rev-list --count HEAD.."$remote")

  if (( ahead == 0 && behind == 0 )); then
    echo "✅ Branch is up to date with '$remote'"
  else
    echo "⚠️  Local is $ahead commit(s) ahead and $behind commit(s) behind '$remote'"
    echo -e "\n📋 Commits on remote not in local:"
    git log HEAD.."$remote" --oneline

    echo -e "\n🔍 Run this to view changes:\n  git diff $remote"
  fi
}

I drop this in my shell config (~/.bashrc / ~/.zshrc) and now gcheck is just part of my daily workflow.

Why I like it

• One glance tells you if you’re up to date with upstream.
• If you’re behind, it lists the missing commits so you can see what’s coming.
• If you’re ahead, it reminds you to push.
• If you’re both, then you know it’s merge/rebase time.
• And if you’re not even in a Git repo, it politely tells you. I do that all the time so it’s much appreciated.

Handy Aliases

I use the following aliases in my environments. glo is especially useful but long and hard to remember. The others are nice when you find yourself running the full command for the thousandth time while working on a project. You can simply add the following to your shell startup files (.bashrc or .zshrc) and reload.

# Git
alias gs='git status'
alias glo='git log --oneline --graph --decorate --all'
alias ga='git add'
alias gc='git commit'
alias gd='git diff'
alias gco='git checkout'
alias gp='git push'
alias gl='git pull'
alias gitcha='gcheck' # an alias i'm used to for the gcheck function

Links & Stuff

Core Learning Resources

• Pro Git book (free online) — The definitive Git reference
• Atlassian Git Tutorials — Visual, task-oriented guides
• Learn Git Branching — Interactive visual tutorial
• Git Immersion — Hands-on walkthrough tutorial
• Git (Wikipedia) — History, design, and technical details

Visual & Interactive Tools

• Git Graph (VS Code extension) — Visual repo browser
• GitKraken — Popular GUI client
• Sourcetree — Free visual Git client

Advanced/Specialized

• Oh Shit, Git!?! — How to fix common Git mistakes
• Git Magic — Advanced concepts explained simply
• nbdime — Better jupyter notebook diffs for data science
• pre-commit — Git hooks framework for code quality

Quick Reference

• Git Cheat Sheet (GitHub) — Official PDF cheat sheet

Conclusion

Git is a deep and sometimes intimidating system, but it is a really powerful part of a project or workflow.

With just a handful of concepts, a few daily commands, and some helpers like gcheck, you can navigate most workflows with confidence.

feedback@adminjitsu.com.