sqitchchanges(3pm)

✨ sqitchchanges ✨

okay bestie, so this is the manual page for sqitchchanges, from the User Contributed Perl Documentation collection (it's a Perl module page, sqitchchanges(3pm), iykyk 💅). it's literally the guide to how you spell out changes when you talk to Sqitch. buckle up, it's giving "actually important" energy. 🦋

---

🌸 DESCRIPTION 🌸

so many Sqitch commands take change parameters as arguments. and what those parameters mean depends on the command, no cap:

• sometimes they point at one specific change
• sometimes — for commands that walk the change history or the change plan, like sqitch log — they mean every change you can reach from that change

and here's the little plot twist: most commands go searching the plan for the relevant change. but a few of them, like sqitch revert and sqitch log, go searching the database instead. main character behavior honestly. 👑

---

🎀 Change Names 🎀

a change name is the thing you pass to sqitch add and the thing that gets written into the plan file. and bestie, it has rules. here they are, all of them, don't skip:

• must be at least one character. one. minimum. that's the floor.
• must contain no blank characters. none. zero. 🙈
• the first character may not be punctuation
• the last letter may not be punctuation
• must not end in ~, ^, /, =, or % followed by digits
• every other character may be any UTF-8 character other than :, @, #, and \

💡 heads up: _ (underscore) is never considered punctuation. periodt.

some examples of names that slay (valid):

"foo"
12
"t"
6
"阱阪阬"
"阱阪阬92"
"foo/bar"
"beta1"
"foo_"
"_foo"
"v1.0-1b"
"v1.2-1"
"v1.2+1"
"v1.2_1"

and some examples of names that do NOT pass the vibe check (invalid):

"^foo"
"foo^"
"foo^6"
"foo^666"
%hi
"hi!"
"foo@bar"
"foo:bar"
"foo\bar"
"+foo"
"-foo"
@foo

---

💖 Tag Names 💖

a tag name is what you hand to sqitch tag and what gets written into the plan file. tags follow the exact same rules as Change Names above, with literally just one extra limitation: tags must not contain a slash character (/).

so here's a name that's a perfectly valid change name but an invalid tag name, iconic little gremlin that it is:

"foo/bar"

---

🌈 Specifying Changes 🌈

a change parameter names a change object. it uses something called an extended SHA1 syntax. here are all the ways you can spell a change name, one by one:

• <change_name>, e.g., users_table — the name of a change itself, exactly as it was added to the plan via sqitch add. 💫
• @<tag_name>, e.g., @rc1 — the change as of the named tag. tags get added to the plan via sqitch tag.
• <change_name>@<tag_name>, e.g., users_table@beta1 — the named change as of a tag, aka a tag-qualified change name. for change iteration commands (like sqitch log), this means the instance of a change with that name before the specified tag. for dependency parameters (like in sqitch add), this means any instance of a change just before that tag, or at any time after the tag.
• <sha1>, e.g., 40763784148fa190d75bad036730ef44d1c2eac6 — the change's full SHA1 ID (that's a 40-byte hexadecimal string, bestie). in some cases, like sqitch add, that ID may refer to a change in another Sqitch project. 😳
• <project>:<change_name>, e.g., mybase:users_table — the name of a change in a specific project. non-SHA1 change parameters without a project prefix are assumed to belong to the current project. most useful for declaring a dependency on a change from another project in sqitch add.
• <project>:@<tag_name>, e.g., mybase:@rc1 — the name of a tag in the named project.
• <project>:<change_name>@<tag_name>, e.g., project:users_table@beta1 — a tag-qualified named change in the named project.
• <project>:<sha1>, e.g., mybase:40763784148fa190d75bad036730ef44d1c2eac6 — the full SHA1 ID from another project. probably redundant, since the SHA1 ID should itself be sufficient. but it's useful for declaring dependencies in the current project so that sqitch add or sqitch rework will validate that the specified change is in the current project. 🧚
• @HEAD, HEAD — special symbolic name for the last change in the plan.
• @ROOT, ROOT — special symbolic name for the first change in the plan.
• <change>^, e.g., @HEAD^^, @HEAD^3, @beta^2 — a ^ suffix on a symbolic or actual name means the change prior to that change. two ^s means the second prior change. and you can add more prior changes as ^<n>, where <n> is the number of changes to go back. ⏪
• <change>~, e.g., @ROOT~, @ROOT~~, @bar~4 — a ~ suffix on a symbolic or actual name means the change after that change. two ~s means the second following change. and you can add more following changes as ~<n>, where <n> is the number of changes to go forward. ⏩

---

👑 Sqitch 👑

part of the sqitch suite. that's it, that's the section. 💜

---

okay that's the whole page, bestie!! 🫶 this was sqitchchanges(3pm), and per the little footer magic it's from perl v5.40.1, dated 2026-07-26. go forth and spell your changes correctly, mwah 💅✨🎀