ohmyzsh/tools/UPDATE_PROCESS.md

check_for_upgrade.sh: Update Process

Visual State Diagram

stateDiagram-v2
    [*] --> Bootstrap

    state Bootstrap {
      [*] --> CheckLegacyUpdateFile
      CheckLegacyUpdateFile: check [[ -f ~/.zsh-update && ! -f $ZSH_CACHE_DIR/.zsh-update ]]
      CheckLegacyUpdateFile --> MigrateLegacyFile: TRUE
      CheckLegacyUpdateFile --> LoadMode: FALSE
      MigrateLegacyFile: mv ~/.zsh-update $ZSH_CACHE_DIR/.zsh-update
      MigrateLegacyFile --> LoadMode

      LoadMode: read update mode from zstyle
      LoadMode --> LegacyModeFallback: fail
      LegacyModeFallback: set update_mode=prompt
      LegacyModeFallback --> LegacyPromptFlag
      LegacyPromptFlag: evaluate DISABLE_UPDATE_PROMPT
      LegacyPromptFlag --> LegacyAutoFlag
      LegacyAutoFlag: evaluate DISABLE_AUTO_UPDATE
      LegacyAutoFlag --> PreFlightGate
      LoadMode --> PreFlightGate: success
    }

    PreFlightGate: aggregated early-return gate
    PreFlightGate --> ExitNoUpdate: mode=disabled
    PreFlightGate --> ExitNoUpdate: write permission or owner check failed
    PreFlightGate --> ExitNoUpdate: tty gate failed
    PreFlightGate --> ExitNoUpdate: git command unavailable
    PreFlightGate --> ExitNoUpdate: repository check failed
    PreFlightGate --> ModeDispatch: all checks pass
    ExitNoUpdate: unset update_mode; return

    state ModeDispatch {
      [*] --> SetupBackgroundHooks: mode=background-alpha
      [*] --> RunHandleUpdate: otherwise
    }

    SetupBackgroundHooks: autoload -Uz add-zsh-hook
    SetupBackgroundHooks --> RegisterBgPrecmd
    RegisterBgPrecmd: add-zsh-hook precmd _omz_bg_update
    RegisterBgPrecmd --> BackgroundStatusHook

    RunHandleUpdate --> HandleUpdateCore

    state HandleUpdateCore {
      [*] --> LockCleanupCheck
      LockCleanupCheck: load datetime and read lock mtime
      LockCleanupCheck --> CheckStaleAge: lock exists
      LockCleanupCheck --> AcquireLock: no lock

      CheckStaleAge: stale if lock older than 24h
      CheckStaleAge --> RemoveStaleLock: TRUE
      CheckStaleAge --> AcquireLock: FALSE

      RemoveStaleLock: rm -rf $ZSH/log/update.lock
      RemoveStaleLock --> AcquireLock

      AcquireLock: mkdir $ZSH/log/update.lock
      AcquireLock --> ExitHandle: fail (lock exists)
      AcquireLock --> InstallTrap: success

      InstallTrap: install trap to cleanup lock and functions
      InstallTrap --> LoadStatusFile

      LoadStatusFile: source status file and validate last epoch
      LoadStatusFile --> InitStatusFile: fail or empty LAST_EPOCH
      LoadStatusFile --> FrequencyCheck: success

      InitStatusFile: update_last_updated_file
      InitStatusFile --> ExitHandle

      FrequencyCheck: resolve frequency from zstyle or default
      FrequencyCheck --> PeriodElapsed

      PeriodElapsed: enough days elapsed since last check
      PeriodElapsed --> RepoCheck: TRUE
      PeriodElapsed --> ExitHandle: FALSE

      RepoCheck: verify ZSH path is a git repository
      RepoCheck --> CheckUpdateAvailable: success
      RepoCheck --> ExitHandle: fail

      CheckUpdateAvailable --> ReminderOrTypedInput: update available (return 0)
      CheckUpdateAvailable --> ExitHandleWithTimestamp: no update (return 1)

      ExitHandleWithTimestamp: update_last_updated_file
      ExitHandleWithTimestamp --> ExitHandle

      ReminderOrTypedInput --> ReminderExit: mode=reminder
      ReminderOrTypedInput --> TypedInputCheck: mode!=background-alpha
      ReminderOrTypedInput --> ModeAutoGate: mode=background-alpha

      TypedInputCheck: detect pending typed input from terminal
      TypedInputCheck --> ReminderExit: input detected
      TypedInputCheck --> ModeAutoGate: no input

      ReminderExit: echo reminder message
      ReminderExit --> ExitHandle

      ModeAutoGate --> RunUpgrade: mode is auto or background alpha
      ModeAutoGate --> PromptUser: mode=prompt

      PromptUser: read -r -k 1 option
      PromptUser --> RunUpgrade: yes or enter
      PromptUser --> WriteTimestampOnly: [nN]
      PromptUser --> ManualMsg: other

      WriteTimestampOnly: update_last_updated_file
      WriteTimestampOnly --> ManualMsg

      ManualMsg: echo manual update hint
      ManualMsg --> ExitHandle

      RunUpgrade --> ExitHandle
      ExitHandle --> [*]
    }

    state CheckUpdateAvailable {
      [*] --> ReadBranch
      ReadBranch: read configured branch default master
      ReadBranch --> ReadRemote
      ReadRemote: read configured remote default origin
      ReadRemote --> ReadRemoteUrl
      ReadRemoteUrl: read remote URL from git config
      ReadRemoteUrl --> ParseRemoteStyle

      ParseRemoteStyle --> AssumeUpdateYes: non-GitHub remote
      ParseRemoteStyle --> ValidateOfficialRepo: GitHub URL

      ValidateOfficialRepo --> AssumeUpdateYes: repo != ohmyzsh/ohmyzsh
      ValidateOfficialRepo --> LocalHeadCheck: repo == ohmyzsh/ohmyzsh

      LocalHeadCheck: resolve local branch HEAD hash
      LocalHeadCheck --> AssumeUpdateYes: fail
      LocalHeadCheck --> RemoteHeadFetch: success

      RemoteHeadFetch --> UseCurl: curl available
      RemoteHeadFetch --> UseWget: wget available
      RemoteHeadFetch --> UseFetch: fetch available
      RemoteHeadFetch --> AssumeUpdateNo: none available

      UseCurl: fetch remote head using curl
      UseWget: fetch remote head using wget
      UseFetch: fetch remote head using fetch utility

      UseCurl --> CompareHeads: success
      UseCurl --> AssumeUpdateNo: fail
      UseWget --> CompareHeads: success
      UseWget --> AssumeUpdateNo: fail
      UseFetch --> CompareHeads: success
      UseFetch --> AssumeUpdateNo: fail

      CompareHeads: compare local and remote head hashes
      CompareHeads --> MergeBaseCheck: TRUE
      CompareHeads --> AssumeUpdateNo: FALSE

      MergeBaseCheck: compute merge base from both hashes
      MergeBaseCheck --> AssumeUpdateYes: fail
      MergeBaseCheck --> EvaluateAncestry: success

      EvaluateAncestry: decide if local is behind remote
      EvaluateAncestry --> AssumeUpdateYes: TRUE
      EvaluateAncestry --> AssumeUpdateNo: FALSE

      AssumeUpdateYes --> [*]
      AssumeUpdateNo --> [*]
    }

    state RunUpgrade {
      [*] --> ResolveVerbose
      ResolveVerbose: resolve verbose mode from zstyle
      ResolveVerbose --> CheckP10kPrompt

      CheckP10kPrompt: check instant prompt setting
      CheckP10kPrompt --> ForceSilent: TRUE
      CheckP10kPrompt --> UpgradePath: FALSE

      ForceSilent: verbose_mode=silent
      ForceSilent --> UpgradePath

      UpgradePath --> InteractiveUpgrade: mode != background-alpha
      UpgradePath --> SilentCaptureUpgrade: mode=background-alpha

      InteractiveUpgrade: run upgrade script with interactive verbosity
      InteractiveUpgrade --> UpdateTimestampOnly: success
      InteractiveUpgrade --> SilentCaptureUpgrade: fail

      SilentCaptureUpgrade: run upgrade script and capture output
      SilentCaptureUpgrade --> UpdateSuccessStatus: success
      SilentCaptureUpgrade --> UpdateErrorStatus: fail

      UpdateTimestampOnly: update_last_updated_file
      UpdateSuccessStatus: write status file with success
      UpdateErrorStatus: write status file with captured error

      UpdateTimestampOnly --> [*]
      UpdateSuccessStatus --> [*]
      UpdateErrorStatus --> [*]
    }

    state BackgroundStatusHook {
      [*] --> RegisterStatusHook
      RegisterStatusHook: register precmd status hook
      RegisterStatusHook --> PollStatus

      PollStatus: poll status file on each precmd
      PollStatus --> WaitMore: status file not ready
      PollStatus --> PrintSuccess: EXIT_STATUS==0
      PollStatus --> PrintFailure: EXIT_STATUS!=0

      WaitMore: return 1 (continue polling)
      WaitMore --> [*]

      PrintSuccess: print success message
      PrintSuccess --> CleanupStatusHook

      PrintFailure: print error message with details
      PrintFailure --> CleanupStatusHook

      CleanupStatusHook: reset status file and deregister status hook
      CleanupStatusHook --> [*]
    }

    SetupBackgroundHooks --> BackgroundStatusHook
    ExitNoUpdate --> [*]

---

State Transition Table

BOOTSTRAP Phase

State	Condition	Command/Check	Next State
START	—	—	CheckLegacyUpdateFile
CheckLegacyUpdateFile	[[ -f ~/.zsh-update && ! -f $ZSH_CACHE_DIR/.zsh-update ]]	TRUE	MigrateLegacyFile
CheckLegacyUpdateFile	—	FALSE (no legacy file)	LoadMode
MigrateLegacyFile	—	mv ~/.zsh-update $ZSH_CACHE_DIR/.zsh-update	LoadMode
LoadMode	zstyle -s ':omz:update' mode update_mode	SUCCESS	PreFlightGate
LoadMode	—	FAIL (zstyle missing)	LegacyModeFallback
LegacyModeFallback	—	set update_mode=prompt (default)	LegacyPromptFlag
LegacyPromptFlag	[[ $DISABLE_UPDATE_PROMPT != true ]]	TRUE	LegacyAutoFlag
LegacyPromptFlag	—	FALSE	SetAutoMode
SetAutoMode	—	update_mode=auto	LegacyAutoFlag
LegacyAutoFlag	[[ $DISABLE_AUTO_UPDATE != true ]]	TRUE	PreFlightGate
LegacyAutoFlag	—	FALSE	SetDisabledMode
SetDisabledMode	—	update_mode=disabled	PreFlightGate

---

PRE-FLIGHT GATE (Early Exit Checks)

State	Condition	Command/Check	Next State
PreFlightGate	[[ $update_mode = disabled ]]	TRUE	ExitNoUpdate
PreFlightGate	[[ ! -w $ZSH || ! -O $ZSH ]]	TRUE	ExitNoUpdate
PreFlightGate	[[ ! -t 1 && ${POWERLEVEL9K_INSTANT_PROMPT:-off} == off ]]	TRUE	ExitNoUpdate
PreFlightGate	! command git --version 2>&1 >/dev/null	TRUE	ExitNoUpdate
PreFlightGate	(cd $ZSH; ! git rev-parse --is-inside-work-tree &>/dev/null)	TRUE	ExitNoUpdate
PreFlightGate	—	ALL FALSE	ModeDispatch
ExitNoUpdate	—	unset update_mode; return	[*]

---

MODE DISPATCH & BACKGROUND SETUP

State	Condition	Command/Check	Next State
ModeDispatch	[[ $update_mode = background-alpha ]]	TRUE	SetupBackgroundHooks
ModeDispatch	—	FALSE	RunHandleUpdate
SetupBackgroundHooks	—	autoload -Uz add-zsh-hook	RegisterBgPrecmd
RegisterBgPrecmd	—	add-zsh-hook precmd _omz_bg_update	BackgroundStatusHook
RunHandleUpdate	—	enter HandleUpdateCore	HandleUpdateCore

---

HANDLE UPDATE CORE (Main Logic)

Lock Management

State	Condition	Command/Check	Next State
HandleUpdateCore	—	zmodload zsh/datetime	LockCleanupCheck
LockCleanupCheck	zstat +mtime $ZSH/log/update.lock 2>/dev/null	SUCCESS (mtime exists)	CheckStaleAge
LockCleanupCheck	—	FAIL (no lock file)	AcquireLock
CheckStaleAge	(mtime + 86400) < EPOCHSECONDS	TRUE (older than 24h)	RemoveStaleLock
CheckStaleAge	—	FALSE	AcquireLock
RemoveStaleLock	—	rm -rf $ZSH/log/update.lock	AcquireLock
AcquireLock	mkdir $ZSH/log/update.lock 2>/dev/null	SUCCESS	InstallTrap
AcquireLock	—	FAIL (lock exists)	ExitHandle
InstallTrap	—	trap "...cleanup..." EXIT INT QUIT	LoadStatusFile

Status File Validation

State	Condition	Command/Check	Next State
LoadStatusFile	source $ZSH_CACHE_DIR/.zsh-update 2>/dev/null && [[ -n $LAST_EPOCH ]]	SUCCESS	FrequencyCheck
LoadStatusFile	—	FAIL or missing LAST_EPOCH	InitStatusFile
InitStatusFile	—	update_last_updated_file (writes LAST_EPOCH)	ExitHandle

Frequency Check

State	Condition	Command/Check	Next State
FrequencyCheck	zstyle -s ':omz:update' frequency epoch_target	SUCCESS	PeriodElapsed
FrequencyCheck	—	FAIL	SetDefaultFrequency
SetDefaultFrequency	—	epoch_target=${UPDATE_ZSH_DAYS:-13}	PeriodElapsed
PeriodElapsed	(current_epoch - LAST_EPOCH) >= epoch_target	TRUE	RepoCheck
PeriodElapsed	—	FALSE	ExitHandle

Git Repository Check

State	Condition	Command/Check	Next State
RepoCheck	(cd $ZSH && LANG= git rev-parse)	SUCCESS	CheckUpdateAvailable
RepoCheck	—	FAIL	ExitHandle

Post-Update Decision

State	Condition	Command/Check	Next State
CheckUpdateAvailable	—	function returns TRUE	ReminderOrTypedInput
CheckUpdateAvailable	—	function returns FALSE	ExitHandleWithTimestamp
ExitHandleWithTimestamp	—	update_last_updated_file	ExitHandle

---

REMINDER OR INPUT CHECK

State	Condition	Command/Check	Next State
ReminderOrTypedInput	[[ $update_mode = reminder ]]	TRUE	ReminderExit
ReminderOrTypedInput	[[ $update_mode != background-alpha ]]	TRUE	TypedInputCheck
ReminderOrTypedInput	—	FALSE (background-alpha)	ModeAutoGate
TypedInputCheck	has_typed_input	TRUE	ReminderExit
TypedInputCheck	—	FALSE	ModeAutoGate
ReminderExit	—	echo "[oh-my-zsh] It's time to update!..."	ExitHandle

has_typed_input internals:

• stty --save
• stty -icanon
• zselect -t 0 -r 0 (poll stdin fd 0)
• stty $termios (restore)

---

UPDATE MODE GATE

State	Condition	Command/Check	Next State
ModeAutoGate	[[ $update_mode = (auto|background-alpha) ]]	TRUE	RunUpgrade
ModeAutoGate	—	FALSE (prompt)	PromptUser

Prompt Mode

State	Condition	Command/Check	Next State
PromptUser	—	read -r -k 1 option	ProcessResponse
ProcessResponse	[[ $option = [yY$'\n'] ]]	TRUE	RunUpgrade
ProcessResponse	[[ $option = [nN] ]]	TRUE	WriteTimestampOnly
ProcessResponse	—	OTHER	ManualMsg
WriteTimestampOnly	—	update_last_updated_file	ManualMsg
ManualMsg	—	echo "[oh-my-zsh] You can update manually..."	ExitHandle

---

RUN UPGRADE SUBPROCESS

State	Condition	Command/Check	Next State
RunUpgrade	—	zstyle -s ':omz:update' verbose verbose_mode	ResolveVerbose
ResolveVerbose	—	SET to default if missing	CheckP10kPrompt
CheckP10kPrompt	[[ ${POWERLEVEL9K_INSTANT_PROMPT:-off} != off ]]	TRUE	ForceSilent
CheckP10kPrompt	—	FALSE	UpgradePath
ForceSilent	—	verbose_mode=silent	UpgradePath
UpgradePath	[[ $update_mode != background-alpha ]]	TRUE	InteractiveUpgrade
UpgradePath	—	FALSE	SilentCaptureUpgrade

Interactive Mode (TTY + user interaction)

State	Condition	Command/Check	Next State
InteractiveUpgrade	LANG= ZSH=$ZSH zsh -f $ZSH/tools/upgrade.sh -i -v $verbose_mode	SUCCESS (exit 0)	UpdateTimestampOnly
InteractiveUpgrade	—	FAIL (exit >0)	SilentCaptureUpgrade
UpdateTimestampOnly	—	update_last_updated_file	ExitHandle

Silent Mode (Background/Capture)

State	Condition	Command/Check	Next State
SilentCaptureUpgrade	error=$(LANG= ZSH=$ZSH zsh -f $ZSH/tools/upgrade.sh -i -v silent 2>&1)	SUCCESS	UpdateSuccessStatus
SilentCaptureUpgrade	—	FAIL (nonzero exit)	UpdateErrorStatus
UpdateSuccessStatus	—	update_last_updated_file 0 "Update successful"	ExitHandle
UpdateErrorStatus	—	update_last_updated_file $exit_status "$error"	ExitHandle

---

CHECK UPDATE AVAILABLE (Nested Function)

Configuration Retrieval

State	Condition	Command/Check	Next State
CheckUpdateAvailable	—	cd $ZSH; git config --local oh-my-zsh.branch	ReadRemote
ReadRemote	—	cd $ZSH; git config --local oh-my-zsh.remote	ReadRemoteUrl
ReadRemoteUrl	—	cd $ZSH; git config remote.$remote.url	ParseRemoteStyle

Remote Validation

State	Condition	Command/Check	Next State
ParseRemoteStyle	URL matches https://github.com/* or git@github.com:*	TRUE	ValidateOfficialRepo
ParseRemoteStyle	—	FALSE (non-GitHub)	AssumeUpdateYes
ValidateOfficialRepo	[[ $repo = ohmyzsh/ohmyzsh ]]	TRUE	LocalHeadCheck
ValidateOfficialRepo	—	FALSE	AssumeUpdateYes

Local HEAD Retrieval

State	Condition	Command/Check	Next State
LocalHeadCheck	cd $ZSH; git rev-parse $branch 2>/dev/null	SUCCESS	RemoteHeadFetch
LocalHeadCheck	—	FAIL	AssumeUpdateYes

Remote HEAD Fetch (Prefer curl > wget > fetch)

State	Condition	Command/Check	Next State
RemoteHeadFetch	(( ${+commands[curl]} ))	TRUE	UseCurl
RemoteHeadFetch	(( ${+commands[wget]} ))	TRUE	UseWget
RemoteHeadFetch	(( ${+commands[fetch]} ))	TRUE	UseFetch
RemoteHeadFetch	—	NONE (no http tool)	AssumeUpdateNo
UseCurl	curl --connect-timeout 2 -fsSL -H 'Accept: application/vnd.github.v3.sha' $api_url 2>/dev/null	SUCCESS	CompareHeads
UseCurl	—	FAIL	AssumeUpdateNo
UseWget	wget -T 2 -O- --header='Accept: application/vnd.github.v3.sha' $api_url 2>/dev/null	SUCCESS	CompareHeads
UseWget	—	FAIL	AssumeUpdateNo
UseFetch	HTTP_ACCEPT='...' fetch -T 2 -o - $api_url 2>/dev/null	SUCCESS	CompareHeads
UseFetch	—	FAIL	AssumeUpdateNo

Head Comparison

State	Condition	Command/Check	Next State
CompareHeads	[[ $local_head != $remote_head ]]	TRUE	MergeBaseCheck
CompareHeads	—	FALSE (equal)	AssumeUpdateNo

Ancestry Check

State	Condition	Command/Check	Next State
MergeBaseCheck	cd $ZSH; git merge-base $local_head $remote_head 2>/dev/null	SUCCESS	EvaluateAncestry
MergeBaseCheck	—	FAIL	AssumeUpdateYes
EvaluateAncestry	[[ $base != $remote_head ]]	TRUE	AssumeUpdateYes
EvaluateAncestry	—	FALSE	AssumeUpdateNo

Results

State	Condition	Command/Check	Next State
AssumeUpdateYes	—	return 0 (update available)	return from function
AssumeUpdateNo	—	return 1 (no update)	return from function

---

BACKGROUND UPDATE STATUS HOOK

State	Condition	Command/Check	Next State
BackgroundStatusHook	—	register precmd → _omz_bg_update_status	PollStatus
PollStatus	[[ ! -f $ZSH_CACHE_DIR/.zsh-update ]]	TRUE	WaitMore
PollStatus	source $ZSH_CACHE_DIR/.zsh-update	SUCCESS + [[ -z $EXIT_STATUS || -z $ERROR ]]	WaitMore
PollStatus	[[ $EXIT_STATUS -eq 0 ]]	TRUE	PrintSuccess
PollStatus	[[ $EXIT_STATUS -ne 0 ]]	TRUE	PrintFailure
WaitMore	—	return 1 (continue polling on next precmd)	PollStatus (next precmd)
PrintSuccess	—	print -P "\n%F{green}[oh-my-zsh] Update successful.%f"	CleanupStatusHook
PrintFailure	—	print -P "\n%F{red}[oh-my-zsh] There was an error updating:%f"; printf "${ERROR}"	CleanupStatusHook
CleanupStatusHook	(( TRY_BLOCK_ERROR == 0 ))	TRUE	DeregisterHook
DeregisterHook	—	update_last_updated_file (reset status file)	DeregisterStatusFunc
DeregisterStatusFunc	—	add-zsh-hook -d precmd _omz_bg_update_status	[*]

---

EXIT & CLEANUP

State	Condition	Command/Check	Next State
ExitHandle	—	trap fires (EXIT/INT/QUIT) → rm -rf $ZSH/log/update.lock	TrapExit
TrapExit	—	unset update_mode	TrapExit2
TrapExit	—	unset -f current_epoch is_update_available ...	TrapExit2
TrapExit2	—	return $ret	[*]

---

Key Functions (Always Available)

current_epoch()

zmodload zsh/datetime
echo $(( EPOCHSECONDS / 60 / 60 / 24 ))

Returns the current day count since epoch.

is_update_available()

Returns 0 (update available) or 1 (no update).
See "CHECK UPDATE AVAILABLE" section above.

update_last_updated_file()

• Called with no args → writes LAST_EPOCH=$(current_epoch)
• Called with exit_status and error → writes status + error msg

update_ohmyzsh()

Calls upgrade.sh subprocesses (interactive or silent capture).
Returns exit code of upgrade operation.

has_typed_input()

Polls stdin with stty/zselect. Returns 0 if input detected, 1 if not.

---

Summary Statistics

• Total States (conceptual): 60+
• Total Transitions: 80+
• Early Exit Points (PreFlightGate): 5 conditions
• Update Decision Points: 3 (mode, frequency, availability)
• User Prompt Paths: 2 (prompt mode vs. auto)
• Background Poller States: 4
• Nested Function Depth: 2 (handle_update → is_update_available)