---
name: "sqitchchanges"
section: "3pm"
platform: "linux"
package: "sqitch"
version: "1.5.2-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/sqitchchanges"
---

# sqitchchanges(3pm)

Specifying changes for Sqitch

## Name

sqitchchanges - Specifying changes for Sqitch

## Description

Many Sqitch commands take change parameters as arguments. Depending on the command, they denote a specific change or, for commands which walk change history or the change plan (such as `"sqitch log"`), all changes which can be reached from that change. Most commands search the plan for the relevant change, though some, such as `"sqitch revert"` and `"sqitch log"`, search the database for the change.

### Change Names

A change name, such as that passed to `"sqitch add"` and written to the plan file, has a few limitations on the characters it may contain. The rules are:

- •

  Must be at least one character.

- •

  Must contain no blank characters.

- •

  The first character may not be punctuation.

- •

  Last letter may not be punctuation.

- •

  Must not end in "~", "^", "/", "=", or "%" followed by digits.

- •

  All other characters may be any UTF-8 character other than ":", "@", "#", and "\\".

Note that "\_" (underscore) is never considered punctuation. Some examples of valid names:

- "foo"

  - 12

  - "t"

  - 6

  - "阱阪阬"

  - "阱阪阬92"

  - "foo/bar"

  - "beta1"

  - "foo\_"

  - "\_foo"

  - "v1.0-1b"

  - "v1.2-1"

  - "v1.2+1"

  - "v1.2\_1"

  Some examples of invalid names:

- "^foo"

  - "foo^"

  - "foo^6"

  - "foo^666"

  - %hi

  - "hi!"

  - "foo@bar"

  - "foo:bar"

  - "foo\\bar"

  - "+foo"

  - "-foo"

  - @foo

  ### Tag Names

A tag name, such as that passed to `"sqitch tag"` and written to the plan file, adhere by the same rules as "Change Names" with one additional limitation: tags must not contain a slash character ("/"). Example valid change name but invalid tag name:

- "foo/bar"

  ## Specifying Changes

A change parameter names a change object. It uses what is called an extended SHA1 syntax. Here are various ways to spell change names:

- "\<change\_name\>", e.g., "users\_table"

  The name of a change itself, as it was added to the plan via `"sqitch add"`.

- "@\<tag\_name\>", e.g., @rc1

  The change as of the named tag. Tags can be added to the plan via `"sqitch tag"`.

- "\<change\_name\>@\<tag\_name\>", e.g., "users\_table@beta1"

  The named change as of a tag, also known as a tag-qualified change name. For change iteration commands (such as `"sqitch log"`), this means the instance of a change with that name before the specified tag. For dependency parameters (such as 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 full SHA1 ID (40-byte hexadecimal string). In some cases, such as `"sqitch add"`, the 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 an 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 I should itself be sufficient. But 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 `"^"` to a symbolic or actual name means the change *prior* to that change. Two `"^"`s indicate the second prior change. Additional prior changes can be specified as `"^<n>"`, where `"<n>"` represents the number of changes to go back.

- "\<change\>~", e.g., "@ROOT~", "@ROOT~~", "@bar~4"

  A suffix `"~"` to a symbolic or actual name means the change *after* that change. Two `"~"`s indicate the second following change. Additional following changes can be specified as `"~<n>"`, where `"<n>"` represents the number of changes to go forward.

## Sqitch

Part of the sqitch suite.