SVK::XD(3)

🌸 NAME 🌸

okay bestie, welcome to the SVK::XD(3) page — fresh out of the User Contributed Perl Documentation collection — and it's literally all about svk depot and checkout handling. that's it. that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

here's the little summoning ritual, copy it exactly bestie:

use SVK::XD;
$xd = SVK::XD->new (depotmap => { '' => '/path/to/repos'});

---

🎀 TERMINOLOGY 🎀

okay vocab check, we're doing this before the code so nobody gets lost:

• depot — a repository that gets referred to by a name. the default depot is '' (yes, the empty string, she's mysterious like that).
• depotpath — a path that's identified by a depot name plus the path inside the depot. so for example //foo/bar means /foo/bar inside the default depot '', and /test/foo/bar means /foo/bar inside the depot test. iykyk 🦋
• copath — checkout path. a path on your actual file system that has a checked out version of a certain depotpath. your local girlie. 💖

---

👑 CONSTRUCTOR 👑

the options you can hand to new, and yes we're going through every single one:

• depotmap — a hash reference mapping depot name ➡️ repository path. the matchmaker. 🫶
• checkout — a Data::Hierarchy object that maps checkout paths.
• giantlock — a filename used for global locking. this file is the bouncer protecting all read and write accesses to the statefile. 🚨

so here's the whole saga: when SVK begins to execute any command, it attempts to get a write lock on this "giant lock" file. once it gets that lock, it writes its PID into the file, reads in its statefile, and starts executing the command. executing the command has two phases, a lock phase and a run phase. and during the lock phase, a command can do one of three things:

1. request to keep the giant lock for the entire execution — this is for commands that modify big chunks of the statefile.
2. request to lock individual checkout paths.
3. not request a lock at all. iconic, unbothered.

so in the first case, the command sets the hold_giant field on the SVK::Command object (and the page itself says this should probably change to a real API, so like, noted 📝), and the command does not release the giant lock until it's finished. it can rewrite the statefile at the end of its execution without waiting on the lock, because it's already holding it. main character energy, honestly.

in the second case, the command calls lock on the SVK::XD object one or more times. this places a lock entry inside the Data::Hierarchy object in the statefile right next to each locked path — unless they're already locked by another process, in which case, nope. between its lock phase and its run phase, the statefile gets written to disk (with those new lock entries) and the giant lock is dropped. then after the run phase, SVK acquires the giant lock again, reads in the statefile, copies all entries from the paths it has locked into the version it just read, clears the lock entries out of the hierarchy, writes the statefile to disk, and drops the giant lock. and heads up: any changes to the hierarchy other than in the locked paths will be ignored. 🙈

in the third case? SVK just drops the giant lock after the lock phase and never tries to read or write the statefile again. ghosted. 💀

• statefile — the filename used for serializing the SVK::XD object.
• svkpath — the directory name where giantlock and statefile live. 🏠

---

🔥 METHODS 🔥

💜 Serialization and locking 💜

• load — loads the serialized SVK::XD data from statefile. if there's nothing to load, it initializes $self. and the giant lock gets acquired when you call load. ✨
• store, store — (yes bestie, the page lists store twice, we do not question the icon) serialize $self to the statefile. if the giant lock is still ours, it overwrites the file directly. otherwise it loads the file again and merges the paths we locked into the new state file. and once store has been called, giant is unlocked. 🔓
• lock — locks the given checkout path and stores the state with the lock info, so other instances can't go modifying the locked paths. hands off. 🚫
• unlock — unlocks all the checkout paths that were locked by this instance. releasing them back into the wild. 🦋
• giant_lock — locks the statefile globally. every other instance has to wait for the lock before it can do literally anything.
• giant_unlock — releases the giant lock. bye bestie 👋

🌈 Depot and path translation 🌈

• find_repos — give it a depotpath and an option about whether the repository should be opened, and it returns an array of the repository path, the path inside the repository, and the SVN::Repos object — but only if the caller actually wants the repository opened. 💅
• find_repos_from_co — give it the checkout path and an option about whether the repository should be opened, and it returns an array of the repository path, the path inside the repository, the absolute checkout path, the checkout info, and the SVN::Repos object, again only if the caller wants it opened.
• find_repos_from_co_maybe — same energy as find_repos_from_co, but it falls back to checking whether the given path is a depotpath. and in that case, the checkout paths it returns will be undef. surprise! 🎁
• find_depotname — that's it. that's the entry. the source gives us no description, so we simply respect the mystery. 🫡

🧚 create_path_object 🧚

creates and returns a brand new path object. and it can be any of: SVK::Path::Checkout, SVK::Path::View, or SVK::Path. pick your fighter. ⭐

it takes a hash with arguments.

• if the copath_anchor argument is defined, then SVK::Path::Checkout gets created, and the other arguments are used to build its source in SVK::Path::Checkout using this method. and if the revision argument is not defined, then the checkout path it's based on is used.
• if the view argument is defined, then SVK::Path::View gets created, and the other arguments are used to build its source in SVK::Path::Checkout using this method.
• otherwise, SVK::Path gets created. simple as that.

and the depot can be passed as an SVK::Depot object in the depot argument, or by using the depotname, repospath and repos arguments. the object takes precedence. 👑

🍓 Checkout handling 🍓

• auto_prop — returns a hash of the properties that should get attached to the file automatically when it's added. ✨
• depot_delta — generates SVN::Delta::Editor calls to represent the changes between (oldroot, oldpath) and (newroot, newpath). heads up: oldpath is an array ref for anchor and target, while newpath is just a string. options:
  • editor — the editor receiving the delta calls. 📬
  • no_textdelta — don't generate text deltas in apply_textdelta calls.
  • no_recurse
  • notice_ancestry

(the last two are just vibing there with no description, we list them with love 💜)

• checkout_delta — generates SVN::Delta::Editor calls to represent the local changes made to the checked out revision. options:
  • delete_verbose — generate delete_entry calls for sub-entries inside a deleted entry.
  • absent_verbose — generate absent_* calls for sub-entries inside an absent entry.
  • unknown_verbose — generate cb_unknown calls for sub-entries inside an absent entry.
  • absent_ignore — don't generate absent_* calls. 🙅
  • expand_copy — mimic the behavior of SVN::Repos::dir_delta: lose the copy information and treat all copied descendents as added too.
  • cb_ignored — called for ignored items, if defined.
  • cb_unchanged — called for unchanged files, if defined.
• get_entry($copath) — returns the Data::Hierarchy entry and the schedule of that entry. 🔍
• get_fh — returns a file handle with keyword translation and line-ending layers attached.
• get_props — returns the properties associated with a node. and if $copath is given, the properties scheduled for commit get merged in too. 💖

---

and that's the whole page bestie, every flag, every argument, every default, no skips, no cap. 🫶

perl v5.42.0 ✨ 2025-07-25 — mwah, go forth and handle those depots, you ate 💅👑