systemd.time

title: systemd.time(7)

summary: Time and date specifications

text:
# systemd.time(7)

## NAME
systemd.time - Time and date specifications

## DESCRIPTION
In systemd, timestamps, time spans, and calendar events are displayed and may be specified in closely related syntaxes.

## DISPLAYING TIME SPANS
Time spans refer to time durations. On display, systemd will present time spans as a space-separated series of time values each suffixed by a time unit. Example:

```
2h 30min
```

All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is locale-independent, only English names for the time units are used.

## PARSING TIME SPANS
When parsing, systemd will accept the same time span syntax. Separating spaces may be omitted. The following time units are understood:

•usec, us, μs

•msec, ms

•seconds, second, sec, s

•minutes, minute, min, m

•hours, hour, hr, h

•days, day, d

•weeks, week, w

•months, month, M (defined as 30.44 days)

•years, year, y (defined as 365.25 days)

If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as such. In a few cases "ns", "nsec" is accepted too, where the granularity of the time span permits this. Parsing is generally locale-independent, non-English names for the time units are not accepted.

Examples for valid time span specifications:

```
2 h
2hours
48hr
1y 12month
55s500ms
300ms20s 5day
```

One can use the timespan command of systemd-analyze(1) to normalise a textual time span for testing and validation purposes.

Internally, systemd generally operates with microsecond time granularity, while the default time unit in user-configurable time spans is usually seconds (see above). This disparity becomes visible when comparing the same settings in the (high-level) unit file syntax with the matching (more low-level) D-Bus properties (which are what systemctl(1)'s show command displays). The former typically are suffixed with "...Sec" to indicate the default unit of seconds, the latter are typically suffixed with "...USec" to indicate the underlying low-level time unit, even if they both encapsulate the very same settings.

## DISPLAYING TIMESTAMPS
Timestamps refer to specific, unique points in time. On display, systemd will format these in the local timezone as follows:

```
Fri 2012-11-23 23:02:15 CET
```

The weekday is printed in the abbreviated English language form. The formatting is locale-independent.

In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via the "UTC" timezone specifier in the output.

In some cases timestamps are shown with microsecond granularity. In this case, the sub-second remainder is separated by a full stop from the seconds component.

## PARSING TIMESTAMPS
When parsing, systemd will accept a similar syntax, but some fields can be omitted, and the space between the date and time can be replaced with a "T" (à la the RFC 3339[1] profile of ISO 8601); thus, in CET, the following are all identical: "Fri 2012-11-23 23:02:15 CET", "Fri 2012-11-23T23:02:15", "2012-11-23T23:02:15 CET", "2012-11-23 23:02:15".

The timezone defaults to the current timezone if not specified explicitly. It may be given after a space, like above, in which case it can be: "UTC", an entry in the installed IANA timezone database (e.g. "CET", "Asia/Tokyo", where the complete list can be obtained with timedatectl list-timezones (see timedatectl(1))), or "±05", "±0530", "±05:30", "Z".

It may also be affixed directly to the timestamp, in which case it must correspond to one of the formats defined in the RFC 3339[1] profile of ISO 8601: "±05:30" or "Z". Thus, the following are also identical to the above: "2012-11-23T23:02:15+01:00", "2012-11-23 22:02:15Z".

A timestamp can start with a field containing a weekday, which can be in an abbreviated ("Wed") or non-abbreviated ("Wednesday") English language form (case does not matter), regardless of the locale. However, if a weekday is specified and does not match the date, the timestamp is rejected.

If the date is omitted, it defaults to today. If the time is omitted, it defaults to 00:00:00. Fractional seconds can be specified down to 1µs precision. The seconds field can also be omitted, defaulting to 0.

There are special tokens that can be used in place of timestamps: "now" may be used to refer to the current time (or of the invocation of the command that is currently executed). "today", "yesterday", and "tomorrow" refer to 00:00:00 of the current day, the day before, or the next day, respectively.

Relative times are also accepted: a time span (see above) prefixed with "+" is evaluated to the current time plus the specified time span. Correspondingly, a time span that is prefixed with "-" is evaluated to the current time minus the specified time span. Instead of prefixing the time span with "+" or "-", it may also be suffixed with a space and the word "left" or "ago".

Finally, an integer prefixed with "@" is evaluated relative to the UNIX epoch – 1970-01-01 00:00:00 UTC.

Examples for valid timestamps and their normalized form (assuming the current time was 2012-11-23 18:15:22 and the timezone was UTC+8, for example "TZ=:Asia/Shanghai"):

```
  Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13

      2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13

  2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13

     2012-11-23T11:12:13Z → Fri 2012-11-23 19:12:13

   2012-11-23T11:12+02:00 → Fri 2012-11-23 17:12:00

               2012-11-23 → Fri 2012-11-23 00:00:00

                 12-11-23 → Fri 2012-11-23 00:00:00

                 11:12:13 → Fri 2012-11-23 11:12:13

                    11:12 → Fri 2012-11-23 11:12:00

                      now → Fri 2012-11-23 18:15:22

                    today → Fri 2012-11-23 00:00:00

                today UTC → Fri 2012-11-23 16:00:00

                yesterday → Fri 2012-11-22 00:00:00

                 tomorrow → Fri 2012-11-24 00:00:00
tomorrow Pacific/Auckland → Thu 2012-11-23 19:00:00

                 +3h30min → Fri 2012-11-23 21:45:22

                      -5s → Fri 2012-11-23 18:15:17

                11min ago → Fri 2012-11-23 18:04:22

              @1395716396 → Tue 2014-03-25 03:59:56
```

Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable locally, as the timezone component is not understood (unless it happens to be "UTC").

Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated by a full stop from the seconds component. Example:

```
2014-03-25 03:59:56.654563
```

In some cases, systemd will display a relative timestamp (relative to the current time, or the time of invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative timestamp is formatted as follows:

```
2 months 5 days ago
```

Note that a relative timestamp is also accepted where a timestamp is expected (see above).

Use the timestamp command of systemd-analyze(1) to validate and normalize timestamps for testing purposes.

## CALENDAR EVENTS
Calendar events may be used to refer to one or more points in time in a single expression. They form a superset of the absolute timestamps explained above:

```
Thu,Fri 2012-*-1,5 11:12:13
```

The above refers to 11:12:13 of the first or fifth day of any month of the year 2012, but only if that day is a Thursday or Friday.

The weekday specification is optional. If specified, it should consist of one or more English language weekday names, either in the abbreviated (Wed) or non-abbreviated (Wednesday) form (case does not matter), separated by commas. Specifying two weekdays separated by ".." refers to a range of continuous weekdays. "," and ".." may be combined freely.

In the date and time specifications, any component may be specified as "*" in which case any value will match. Alternatively, each component can be specified as a list of values separated by commas. Values may be suffixed with "/" and a repetition value, which indicates that the value itself and the value plus all multiples of the repetition value are matched. Two values separated by ".." may be used to indicate a range of values; ranges may also be followed with "/" and a repetition value, in which case the expression matches all times starting with the start value, and continuing with all multiples of the repetition value relative to the start value, ending at the end value the latest.

A date specification may use "~" to indicate the last day in a month. For example, "*-02~03" means "the third last day in February," and "Mon *-05~07/1" means "the last Monday in May."

The seconds component may contain decimal fractions both in the value and the repetition. All fractions are rounded to 6 decimal places.

Either time or date specification may be omitted, in which case 00:00:00 and *-*-* is implied, respectively. If the seconds component is not specified, ":00" is assumed.

Timezone can be specified as the literal string "UTC", or the local timezone, similar to the supported syntax of timestamps (see above), or the timezone in the IANA timezone database format (also see above).

The following special expressions may be used as shorthands for longer normalized forms:

```
    minutely → *-*-* *:*:00

      hourly → *-*-* *:00:00

       daily → *-*-* 00:00:00

     monthly → *-*-01 00:00:00

      weekly → Mon *-*-* 00:00:00

      yearly → *-01-01 00:00:00

   quarterly → *-01,04,07,10-01 00:00:00
semiannually → *-01,07-01 00:00:00
```

Examples for valid timestamps and their normalized form:

```
  Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00

      Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00

                    Wed *-1 → Wed *-*-01 00:00:00

           Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00

                 Wed, 17:48 → Wed *-*-* 17:48:00
Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03

                *-*-7 0:0:0 → *-*-07 00:00:00

                      10-15 → *-10-15 00:00:00

        monday *-12-* 17:00 → Mon *-12-* 17:00:00

  Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45

       12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00

            12..14:10,20,30 → *-*-* 12..14:10,20,30:00

  mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45

             03-05 08:05:40 → *-03-05 08:05:40

                   08:05:40 → *-*-* 08:05:40

                      05:40 → *-*-* 05:40:00

     Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40

           Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40

           2003-03-05 05:40 → 2003-03-05 05:40:00

 05:40:23.4200004/3.1700005 → *-*-* 05:40:23.420000/3.170001

             2003-02..04-05 → 2003-02..04-05 00:00:00

       2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC

                 2003-03-05 → 2003-03-05 00:00:00

                      03-05 → *-03-05 00:00:00

                     hourly → *-*-* *:00:00

                      daily → *-*-* 00:00:00

                  daily UTC → *-*-* 00:00:00 UTC

                    monthly → *-*-01 00:00:00

                     weekly → Mon *-*-* 00:00:00

    weekly Pacific/Auckland → Mon *-*-* 00:00:00 Pacific/Auckland

                     yearly → *-01-01 00:00:00

                   annually → *-01-01 00:00:00

                      *:2/3 → *-*-* *:02/3:00
```

Calendar events are used by timer units, see systemd.timer(5) for details.

Use the calendar command of systemd-analyze(1) to validate and normalize calendar time specifications for testing purposes. The tool also calculates when a specified calendar event would occur next.

## SEE ALSO
systemd(1), journalctl(1), systemd.timer(5), systemd.unit(5), systemd.directives(7), systemd-analyze(1)

## NOTES
1.

RFC 3339

https://tools.ietf.org/html/rfc3339


systemd.v

package: systemd

title: systemd.v(7)

summary: Directory with Versioned Resources

text:
# systemd.v(7)

## NAME
systemd.v - Directory with Versioned Resources

## DESCRIPTION
In various places systemd components accept paths whose trailing components have the ".v/" suffix, pointing to a directory. These components will then automatically look for suitable files inside the directory, do a version comparison and open the newest file found (by version). Available since version v256. Specifically, two expressions are supported:

•When looking for files with a suffix .SUFFIX, and a path ...PATH/NAME.SUFFIX.v/ is specified, then all files ...PATH/NAME.SUFFIX.v/NAME_*.SUFFIX are enumerated, filtered, sorted and the newest file used. The primary sorting key is the variable part, here indicated by the wildcard "*".

•When a path ...PATH.v/NAME___.SUFFIX is specified (i.e. the penultimate component of the path ends in ".v" and the final component contains a triple underscore), then all files ...PATH.v/NAME_*.SUFFIX are enumerated, filtered, sorted and the newest file used (again, by the variable part, here indicated by the wildcard "*").

To illustrate this in an example, consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with three files:

•mymachine_7.5.13.raw

•mymachine_7.5.14.raw

•mymachine_7.6.0.raw

Invoke a tool such as systemd-nspawn(1) with a command line like the following:

```
# systemd-nspawn --image=/var/lib/machines/mymachine.raw.v --boot
```

Then this would automatically be resolved to the equivalent of:

```
# systemd-nspawn --image=/var/lib/machines/mymachine.raw.v/mymachine_7.6.0.raw --boot
```

Much of systemd's functionality that expects a path to a disk image or OS directory hierarchy support the ".v/" versioned directory mechanism, for example systemd-nspawn(1), systemd-dissect(1) or the RootDirectory=/RootImage= settings of service files (see systemd.exec(5)).

Use the systemd-vpick(1) tool to resolve ".v/" paths from the command line, for example for usage in shell scripts.

## FILTERING AND SORTING
The variable part of the filenames in the ".v/" directories are filtered and compared primarily with a version comparison, implementing Version Format Specification[1]. However, additional rules apply:

•If the variable part is suffixed by one or two integer values ("tries left" and "tries done") in the formats +LEFT or +LEFT-DONE, then these indicate usage attempt counters. The idea is that each time before a file is attempted to be used, its "tries left" counter is decreased, and the "tries done" counter increased (simply by renaming the file). When the file is successfully used (which for example could mean for an OS image: successfully booted) the counters are removed from the file name, indicating that the file has been validated to work correctly. This mechanism mirrors the boot assessment counters defined by Automatic Boot Assessment[2]. Any filenames with no boot counters or with a non-zero "tries left" counter are sorted before filenames with a zero "tries left" counter.

•Preceding the use counters (if they are specified), an optional CPU architecture identifier may be specified in the filename (separated from the version with an underscore), as defined in the architecture vocabulary of the ConditionArchitecture= unit file setting, as documented in systemd.unit(5). Files whose name indicates an architecture not supported locally are filtered and not considered for the version comparison.

•The rest of the variable part is the version string.

Or in other words, the files in the ".v/" directories should follow one of these naming structures:

•NAME_VERSION.SUFFIX

•NAME_VERSION_ARCHITECTURE.SUFFIX

•NAME_VERSION+LEFT.SUFFIX

•NAME_VERSION+LEFT-DONE.SUFFIX

•NAME_VERSION_ARCHITECTURE+LEFT.SUFFIX

•NAME_VERSION_ARCHITECTURE+LEFT-DONE.SUFFIX

## EXAMPLE
Here's a more comprehensive example, further extending the one described above. Consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with the following files:

•mymachine_7.5.13.raw

•mymachine_7.5.14_x86-64.raw

•mymachine_7.6.0_arm64.raw

•mymachine_7.7.0_x86-64+0-5.raw

Now invoke the following command on an x86-64 machine:

```
$ systemd-vpick --suffix=.raw /var/lib/machines/mymachine.raw.v/
```

This would resolve the specified path to /var/lib/machines/mymachine.raw.v/mymachine_7.5.14_x86-64.raw. Explanation: even though mymachine_7.7.0_x86-64+0-5.raw has the newest version, it is not preferred because its tries left counter is zero. And even though mymachine_7.6.0_arm64.raw has the second newest version it is also not considered in this case, because we operate on an x86_64 system and the image is intended for arm64 CPUs. Finally, the mymachine_7.5.13.raw image is not considered because it is older than mymachine_7.5.14_x86-64.raw.

## SEE ALSO
systemd(1), systemd-vpick(1), systemd-nspawn(1), systemd-dissect(1), systemd.exec(5), systemd-sysupdate(8)

## NOTES
1.

Version Format Specification

https://uapi-group.org/specifications/specs/version_format_specification/

2.

Automatic Boot Assessment

https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/

branch: sisyphus


systemd-boot

package: systemd-boot-efi

title: systemd-boot(7)

summary: A simple UEFI boot manager

text:
# systemd-boot(7)

## NAME
systemd-boot, sd-boot - A simple UEFI boot manager

## DESCRIPTION
systemd-boot (short: sd-boot) is a simple UEFI boot manager. It provides a textual menu to select the entry to boot and an editor for the kernel command line. systemd-boot supports systems with UEFI firmware only.

systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at /efi/, /boot/, or /boot/efi/ during OS runtime, as well as from the Extended Boot Loader partition (XBOOTLDR) if it exists (usually mounted to /boot/). Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on the ESP or the Extended Boot Loader partition. Linux kernels must be built with CONFIG_EFI_STUB to be able to be directly executed as an EFI image. During boot systemd-boot automatically assembles a list of boot entries from the following sources:

•Boot entries defined with Boot Loader Specification[1] Type #1 description files located in /loader/entries/ on the ESP and the Extended Boot Loader Partition. These usually describe Linux kernel images with associated initrd images, but alternatively may also describe other arbitrary EFI executables.

•Unified kernel images, Boot Loader Specification[1] Type #2, which are executable EFI binaries in /EFI/Linux/ on the ESP and the Extended Boot Loader Partition.

•The Microsoft Windows EFI boot manager, if installed.

•The Apple macOS boot manager, if installed.

•The EFI Shell binary, if installed.

•A "Reboot Into Firmware Interface" option, if supported by the UEFI firmware.

•Secure Boot variables enrollment if the UEFI firmware is in setup-mode and files are provided on the ESP.

systemd-boot supports the following features:

•Basic boot manager configuration changes (such as timeout configuration, default boot entry selection, ...) may be made directly from the boot loader UI at boot-time, as well as during system runtime with EFI variables.

•The boot manager integrates with the systemctl command to implement features such as systemctl reboot --boot-loader-entry=... (for rebooting into a specific boot menu entry, i.e. "reboot into Windows") and systemctl reboot --boot-loader-menu=... (for rebooting into the boot loader menu), by implementing the Boot Loader Interface[2]. See systemctl(1) for details.

•An EFI variable set by the boot loader informs the OS about the EFI System Partition used during boot. This is then used to automatically mount the correct EFI System Partition to /efi/ or /boot/ during OS runtime. See systemd-gpt-auto-generator(8) for details.

•The boot manager provides information about the boot time spent in UEFI firmware using the Boot Loader Interface[2]. This information can be displayed using systemd-analyze(1).

•The boot manager implements boot counting and automatic fallback to older, working boot entries on failure. See Automatic Boot Assessment[3].

•The boot manager optionally reads a random seed from the ESP partition, combines it with a 'system token' stored in a persistent EFI variable and derives a random seed to use by the OS as entropy pool initialization, providing a full entropy pool during early boot.

•The boot manager allows for Secure Boot variables to be enrolled if the UEFI firmware is in setup-mode. Additionally, variables can be automatically enrolled if configured.

bootctl(1) may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list available entries, and install systemd-boot itself.

kernel-install(8) may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate description files compliant with the Boot Loader Specification.

systemd-stub(7) may be used as UEFI boot stub for executed kernels, which is useful to show graphical boot splashes before transitioning into the Linux world. It is also capable of automatically picking up auxiliary credential files (for boot parameterization) and system extension images, as companion files to the booted kernel images.

## KEY BINDINGS
The following keys may be used in the boot menu:

↑ (Up), ↓ (Down), j, k, PageUp, PageDown, Home, End

Navigate up/down in the entry list Added in version 239.

↵ (Enter), → (Right)

Boot selected entry Added in version 239.

d

Make selected entry the default An EFI variable is set to allow this setting to persist.

Added in version 239.

e

Edit the kernel command line for selected entry Added in version 239.

+, t

Increase the timeout before default entry is booted An EFI variable is set to allow this setting to persist.

Added in version 239.

-, T

Decrease the timeout An EFI variable is set to allow this setting to persist.

Added in version 239.

r

Change screen resolution, skipping any unsupported modes. An EFI variable is set to allow this setting to persist.

Added in version 250.

R

Reset screen resolution to firmware or configuration file default. An EFI variable is set to allow this setting to persist.

Added in version 250.

p

Print status Added in version 250.

h, ?, F1

Show a help screen Added in version 239.

f

Reboot into firmware interface. For compatibility with the keybindings of several firmware implementations this operation may also be reached with F2, F10, Del and Esc.

Added in version 250.

Shift+o

Power off the system. Added in version 255.

Shift+b

Reboot the system. Added in version 255.

The following keys may be pressed during bootup or in the boot menu to directly boot a specific entry:

l

Linux Added in version 239.

w

Windows Added in version 239.

a

macOS Added in version 239.

s

EFI shell Added in version 239.

1, 2, 3, 4, 5, 6, 7, 8, 9

Boot entry number 1 ... 9 Added in version 239.

The boot menu is shown when a non-zero menu timeout has been configured. If the menu timeout has been set to zero, hold down a key (space is recommended) before the boot loader initializes to bring up the boot menu. Note that depending on the firmware implementation the time window where key presses are accepted before the boot loader initializes might be short. If the window is missed, reboot and try again, possibly repeatedly pressing a suitable key; on most systems it should be possible to hit the time window after a few attempts. Keys other than the space bar may be used, except for the keys listed above. If showing the menu on demand doesn't work well, consider setting a non-zero timeout to show the boot menu unconditionally. Some desktop environments might offer an option to boot directly into the boot menu, which also avoids the problem altogether. Alternatively, use the command line systemctl reboot --boot-loader-menu= with a non-zero value from the shell.

In the editor, most keys simply insert themselves, but the following keys may be used to perform additional actions:

← (Left), → (Right), Home, End

Navigate left/right Added in version 239.

Esc, Ctrl+c

Abort the edit and quit the editor Added in version 239.

Ctrl+k

Clear the command line forwards Added in version 239.

Ctrl+w, Alt+Backspace

Delete word backwards Added in version 239.

Ctrl+Del, Alt+d

Delete word forwards Added in version 239.

↵ (Enter)

Boot entry with the edited command line Added in version 239.

Note that unless configured otherwise in the UEFI firmware, systemd-boot will use the US keyboard layout, so key labels might not match for keys like +/-.

## FILES
The files systemd-boot processes generally reside on the UEFI ESP which is usually mounted to /efi/, /boot/ or /boot/efi/ during OS runtime. It also processes files on the Extended Boot Loader partition which is typically mounted to /boot/, if it exists.

systemd-boot reads runtime configuration such as the boot timeout and default entry from /loader/loader.conf on the ESP (in combination with data read from EFI variables). See loader.conf(5).

Boot entry description files following the Boot Loader Specification[1] are read from /loader/entries/ on the ESP and the Extended Boot Loader partition.

Unified kernel boot entries following the Boot Loader Specification[1] are read from /EFI/Linux/ on the ESP and the Extended Boot Loader partition.

Optionally, a random seed for early boot entropy pool provisioning is stored in /loader/random-seed in the ESP.

During initialization, sd-boot automatically loads all driver files placed in the /EFI/systemd/drivers/ directory of the ESP. The files placed there must have an extension of the EFI architecture ID followed by .efi (e.g. for x86-64 this means a suffix of x64.efi). This may be used to automatically load file system drivers and similar, to extend the native firmware support.

Enrollment of Secure Boot variables can be performed manually or automatically if files are available under /loader/keys/NAME/{db,dbx,KEK,PK}.auth, NAME being the display name for the set of variables in the menu. If one of the sets is named auto then it might be enrolled automatically depending on the execution environment and the value of the "secure-boot-enroll" option. See loader.conf(5).

## EFI VARIABLES
The following EFI variables are defined, and may be set or read by systemd-boot for communication between the boot loader and the OS. The vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f" is used in all cases.

LoaderBootCountPath

If boot counting is enabled, contains the path to the file in whose name the boot counters are encoded. Set by the boot loader. systemd-bless-boot.service(8) uses this information to mark a boot as successful as determined by the successful activation of the boot-complete.target target unit. Added in version 240.

LoaderConfigTimeout, LoaderConfigTimeoutOneShot

The menu timeout in seconds. Read by the boot loader. LoaderConfigTimeout is maintained persistently, while LoaderConfigTimeoutOneShot is a one-time override which is read once (in which case it takes precedence over LoaderConfigTimeout) and then removed. LoaderConfigTimeout may be manipulated with the t/T keys, see above. Added in version 240.

LoaderConfigConsoleMode

The numerical menu console mode. Read by the boot loader. LoaderConfigConsoleMode is maintained persistently. LoaderConfigConsoleMode may be manipulated with the r/R keys, see above. Added in version 250.

LoaderDevicePartUUID

Contains the partition UUID of the partition the boot loader has been started from on the current boot (usually an EFI System Partition). Set by the boot loader. (Note that systemd-stub(7) will set this too, if not set yet, to support systems that boot directly into a unified kernel image, bypassing any boot loader.) systemd-gpt-auto-generator(8) uses this information to automatically find the disk booted from, in order to discover various other partitions on the same disk automatically. Added in version 220.

LoaderDeviceURL

If the boot loader has been invoked via network booting this variable contains the originating URL. This may be used to automatically acquire additional resources from the same source. Added in version 258.

LoaderEntries

A list of the identifiers of all discovered boot loader entries. Set by the boot loader. Added in version 240.

LoaderEntryDefault, LoaderEntrySysFail, LoaderEntryOneShot

The identifier of the default boot loader entry. Can be set in the OS and the boot loader. LoaderEntryOneShot sets the default entry for the next boot only, while LoaderEntryDefault sets it persistently for all future boots. bootctl(1)'s set-default and set-oneshot commands make use of these variables. The boot loader modifies LoaderEntryDefault on request, when the d key is used, see above. Added in version 240.

LoaderEntryLastBooted

The identifier of the boot loader entry last attempted. Set and read by the boot loader, only when /loader/loader.conf has default set to "@saved". See loader.conf(5). The boot loader will ensure LoaderEntryLastBooted is up-to date for every boot, updating it as needed and will omit changing it all together when LoaderEntryOneShot is set.

The boot loader reads the variable, which takes higher priority than LoaderEntryDefault. The variable is ignored when LoaderEntryOneShot is set.

LoaderEntryLastBooted cannot be used as indication that the last boot was successful or not.

Added in version 250.

LoaderEntrySelected

The identifier of the boot loader entry currently being booted. Set by the boot loader. Added in version 240.

LoaderFeatures

A set of flags indicating the features the boot loader supports. Set by the boot loader. Use bootctl(1) to view this data. Added in version 240.

LoaderFirmwareInfo, LoaderFirmwareType

Brief firmware information. Set by the boot loader. Use bootctl(1) to view this data. Added in version 240.

LoaderTpm2ActivePcrBanks

Hexadecimal string representation of a bitmask with values defined by the TCG EFI Protocol Specification for TPM 2.0 as EFI_TCG2_BOOT_HASH_ALG_*. If no TPM2 support or no active banks were detected, will be set to 0. Set by the boot loader. Use systemd-analyze(1) to view this data. Added in version 258.

LoaderImageIdentifier

The file system path to the EFI executable of the boot loader for the current boot, relative to the partition's root directory (i.e. relative to the partition indicated by LoaderDevicePartUUID, see above). Set by the boot loader. (Note that systemd-stub will set this too, if not set yet, to support systems that directly boot into a unified kernel image, bypassing any boot loader.) Use bootctl(1) to view this data. Added in version 220.

LoaderInfo

Brief information about the boot loader. Set by the boot loader. Use bootctl(1) to view this data. Added in version 240.

LoaderTimeExecUSec, LoaderTimeInitUSec, LoaderTimeMenuUsec

Information about the time spent in various parts of the boot loader. Set by the boot loader. Use systemd-analyze(1) to view this data. Added in version 240.

LoaderSystemToken

A binary random data field, that is used for generating the random seed to pass to the OS (see above). Note that this random data is generally only generated once, during OS installation, and is then never updated again. Added in version 243.

Many of these variables are defined by the Boot Loader Interface[2].

## SMBIOS TYPE 11 STRINGS
systemd-boot can be configured using SMBIOS Type 11 strings. Applicable strings consist of a name, followed by "=", followed by the value. Unless systemd-boot detects it is running inside a confidential computing environment, systemd-boot will search the table for a string with a specific name, and if found, use its value. The following strings are read:

io.systemd.boot.kernel-cmdline-extra

If set, the value of this string is added to the list of kernel command line arguments for Boot Loader Specification Type 1 entries that are measured in PCR12 and passed to the kernel. Added in version 256.

io.systemd.boot-entries.extra:ID=DEFINITION

This allows inserting additional entries into the systemd-boot menu. Take a pair of menu entry identifier and menu entry definition string. The former should be suitable for use as a filename of a Boot Loader Specification Type #1 entry filename (note that it is used for identification purposes only, no file of this name is actually accessed), the latter shall follow the syntax of the contents of a Type #1 entry. Any menu entry defined this way is processed and shown in pretty much the same way as a Type #1 entry read from the ESP or XBOOTLDR partition. Example:

```
io.systemd.boot-entries.extra:fooos-current.conf=title FooOS (Current)
uki-url http://example.com/somedir/fooos.efi
```

Note that this example contains a newline character. When generating this string from a shell care must be taken to encode it correctly.

Pass multiple strings formatted this way to generate multiple menu entries.

Added in version 258.

## BOOT COUNTING
systemd-boot implements a simple boot counting mechanism on top of the Boot Loader Specification[1], for automatic and unattended fallback to older kernel versions/boot loader entries when a specific entry continuously fails. Any boot loader entry file and unified kernel image file that contains a "+" followed by one or two numbers (if two they need to be separated by a "-"), before the .conf or .efi suffix is subject to boot counting: the first of the two numbers ('tries left') is decreased by one on every boot attempt, the second of the two numbers ('tries done') is increased by one (if 'tries done' is absent it is considered equivalent to 0). Depending on the current value of these two counters the boot entry is considered to be in one of three states:

1.If the 'tries left' counter of an entry is greater than zero the entry is considered to be in 'indeterminate' state. This means the entry has not completed booting successfully yet, but also has not been determined not to work.

2.If the 'tries left' counter of an entry is zero it is considered to be in 'bad' state. This means no further attempts to boot this item will be made (that is, unless all other boot entries are also in 'bad' state), as all attempts to boot this entry have not completed successfully.

3.If the 'tries left' and 'tries done' counters of an entry are absent it is considered to be in 'good' state. This means further boot counting for the entry is turned off, as it successfully booted at least once. The systemd-bless-boot.service(8) service moves the currently booted entry from 'indeterminate' into 'good' state when a boot attempt completed successfully.

Generally, when new entries are added to the boot loader, they first start out in 'indeterminate' state, i.e. with a 'tries left' counter greater than zero. The boot entry remains in this state until either it managed to complete a full boot successfully at least once (in which case it will be in 'good' state) — or the 'tries left' counter reaches zero (in which case it will be in 'bad' state).

Example: let's say a boot loader entry file foo.conf is set up for 3 boot tries. The installer will hence create it under the name foo+3.conf. On first boot, the boot loader will rename it to foo+2-1.conf. If that boot does not complete successfully, the boot loader will rename it to foo+1-2.conf on the following boot. If that fails too, it will finally be renamed foo+0-3.conf by the boot loader on next boot, after which it will be considered 'bad'. If the boot succeeds however the entry file will be renamed to foo.conf by the OS, so that it is considered 'good' from then on.

The boot menu takes the 'tries left' counter into account when sorting the menu entries: entries in 'bad' state are ordered at the beginning of the list, and entries in 'good' or 'indeterminate' at the end. The user can freely choose to boot any entry of the menu, including those already marked 'bad'. If the menu entry to boot is automatically determined, this means that 'good' or 'indeterminate' entries are generally preferred (as the bottom item of the menu is the one booted by default), and 'bad' entries will only be considered if there are no 'good' or 'indeterminate' entries left.

The kernel-install(8) kernel install framework optionally sets the initial 'tries left' counter to the value specified in /etc/kernel/tries when a boot loader entry is first created.

## USING SYSTEMD-BOOT IN VIRTUAL MACHINES
When using qemu with OVMF (UEFI Firmware for virtual machines) the -kernel switch works not only for linux kernels, but for any EFI binary, including sd-boot and unified linux kernels. Example command line for loading systemd-boot on x64:

qemu-system-x86_64 [ ... ] -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi

systemd-boot will detect that it was started directly instead of being loaded from ESP and will search for the ESP in that case, taking into account boot order information from the hypervisor (if available).

## SEE ALSO
bootctl(1), loader.conf(5), systemd-bless-boot.service(8), systemd-boot-random-seed.service(8), kernel-install(8), systemd-stub(7), Boot Loader Specification[1], Boot Loader Interface[2], TPM2 PCR Measurements Made by systemd[4]

## NOTES
1.

Boot Loader Specification

https://uapi-group.org/specifications/specs/boot_loader_specification

2.

Boot Loader Interface

https://systemd.io/BOOT_LOADER_INTERFACE

3.

Automatic Boot Assessment

https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT

4.

TPM2 PCR Measurements Made by systemd

https://systemd.io/TPM2_PCR_MEASUREMENTS


term

package: termutils

title: term(7)

text:
# term(7)

## NAME
term - conventions for naming terminal types

## DESCRIPTION
The environment variable TERM should normally contain the type name of the terminal, console or display-device type you are using. This information is critical for all screen-oriented programs, including your editor and mailer.

A default TERM value will be set on a per-line basis by either /etc/inittab (e.g., System-V-like Unices) or /etc/ttys (BSD Unices). This will nearly always suffice for workstation and microcomputer consoles.

If you use a dialup line, the type of device attached to it may vary. Older Unix systems pre-set a very dumb terminal type like “dumb” or “dialup” on dialup lines. Newer ones may pre-set “vt100”, reflecting the prevalence of DEC VT100-compatible terminals and personal-computer emulators.

Modern telnets pass your TERM environment variable from the local side to the remote one. There can be problems if the remote terminfo or termcap entry for your type is not compatible with yours, but this situation is rare and can almost always be avoided by explicitly exporting “vt100” (assuming you are in fact using a VT100-superset console, terminal, or terminal emulator).

In any case, you are free to override the system TERM setting to your taste in your shell profile. The tset(1) utility may be of assistance; you can give it a set of rules for deducing or requesting a terminal type based on the tty device and baud rate.

Setting your own TERM value may also be useful if you have created a custom entry incorporating options (such as visual bell or reverse-video) which you wish to override the system default type for your line.

Terminal type descriptions are stored as files of capability data underneath /usr/share/terminfo. To browse a list of all terminal names recognized by the system, do

toe | more

from your shell. These capability files are in a binary format optimized for retrieval speed (unlike the old text-based termcap format they replace); to examine an entry, you must use the infocmp(1M) command. Invoke it as follows:

infocmp entry_name

where entry_name is the name of the type you wish to examine (and the name of its capability file the subdirectory of /usr/share/terminfo named for its first letter). This command dumps a capability file in the text format described by terminfo(5).

The first line of a terminfo(5) description gives the names by which terminfo knows a terminal, separated by “|” (pipe-bar) characters with the last name field terminated by a comma. The first name field is the type's primary name, and is the one to use when setting TERM. The last name field (if distinct from the first) is actually a description of the terminal type (it may contain blanks; the others must be single words). Name fields between the first and last (if present) are aliases for the terminal, usually historical names retained for compatibility.

There are some conventions for how to choose terminal primary names that help keep them informative and unique. Here is a step-by-step guide to naming terminals that also explains how to parse them:

First, choose a root name. The root will consist of a lower-case letter followed by up to seven lower-case letters or digits. You need to avoid using punctuation characters in root names, because they are used and interpreted as filenames and shell meta-characters (such as !, $, *, ?, etc.) embedded in them may cause odd and unhelpful behavior. The slash (/), or any other character that may be interpreted by anyone's file system (\, $, [, ]), is especially dangerous (terminfo is platform-independent, and choosing names with special characters could someday make life difficult for users of a future port). The dot (.) character is relatively safe as long as there is at most one per root name; some historical terminfo names use it.

The root name for a terminal or workstation console type should almost always begin with a vendor prefix (such as hp for Hewlett-Packard, wy for Wyse, or att for AT&T terminals), or a common name of the terminal line (vt for the VT series of terminals from DEC, or sun for Sun Microsystems workstation consoles, or regent for the ADDS Regent series. You can list the terminfo tree to see what prefixes are already in common use. The root name prefix should be followed when appropriate by a model number; thus vt100, hp2621, wy50.

The root name for a PC-Unix console type should be the OS name, i.e., linux, bsdos, freebsd, netbsd. It should not be console or any other generic that might cause confusion in a multi-platform environment! If a model number follows, it should indicate either the OS release level or the console driver release level.

The root name for a terminal emulator (assuming it does not fit one of the standard ANSI or vt100 types) should be the program name or a readily recognizable abbreviation of it (i.e., versaterm, ctrm).

Following the root name, you may add any reasonable number of hyphen-separated feature suffixes.

2p

Has two pages of memory. Likewise 4p, 8p, etc.

mc

Magic-cookie. Some terminals (notably older Wyses) can only support one attribute without magic-cookie lossage. Their base entry is usually paired with another that has this suffix and uses magic cookies to support multiple attributes.

-am

Enable auto-margin (right-margin wraparound).

-m

Mono mode - suppress color support.

-na

No arrow keys - termcap ignores arrow keys which are actually there on the terminal, so the user can use the arrow keys locally.

-nam

No auto-margin - suppress am capability.

-nl

No labels - suppress soft labels.

-nsl

No status line - suppress status line.

-pp

Has a printer port which is used.

-rv

Terminal in reverse video mode (black on white).

-s

Enable status line.

-vb

Use visible bell (flash) rather than beep.

-w

Wide; terminal is in 132-column mode.

Conventionally, if your terminal type is a variant intended to specify a line height, that suffix should go first. So, for a hypothetical FuBarCo model 2317 terminal in 30-line mode with reverse video, best form would be fubar-30-rv (rather than, say, “fubar-rv-30”).

Terminal types that are written not as standalone entries, but rather as components to be plugged into other entries via use capabilities, are distinguished by using embedded plus signs rather than dashes.

Commands which use a terminal type to control display often accept a -T option that accepts a terminal name argument. Such programs should fall back on the TERM environment variable when no -T option is specified.

## FILES
/usr/share/terminfo

compiled terminal description database

/etc/inittab

tty line initialization (AT&T-like Unices)

/etc/ttys

tty line initialization (BSD-like Unices)

## PORTABILITY
For maximum compatibility with older System V Unices, names and aliases should be unique within the first 14 characters.

## SEE ALSO
curses(3X), term(5), terminfo(5)


tigmanual

package: tig

title: tigmanual(7)

summary: text\-mode interface for Git

text:
# tigmanual(7)

## NAME
tigmanual - text-mode interface for Git

## SYNOPSIS

```
tig        [options] [revisions] [--] [paths]
tig show   [options] [revisions] [--] [paths]
tig blame  [options] [rev] [--] path
tig status
tig <      [Git command output]
```

## DESCRIPTION
This is the manual for Tig, the ncurses-based text-mode interface for git. Tig allows you to browse changes in a Git repository and can additionally act as a pager for output of various Git commands. When used as a pager, it will display input from stdin and colorize it.

When browsing repositories, Tig uses the underlying Git commands to present the user with various views, such as summarized commit log and showing the commit with the log message, diffstat, and the diff.

## CALLING CONVENTIONS

### Pager Mode
If stdin is a pipe, any log or diff options will be ignored and the pager view will be opened loading data from stdin. The pager mode can be used for colorizing output from various Git commands.

Example on how to colorize the output of git-show(1):

```
$ git show | tig
```

### Git Command Options
All Git command options specified on the command line will be passed to the given command and all will be shell quoted before they are passed to the shell.

Note If you specify options for the main view, you should not use the --pretty option as this option will be set automatically to the format expected by the main view.

Example on how to view a commit and show both author and committer information:

```
$ tig show --pretty=fuller
```

See the section on specifying revisions for an introduction to revision options supported by the Git commands. For details on specific Git command options, refer to the man page of the command in question.

## THE VIEWER
The display consists of a status window on the last line of the screen and one or more views. The default is to only show one view at a time but it is possible to split both the main and log view to also show the commit diff.

If you are in the log view and press Enter when the current line is a commit line, such as:

```
commit 4d55caff4cc89335192f3e566004b4ceef572521
```

You will split the view so that the log view is displayed in the top window and the diff view in the bottom window. You can switch between the two views by pressing Tab. To maximize the log view again, simply press l.

### Views
Various views of a repository are presented. Each view is based on output from an external command, most often git log, git diff, or git show.

The main view

Is the default view, and it shows a one line summary of each commit in the chosen list of revisions. The summary includes committer or author date, author, committer, and the first line of the log message. Additionally, any repository references, such as tags, will be shown.

The log view

Presents a more rich view of the revision log showing the whole log message and the diffstat.

The reflog view

Presents a view of the reflog allowing to navigate the repo history.

The diff view

Shows either the diff of the current working tree, that is, what has changed since the last commit, or the commit diff complete with log message, diffstat and diff.

The tree view

Lists directory trees associated with the current revision allowing subdirectories to be descended or ascended and file blobs to be viewed.

The blob view

Displays the file content or "blob" of data associated with a file name.

The blame view

Displays the file content annotated or blamed by commits.

The refs view

Displays the branches, remotes and tags in the repository.

The status view

Displays status of files in the working tree and allows changes to be staged/unstaged as well as adding of untracked files.

The stage view

Displays diff changes for staged or unstaged files being tracked or file content of untracked files.

The stash view

Displays the list of stashes in the repository.

The grep view

Displays a list of files and all the lines that matches a search pattern.

The pager view

Is used for displaying both input from stdin and output from Git commands entered in the internal prompt.

The help view

Displays a quick reference of key bindings.

### Browsing State and User-defined Commands
The viewer keeps track of both what head and commit ID you are currently viewing. The commit ID will follow the cursor line and change every time you highlight a different commit. Whenever you reopen the diff view it will be reloaded, if the commit ID changed. The head ID is used when opening the main and log view to indicate from what revision to show history.

Some of the commands used or provided by Tig can be configured. This goes for some of the environment variables as well as the external commands. These user-defined commands can use arguments that refer to the current browsing state by using one of the following variables.

Table 1. Browsing state variables

%(head)

The currently viewed head ID. Defaults to HEAD

%(commit)

The currently selected commit ID.

%(blob)

The currently selected blob ID.

%(branch)

The currently selected branch name.

%(remote)

The currently selected remote name. For remote branches %(branch) will contain the branch name.

%(tag)

The currently selected tag name.

%(refname)

The currently selected reference name including the remote name for remote branches.

%(stash)

The currently selected stash name.

%(directory)

The current directory path in the tree view or "." if undefined.

%(file)

The currently selected file.

%(file_old)

The old filename of the currently selected file.

%(lineno)

The currently selected line number. Defaults to 0.

%(lineno_old)

The currently selected line number, before the diff was applied. Defaults to 0.

%(ref)

The reference given to blame or HEAD if undefined.

%(revargs)

The revision arguments passed on the command line.

%(fileargs)

The file arguments passed on the command line.

%(cmdlineargs)

All other options passed on the command line.

%(diffargs)

Options from diff-options or TIG_DIFF_OPTS used by the diff and stage view.

%(blameargs)

Options from blame-options used by the blame view.

%(logargs)

Options from log-options used by the log view.

%(mainargs)

Options from main-options used by the main view.

%(prompt)

Prompt for the argument value. Optionally specify a custom prompt using "%(prompt Enter branch name: )"

%(text)

The text column of the currently selected line.

%(repo:head)

The name of the checked out branch, e.g. master

%(repo:head-id)

The commit ID of the checked out branch.

%(repo:remote)

The remote name associated with the checked out branch, e.g. origin.

%(repo:upstream)

The upstream branch associated with the checked out branch, e.g. origin/master.

%(repo:cdup)

The path to change directory to the repository root, e.g. ../

%(repo:prefix)

The path prefix of the current work directory, e.g subdir/.

%(repo:git-dir)

The path to the Git directory, e.g. /src/repo/.git.

%(repo:worktree)

The worktree path, if defined.

%(repo:is-inside-work-tree)

Whether Tig is running inside a work tree, either true or false.

Example user-defined commands:

•Allow to amend the last commit:

```
bind generic + !git commit --amend
```

•Copy commit ID to clipboard:

```
bind generic 9 @sh -c "echo -n %(commit) | xclip -selection c"
```

•Add/edit notes for the current commit used during a review:

```
bind generic T !git notes edit %(commit)
```

•Enter Git’s interactive add for fine-grained staging of file content:

```
bind generic I !git add -i %(file)
```

•Rebase current branch on top of the selected branch:

```
bind refs 3 !git rebase -i %(branch)
```

### Title Windows
Each view has a title window which shows the name of the view, current commit ID if available, and where the view is positioned:

```
[main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61             1%
```

By default, the title of the current view is highlighted using bold font. For long loading views (taking over 3 seconds) the time since loading started will be appended:

```
[main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 loading 5s 0%
```

## ENVIRONMENT VARIABLES
Several options related to the interface with Git can be configured via environment options.

### Configuration Files
Upon startup, Tig first reads the system wide configuration file ({sysconfdir}/tigrc by default) and then proceeds to read the user’s configuration file (~/.tigrc or $XDG_CONFIG_HOME/tig/config by default). The paths to either of these files can be overridden through the following environment variables:

TIGRC_USER

Path of the user configuration file.

TIGRC_SYSTEM

Path of the system wide configuration file.

### History Files
If compiled with readline support, Tig writes a persistent command and search history to ~/.tig_history or $XDG_DATA_HOME/tig/history.

### Repository References
Commits that are referenced by tags and branch heads will be marked by the reference name surrounded by [ and ]:

```
2006-03-26 19:42 Petr Baudis         | [cogito-0.17.1] Cogito 0.17.1
```

If you want to limit what branches are shown, say only show branches named master or those which start with the feature/ prefix, you can do it by setting the following variable:

```
$ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
```

Or set the variable permanently in your environment.

TIG_LS_REMOTE

Command for retrieving all repository references. The command should output data in the same format as git-ls-remote(1). Defaults to:

```
git ls-remote .
```

### Diff options
It is possible to alter how diffs are shown by the diff view. If for example you prefer to have commit and author dates shown as relative dates, use:

```
$ TIG_DIFF_OPTS="--relative-date" tig
```

Or set the variable permanently in your environment.

## DEFAULT KEYBINDINGS
Below the default key bindings are shown.

### View Switching
Key

Action

m

Switch to main view.

d

Switch to diff view.

l

Switch to log view.

p

Switch to pager view.

t

Switch to (directory) tree view.

f

Switch to (file) blob view.

g

Switch to grep view.

b

Switch to blame view.

r

Switch to refs view.

y

Switch to stash view.

h

Switch to help view

s

Switch to status view

c

Switch to stage view

### View Manipulation
Key

Action

q

Close view, if multiple views are open it will jump back to the previous view in the view stack. If it is the last open view it will quit. Use Q to quit all views at once.

Enter

This key is "context sensitive" depending on what view you are currently in. When in log view on a commit line or in the main view, split the view and show the commit diff. In the diff view pressing Enter will simply scroll the view one line down.

Tab

Switch to next view.

R

Reload and refresh the current view.

O

Maximize the current view to fill the whole display.

Up

This key is "context sensitive" and will move the cursor one line up. However, if you opened a split view it will change the cursor to point to the previous commit in the parent view and update the child view to display it. If you prefer this key to move the cursor or scroll within the diff view instead, use bind diff <Up> move-up or bind diff <Up> scroll-line-up, respectively.

Down

Similar to Up but will move down.

,

Move to parent. In the tree view, this means switch to the parent directory. In the blame view it will load blame for the parent commit. For merges the parent is queried.

### View Specific Actions
Key

Action

u

Update status of file. In the status view, this allows you to add an untracked file or stage changes to a file for next commit (similar to running git-add <filename>). In the stage view, when pressing this on a diff chunk line stages only that chunk for next commit, when not on a diff chunk line all changes in the displayed diff are staged.

M

Resolve unmerged file by launching git-mergetool(1). Note, to work correctly this might require some initial configuration of your preferred merge tool. See the manpage of git-mergetool(1).

!

Checkout file with unstaged changes. This will reset the file to contain the content it had at last commit.

1

Stage single diff line.

@

Move to next chunk in the stage view.

]

Increase the diff context.

[

Decrease the diff context.

### Cursor Navigation
Key

Action

k

Move cursor one line up.

j

Move cursor one line down.

PgUp, -

Move cursor one page up.

PgDown, Space

Move cursor one page down.

Home

Jump to first line.

End

Jump to last line.

### Scrolling
Key

Action

Insert

Scroll view one line up.

Delete

Scroll view one line down.

ScrollBack

Scroll view one page up.

ScrollFwd

Scroll view one page down.

Left

Scroll view one column left.

Right

Scroll view one column right.

|

Scroll view to the first column.

### Searching
Key

Action

/

Search the view. Opens a prompt for entering search regexp to use.

?

Search backwards in the view. Also prompts for regexp.

n

Find next match for the current search regexp.

N

Find previous match for the current search regexp.

The format for patterns is either POSIX.2 “extended” REs or PCRE / PCRE2 if Tig was compiled with PCRE / PCRE2 support (check with tig -v). See the manpage of re_format(7) or pcrepattern(3) / pcre2pattern(3).

Case sensitivity can be controlled with variable ignore-case.

### Misc
Key

Action

Q

Quit.

<C-L>

Redraw screen.

z

Stop all background loading. This can be useful if you use Tig in a repository with a long history without limiting the revision log.

v

Show version.

o

Open option menu

\#

Toggle line numbers on/off.

D

Toggle date display on/off/relative/relative-compact/custom

A

Toggle author display on/off/abbreviated/email/email user name.

T

Toggle committer display on/off/abbreviated/email/email user name.

G

Toggle revision graph visualization on/off.

~

Toggle (line) graphics mode

F

Toggle reference display on/off (tag and branch names).

W

Toggle ignoring whitespace on/off for diffs

X

Toggle commit ID display on/off

%

Toggle file filtering in order to see the full diff instead of only the diff concerning the currently selected file.

^

Toggle revision filtering in the main view.

$

Toggle highlighting of commit title overflow.

H

Go to the HEAD commit.

:

Open prompt. This allows you to specify what command to run and also to jump to a specific line, e.g. :23

e

Open file in editor.

### Prompt
Key

Action

:<number>

Jump to the specific line number, e.g. :80.

:<sha>

Jump to a specific commit, e.g. :2f12bcc.

:<x>

Execute the corresponding key binding, e.g. :q.

:!<command>

Execute a system command in a pager, e.g. :!git log -p.

:<action>

Execute a Tig command, e.g. :edit.

:goto <rev>

Jump to a specific revision, e.g. :goto %(commit)^2 to goto the current commit’s 2nd parent or :goto some/branch to goto the commit denoting the branch some/branch.

:save-display <file>

Save current display to <file>.

:save-options <file>

Save current options to <file>.

:save-view <file>

Save view info to <file> (for testing purposes).

:script <file>

Execute commands from <file>.

:exec <flags><args...>

Execute command using <args> with external user-defined command option flags defined in <flags>.

:echo <args...>

Display text in the status bar.

### External Commands
For more custom needs, external commands provide a way to easily execute a script or program. They are bound to keys and use information from the current browsing state, such as the current commit ID. Tig comes with the following built-in external commands:

Keymap

Key

Action

main

C

git cherry-pick %(commit)

status

C

git commit

generic

G

git gc

## REVISION SPECIFICATION
This section describes various ways to specify what revisions to display or otherwise limit the view to. Tig does not itself parse the described revision options so refer to the relevant Git man pages for further information. Relevant man pages besides git-log(1) are git-diff(1) and git-rev-list(1).

You can tune the interaction with Git by making use of the options explained in this section. For example, by configuring the environment variable described in the section on diff options.

### Limit by Path Name
If you are interested only in those revisions that made changes to a specific file (or even several files) list the files like this:

```
$ tig Makefile README
```

To avoid ambiguity with Tig’s subcommands or repository references such as tag names, be sure to separate file names from other Git options using "--". So if you have a file named status it will clash with the status subcommand, and thus you will have to use:

```
$ tig -- status
```

### Limit by Date or Number
To speed up interaction with Git, you can limit the amount of commits to show both for the log and main view. Either limit by date using e.g. --since=1.month or limit by the number of commits using -n400.

If you are only interested in changes that happened between two dates you can use:

```
$ tig --after="May 5th" --before="2006-05-16 15:44"
```

Note If you want to avoid having to quote dates containing spaces you can use "." instead, e.g. --after=May.5th.

### Limiting by Commit Ranges
Alternatively, commits can be limited to a specific range, such as "all commits between tag-1.0 and tag-2.0". For example:

```
$ tig tag-1.0..tag-2.0
```

This way of commit limiting makes it trivial to only browse the commits which haven’t been pushed to a remote branch. Assuming origin is your upstream remote branch, using:

```
$ tig origin..HEAD
```

will list what will be pushed to the remote branch. Optionally, the ending HEAD can be left out since it is implied.

### Limiting by Reachability
Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits reachable from tag-2.0 but not from tag-1.0". Where reachability refers to what commits are ancestors (or part of the history) of the branch or tagged revision in question.

If you prefer to specify which commit to preview in this way use the following:

```
$ tig tag-2.0 ^tag-1.0
```

You can think of ^ as a negation operator. Using this alternate syntax, it is possible to further prune commits by specifying multiple branch cut offs.

### Combining Revisions Specification
Revision options can to some degree be combined, which makes it possible to say "show at most 20 commits from within the last month that changed files under the Documentation/ directory."

```
$ tig --since=1.month -n20 -- Documentation/
```

### Examining All Repository References
In some cases, it can be useful to query changes across all references in a repository. An example is to ask "did any line of development in this repository change a particular file within the last week". This can be accomplished using:

```
$ tig --all --since=1.week -- Makefile
```

## MORE INFORMATION
Please visit Tig’s home page[1] for information about new releases and how to report bugs and feature requests.

## COPYRIGHT
Copyright (c) 2006-2026 Jonas Fonseca <jonas.fonseca@gmail.com[2]>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

## SEE ALSO
Manpages:

•tig(1)

•tigrc(5)

## NOTES
1.

home page

https://github.com/jonas/tig

2.

jonas.fonseca@gmail.com

mailto:jonas.fonseca@gmail.com


timew-config

package: timewarrior

title: timew-config(7)

text:
# timew-config(7)

## NAME
timew-config - Timewarrior configuration file and override options

## SYNOPSIS
timew rc.<name>=<value> <command>

## DESCRIPTION
Timewarrior stores its configuration in the user's home directory in ~/.timewarrior/timewarrior.cfg. This file contains a mix of rules and configuration settings. Note that the TIMEWARRIORDB environment variable can be set to override this location. The values 'true', '1', 'y', 'yes' and 'on' are all equivalent and enable a setting. Any other value means disable the setting. Default values may be overridden by timewarrior.cfg values, which may in turn be overridden on the command line using: rc.<name>=<value>

For example, to turn off verbose mode:

rc.verbose=0

Note that hints can also do this (:quiet).

## CONFIGURATION
confirmation

Determines whether harmful operations require interactive confirmation.

May be overridden by the ':yes' hint.

Default value is 'yes'.

verbose

Determines whether Timewarrior generates feedback.

May be overridden by the ':quiet' hint.

Default value is 'yes'.

debug

Determines whether diagnostic debugging information is shown.

Useful for troubleshooting, but not for general use.

Default value is 'off'.

debug.indicator

The debug output prefix string.

Default value is '>>'.


timew-dates

title: timew-dates(7)

summary: date formats supported by Timewarrior

text:
# timew-dates(7)

## NAME
timew-dates - date formats supported by Timewarrior

## DESCRIPTION
Timewarrior supports the following date formats based on ISO-8601:

<extended-date> [T <extended-time>] Extended date, optional extended time

<date> [T <time>] Date, optional time

<extended-time> Extended time

<time> Time

extended-date:

YYYY-MM-DD Year, month, day

YYYY-MM Year, month, 1st

YYYY-DDD Year, Julian day 001-366

YYYY-WwwD Year, week number, day number

YYYY-Www Year, week number, day 1

extended-time:

hh:mm[:ss]Z Hours, minutes, optional seconds, UTC

hh:mm[:ss][+/-hh:mm] Hours, minutes, optional seconds, TZ

date:

YYYYMMDD Year, month, day

YYYYWww Year, week number, day number

YYYYDDD Year, Julian day 001-366

time:

hhmm[ss]Z Hour, minutes, optional seconds, UTC

hhmm[ss][+/-hh[mm]] Hour, minutes, optional seconds, TZ

Examples:

2016-06-09T08:12:00Z

2016-06T08:12:00+01:00

2016-06T08:12Z

2016-161

2016-W244

2016-W24

20160609T081200Z

2016W24

8:12:00Z

0812-0500

In addition to the standard date formats, the following are supported:

now Current date and time

today Current date at 0:00:00

yesterday Yesterday at 0:00:00

tomorrow Tomorrow at 0:00:00 (midnight tonight)

<day-of-week> Previous named day at 0:00:00

<month-of-year> Previous 1st of the month at 0:00:00

hh:mm[:ss][am|a|pm|p] Short time format

Nst, Nnd, Nrd, Nth Previous 1st, 2nd, 3rd ...

<epoch> POSIX time

later 2038-01-18T0:00:00 (Y2K38)

someday 2038-01-18T0:00:00 (Y2K38)

sopd, eopd Start/end of previous day

sod, eod Start/end of current day

sond, eond Start/end of next day

sopw, eopw Start/end of previous week

sow, eow Start/end of current week

sonw, eonw Start/end of next week

sopww, eopww Start/end of previous work week (mon - fri)

soww, eoww Start/end of current work week (mon - fri)

sonww, eonww Start/end of next work week (mon - fri)

sopm, eopm Start/end of previous month

som, eom Start/end of current month

sonm, eonm Start/end of next month

sopq, eopq Start/end of previous quarter

soq, eoq Start/end of current quarter

sonq, eonq Start/end of next quarter

sopy, eopy Start/end of previous year

soy, eoy Start/end of current year

sony, eony Start/end of next year

easter Easter Sunday

eastermonday Easter Monday

ascension Ascension

pentecost Pentecost

goodfriday Good Friday

midsommar midnight, 1st Saturday after 20th June

midsommarafton midnight, 1st Friday after 19th June

juhannus midnight, 1st Friday after 19th June

Examples:

8am

24th

monday

august

## SEE ALSO
timew-durations(7), timew-hints(7)


timew-dom

title: timew-dom(7)

summary: Timewarrior DOM

text:
# timew-dom(7)

## NAME
timew-dom - Timewarrior DOM

## DESCRIPTION
Supported DOM references are:

dom.tag.count Count of all tags

dom.tag.1 Nth tag used

dom.active '1' if there is active tracking, otherwise '0'

dom.active.tag.count Count of active tags

dom.active.tag.1 Active Nth tag

dom.active.start Active start timestamp (ISO Extended local date)

dom.active.duration Active elapsed (ISO Period)

dom.active.json Active interval as JSON

dom.tracked.count Count of tracked intervals

dom.tracked.1.tag.count Count of active tags

dom.tracked.1.tag.1 Tracked Nth, Nth tag

dom.tracked.1.start Tracked Nth, start time

dom.tracked.1.end Tracked Nth, end time, blank if closed

dom.tracked.1.duration Tracked Nth, elapsed

dom.tracked.1.json Tracked Nth, interval as JSON

dom.rc.<name> Configuration setting


timew-durations

title: timew-durations(7)

text:
# timew-durations(7)

## NAME
timew-durations - duration formats supported by Timewarrior

## DESCRIPTION
Timewarrior supports the following duration formats based on ISO-8601:

'P' [nn 'Y'] [nn 'M'] [nn 'D'] ['T' [nn 'H'] [nn 'M'] [nn 'S']]

PnnW

Examples:

P1Y 1 year

P1.5M 1.5 months

PT1S 1 second

PT4.5H 4.5 hours

PT4H30M 4.5 hours

P600D 600 days

P3W 3 weeks

P1Y1DT1H1M1S 1 year and 25 hours, 61 seconds (imprecise term)

Note that the year and month terms are imprecise, being defined as 365d and 30d respectively. For precision use the other terms.

In addition to the standard duration formats, the following are supported:

n[.n]<unit>

Where the <unit> is one of:

annual

biannual

bimonthly

biweekly

biyearly

daily

days, day, d

fortnight

hours, hour, hrs, hr, h

minutes, minute, mins, min

monthly, months, month, mnths, mths, mth, mos, mo, m

quarterly, quarters, quarter, qrtrs, qtr, q

semiannual

sennight

seconds, second, secs, sec, s

weekdays

weekly, weeks, week, wks, wk, w

yearly, years, year, yrs, yr, y

Examples:

1hour 60 minutes

1.5h 90 minutes

3mo 3 months

10d 10 days

Note that the year, quarter and month terms are imprecise, being defined as 365d, 91d and 30d respectively. For precision use the other terms.


timew-hints

title: timew-hints(7)

summary: Timewarrior hints

text:
# timew-hints(7)

## NAME
timew-hints - Timewarrior hints

## DESCRIPTION
Timewarrior supports hints, which are single-word command line features that start with a colon like this:

:week

Hints serve several purposes. This example is a shortcut for the date range that defines the current week.

Other hints, such as:

:quiet

Are ways to control the behavior of Timewarrior, in this case eliminating all forms of feedback, for purposes of automation.

The supported hints are:

:quiet Turns off all feedback. For automation

:debug Runs in debug mode, shows many runtime details

:yes Overrides confirmation by answering 'yes' to the questions

:color Force color on, even if not connected to a TTY

:nocolor Force color off, even if connected to a TTY

:blank Leaves tracked time out of a report

:fill Expand time to fill surrounding available gap

:adjust Automatically correct overlaps

:ids Displays interval ID numbers in the summary report

Range hints provide convenient shortcuts to date ranges:

:yesterday The 24 hours of the previous day

:day The 24 hours of the current day

:week This week

:month This month

:quarter This quarter

:year This year

:lastweek Last week

:lastmonth Last month

:lastquarter Last quarter

:lastyear Last year

:monday Previous monday

:tuesday Previous tuesday

:wednesday Previous wednesday

:thursday Previous thursday

:friday Previous friday

:saturday Previous saturday

:sunday Previous sunday


timew-ranges

title: timew-ranges(7)

text:
# timew-ranges(7)

## NAME
timew-ranges - date and time ranges supported by Timewarrior

## DESCRIPTION
An interval defines a block of time that is tracked. The syntax for specifying an interval is flexible, and may be one of:

[from] <date>

[from] <date> to/- <date>

[from] <date> for <duration>

<duration> before/after <date>

<duration> ago

[for] <duration>

Examples are:

from 9:00

from 9am - 11am

from 9:00:00 to 11:00

from 9:00 for 2h

2h after 9am

2h before 11:00

2h ago

for 2h

An interval is said to be 'closed' if there is both a start and end, and 'open' if there is no end date.


tofututo

package: tofu

title: tofututo(7)

text:
# tofututo(7)

## NAME
tofututo - a plain stupid tutorial for tofu.

## OBJECT
This tutorial covers the elements to master in order to be able to use tofu in an efficient way. The selected approach tries to be as much concrete, progressive and concise as possible.

## CONTENTS
PRELIMINARY STEPS

THE BASICS

Cook selections

Order your todo

Edit and feed your tasks

When things are got done

Several operations on a single line

TAGGING AND QUEUEING

Getting the right thing to work on now

A todo can hide another one

PLAY WITH MACROS

SEE ALSO

AUTHOR

## PRELIMINARY STEPS
Maybe you've already begun to play with tofu before discovering this tutorial. That's why we first go to create a separate and safe execution environment. Open a new terminal or a new console and type this ($ stands for the prompt, don't type it):

```
$ export TOFURC=/tmp/tofututorc
$ export TOFUDIR=/tmp/tofututo
```

If this one is not already set, specify also your favorite editor (unless vi is your pet):

```
$ export EDITOR=<edit_command>
```

At this point, we're sure to not break anything, so we can feed our dummy todo:

```
$ tofu next="Begin 'In Search of Lost Time'"
$ tofu next="Feed the cat before leaving"
$ tofu next="Clean the mouse"
$ tofu next="Recode getopt() in myproject-demo"
$ tofu next="Write myproject.1 and myproject.5"
$ tofu next="Recall Bob"
$ tofu next="Write the specification of myotherprojectDB"
$ tofu next="Fix the paths in MyProject.pm"
$ tofu next="Report the nasty bugs hidden in tofu"
$ tofu next="Achieve this tutorial"
$ tofu next="A last and pointless task"
```

Right, we're now ready to begin our exploration (notice that here you've already learned how to create new tasks :-). Ladies and Gentlemen, follow the guide...

## THE BASICS
In this section, we will introduce the set of functionnalities commonly needed for a daily use of tofu.

### Cook selections
As you can see if you enter it in your terminal, tofu invoked alone always prints the whole todo list. The first thing we will see is thus how to make more precise selections.

The easiest way to get a set of tasks is to call them by their position in the todo, enter this in your terminal:

```
$ tofu 3 2 5
```

You can also use a negative way, specifying the tasks you want to exclude and getting the others:

```
$ tofu -3 -2 -5
```

But let discover what's happens when we use the both mechanisms:

```
$ tofu 1 2 3 -3 -4 -5
```

As you can see, you get the two first tasks and the five last ones. We can deduce two things from this: 1) the -n (de-)selector is stonger than n, 2) when the selection is made exclusively from n selectors, this one is limited to the tasks selected by this way, but it's not the case when selector with a larger scope (-n means "all but") are introduced.

The first point is easy to understand and just illustrates the fact that tofu always takes the selection the most restrictive it can define. The second is more obscure though, has it any sense to use n with other ones? It has, let use them with the max=amount selector, which limits the amount of tasks selectedi, and the all one, which just call all the tasks in the selection:

```
$ tofu 7 8 9 all max=4
```

It results a selection composed from the first task plus the tasks we've explicitely selected. This shows the role of the n selectors when they are mixed with others: they create exceptions, so that the tasks selected by this way are never removed from the selection unless it's precisely requested.

### Order your todo
With tofu, the tasks are sorted by decreasing order of priority, so change the priority of a tasks is the same as change its position in the todo. The action to perform that is jump=position, try:

```
$ tofu 2 5 6 jump=1
$ tofu
```

tofu first extracts the tasks from the todo and makes a sub-list with them (it means that you could have write 6 5 2, the results would have been the same), then it inserts this one at the requested position in the remaining list. This means that the requested position doesn't refer to the one of the task which is currently at this one, but to the final position of the sub-list in the final todo. Illustration:

```
$ tofu 2 3 5 jump=4
$ tofu
```

You can see that the tasks 2, 3 and 5 are at the good position (fourth) in the current todo, but the task which was at the fourth in the previous todo is now the second one. So, keep in mind that the position are absolutely defined, not relatively to a task. It could seem not very handy at first glance, but in general it's not a problem (it's only unintuitive when the same jump both decreases and increases the priority of selected tasks).

Nevertheless, there are cases were it's handier to place the tasks relatively to another one. This can be achieved with the ride=task action:

```
$ tofu 2 3 8 ride=6
$ tofu
```

In the example above, the selection is inserted before the sixth task (which is now the seventh, due to the eighth which took a place before it). To get the same result with an absolute placing, the selection should have been sent to the fourth position.

### Edit and feed your tasks
Until now, a task has appeared to us as a mere line of text, but tofu does not limit you to this narrow format. Indeed, you have the possibility to append to each task as much further text as you want. This is very useful, for example when you know the algorithm you plan to use to realize a certain functionnality or when there are points you have absolutely to keep in mind when you modifying a certain part of code. Append text is performed with the edit action. Enter this an add some text after the first line:

```
$ tofu 1 edit
```

If, as usual, you type tofu on the command line after your editor's closed, you won't see much changes. This is normal, because default display of tofu tries to be concise. To recover the text you have entered, you have to use another display which is specified through the read action:

```
$ tofu 1 read
$ tofu 1 4 7 read
```

The first command above displays what you've written precedently, the second just aims to show you how tofu display several tasks in this mode. You can note that before each task header is inserted the position of the task, so that you can easily retrieve the ones interesting you in further tofu commands.

### When things are got done
Once you have realized a task in your todo, this one becomes useless. In the world of tofu, the way to process with such tasks is merely to definitively wipe them out. This is made through the delete action:

```
$ tofu 11 delete
```

To avoid precipitate trashing, tofu will always ask to you a confirmation and give you the possibility to read entirely the task a last time before throwing it back to the null dimension. This temperate behaviour also allows to strip a selection of tasks, deleting some and keeping others.

### Several operations on a single line
You've maybe remarked that the command lines we presented until now always put the selectors before the actions. This is merely because you can perform several selection-then-action cycles on the same line. Each time tofu detects a selector after a set of actions, it begins a new cycle. Look at this:

```
$ tofu 1 2 list 2 jump=1 1 2 list
```

As you can see, the two first tasks are primarily listed, then the second is moved to the first position, and endly we get an updated list. Trivial to understand, isn't it? Well, there is although a little subtlety, try this:

```
$ tofu 1 jump=7 list 1 list
```

Do you see the problem? in the second selection, the task should be different, as we have sent the first task to the seventh position, but it shows precisely this one at the seventh position. In fact, this is not a problem, but a solution. As matter of fact, when you begin to write a complex command line you generally know which task is which task, but after one or two jump or/and deletion it can rapidly become tricky to anticipate the position of each one. That's why tofu chooses to always refer to the initial positions in the todo, the only ones you can really know. So when you use n or -n, you can safely do it all along the line, you're sure of the task it will point on.

## TAGGING AND QUEUEING
Select tasks by position is enough to deal with todo containing few tasks, as the one we use in this tutorial. Nevertheless, if you need a todo manager software, it's probably because you expect to have a little more stuff than that. That's why we will see in this section how categorize things and create sub-todo list(s).

### Getting the right thing to work on now
The command to use to add tags is stamp=tags, let's add some on our tasks:

```
$ tofu 2 3 8 stamp=myproject,code
$ tofu 6 stamp=myotherproject,code
$ tofu 8 9 stamp=bug
$ tofu 7 10 stamp=read
$ tofu 1 4 stamp=life,pointless all
```

As you can see, the tags now appear in the digest of the tasks they are put on. This allows to easily retrieve our tasks accoding to the type of things we want to do at the moment. For example, if you want to code:

```
$ tofu wi=code
```

or, on the contrary, if after passing the day to do it, you want to do anything but not debugging nor coding:

```
$ tofu wo=code,bug
```

The new wi=tags and wo=tags we introduced respectively select and reject any task which bears at least one of the specified tags. There are also variants of them that select or reject any task which bears all of the specified tags:

```
$ tofu wil=bug,myproject digest wol=bug,myproject digest wo=read 10
```

As expected, the first cycle above shows you the eighth task while the second prints the ninth. The third cycle merely recalls you the characteristic of the individual selectors (the tenth task bears "read"), which becomes very handy used in conjonction with the tags.

To remove tags, use the erase=tags command:

```
$ tofu 1 4 erase=pointless
```

### A todo can hide another one
Tagging is a mechanism which quitely helps to deal with a large todo list. But it reaches its limits soon. For example, when you work on a project, you really don't care about the rest of your todo list and it's quickly annoying to have to remember to explicitely include or exclude this or this tag in commands. The queue=tag selector aims precisely to resolv such problems:

```
$ tofu queue=myproject
```

It creates a new list with all the tasks bearing the requested tag and masks the others. Moreover, tofu will stay in this queue as long as you don't order a change and automatically add its associated tag to the new tasks, so you can safely keep the nose in your project for hours, you don't risk to mess tasks that are not related. To get back the whole todo, simply request the main queue, which is a reserved item:

```
$ tofu queue=main
```

Note that change queue in the middle of a command line reset the individual selector references, so avoid to use them both or choose your queue in the first cycle:

```
$ tofu queue=read 1 list queue=bug 1 list 1 queue=main list
```

As you can see, each cycle above shows a different task for the same selector.

## PLAY WITH MACROS
To achieve this tutorial, we will say some words about another handy mechanism provided by tofu: the macros. If tofu becomes tour daily todo manager, you will often have to repeat the same operations, and sometimes these one are complex and long to specify. Define macros is then the solution to create shortcuts and new commands. These ones must be written into the configuration file. Edit it:

```
$ $EDITOR $TOFURC
```

Macro definitions are set through the macroname(macrobody) syntax. Each command which makes up the body is separated from the others by a period, and members of a tag list by a space. Moreover, the macros can take arguments if you let the arguments of the command which take some empty. Here are some examples (the leading # introduce comments):

```
# a shortcut for the "myproject" queue.
qmyproject(queue=myproject)
amyproject(next=, stamp=myproject code)
# (un-)highlight the tasks you want to work on.
select(stamp=workinprogress, color=1)
reject(erase=workinprogress, color=0)
qselect(queue=workinprogress)
wselect(wi=workinprogress)
# manage the todo in the tofu 2.x fashion
hset(stamp=hot, erase=cool warm, color=3)
wset(stamp=warm, erase=hot cool, color=5)
cset(stamp=cool, erase=warm hot, color=8)
hot(wi=hot)
warm(wi=warm)
cool(wi=cool)
sort(wi=cool, jump=1, wi=warm, jump=1, wi=hot, jump=1, all)
```

Once defined, the macros are used on the command line just like other commands, except that a column (:) is prepended to them:

```
$ tofu :amyproject="Recode the build system"
$ tofu :cset 6 7 :wset 2 3 :hset :sort
$ tofu 2 5 6 :select digest
```

The last examples should have taught you the purpose of the color=n command we introduced in the definition. This one is particuliary useful in macros where they are associated with tags.

## SEE ALSO
tofu(1), tofuup(1)

## AUTHOR
This tutorial written and are maintained by Sébastien Boillod. Bug/typo reports, patches, suggestions, feedbacks and so on are welcome at <sbb at tuxfamily dot org>.

This tutorial manual are published under the terms of the very permissive MIT/X11 license. The text of this one is reproduced at the head of the tofu script.


package: torque-client

title: pbs_job_attributes(7)

summary: pbs job attributes

text:
# pbs_job_attributes(7)

## NAME
pbs_job_attributes - pbs job attributes

## DESCRIPTION
A batch job has the following public attributes shown in the following list. The attributes marked with the section symbol § are required by POSIX 1003.2d: If an attribute is unset, the indicated default value is assumed.

Account_Name §

Used for accounting on some hosts. Format: string; default value: none, not used.

Checkpoint §

If supported by the server implementation and the host operating system, the checkpoint attribute determines when checkpointing will be performed by PBS on behalf of the job. The legal values for checkpoint are described under the qalter and qsub commands. Format: the strings "n", "s", "c", "c=mmmm"; default value: "u", which is unspecified.

depend

The type of inter-job dependencies specified by the job owner. Format: "type:jobid[,jobid...]"; default value: no dependencies.

Error_Path §

The final path name for the file containing the job's standard error stream. See the qsub and qalter command description for more detail. Format: "[hostname:]pathname"; default value: (job_name).e(job_number).

Execution_Time §

The time after which the job may execute. The time is maintained in seconds since Epoch. If this time has not yet been reached, the job will not be scheduled for execution and the job is said to be in wait state. Format: "[[CCwYY]MMDDhhmm[.ss]"; default value: time 0, no delay.

group_list §

A list of group_names@hosts which determines the group under which the job is run on a given host. [internal type: array of strings] When a job is to be placed into execution, the server will select a group name according to the following ordered set of rules:

1.

Select the group name from the list for which the associated host name matches the name of the execution host.

2.

Select the group name which has no associated host name, the wild card name.

3.

Use the login group for the user name under which the job will be run.

Format: "group_name[@host][,group_name[@host]...]".

Hold_Types §

The set of holds currently applied to the job. If the set is not null, the job will not be scheduled for execution and is said to be in the hold state. Note, the hold state takes precedence over the wait state. Format: string made up of the letters 'u', 's', 'o'; default value: no hold.

Job_Name §

The name assigned to the job by the qsub or qalter command. Format: string up to 15 characters, first character must be alphabetic; default value: the base name of the job script or STDIN.

Join_Path §

If the Join_Paths attribute is {TRUE}, then the job's standard error stream will be merged, inter-mixed, with the job's standard output stream and placed in the file determined by the Output_Path attribute. The Error_Path attribute is maintained, but ignored. Format: boolean, values accepted are "True", "TRUE", "true", "Y", "y", "1", "False", "FALSE", "false", "N", "n", "0"; default value: false.

Keep_Files §

If Keep_Files contains the values "o" and/or "e" the corresponding streams of the batch job will be retained on the execution host upon job termination. Keep_Files overrides the Output_Path and Error_Path attributes. Format: "o", "e", "oe" or "eo"; default value: no keep, return files to submission host.

Mail_Points §

Identifies at which state changes the server will send mail about the job. Format: string made up of the letters 'a' for abort, 'b' for beginning, and default value: 'a', send on job abort.

Mail_Users §

The set of users to whom mail may be sent when the job makes certain state changes. Format: "user@host[,user@host]"; default value: job owner only.

Output_Path §

The final path name for the file containing the job's standard output stream. See the qsub and qalter command description for more detail. Format: see error_path, default value: (job_name).o(job_number).

Priority §

The job scheduling priority assigned by the user. Format: "[+|-]nnnnn"; default value: undefined.

Rerunable §

The rerunable flag given by the user. Format: "y" or "n", see Join_Path; default value: y, job is rerunable.

Resource_List §

The list of resources required by the job. The resource list is a set of name=value strings. The meaning of name and value is server dependent. The value also establishes the limit of usage of that resource. If not set, the value for a resource may be determined by a queue or server default established by the administrator. Default value: no usage or no limit depending on specific resource.

Shell_Path_List §

A set of absolute paths of the program to process the job's script file. The list is in the format: "path[@host][,path[@host]...]". If this is null, then the user's login shell on the host of execution will be used. Default value: null, login shell.

stagein

The list of files to be staged in prior to job execution. Format: local_path@remote_host:remote_path

stageout

The list of files to be staged out after job execution. Format: local_path@remote_host:remote_path

User_List §

The list of user@hosts which determines the user name under which the job is run on a given host. [internal type: array of strings] When a job is to be placed into execution, the server will select a user name from the list according to the following ordered set of rules:

1.

Select the user name from the list for which the associated host name matches the name of the execution host.

2.

Select the user name which has no associated host name, the wild card name.

3.

Use the Job_Owner as the user name.

Default value: job owner name.

Variable_List §

This is the list of environment variables passed with the Queue Job batch request. Format: "name=value[,name=value...]".

The following attributes require system, manager, or operator privilege to set. They are visible to clients depending on privilege as noted.

comment

An attribute for displaying comments about the job from the system. Visible to any client. Format: any string; default value: none.

sched_hint

This attribute is present when the job is a member of a synchronous dependency set. It is set when the hold is released on the job. The value is {SYNC_SCHED_HINT_FIRST} (1) when the first job of the set is released for scheduling. This is a hint that may be used by the scheduler to decrease the priority of the job. This keeps a user from attempting to game the scheduler. The attribute is set to {SYNC_SCHED_HINT_OTHER} (2) for all other jobs in the set as they become schedulable. This should be taken as a hint by the scheduler to increase their priority to insure they will run at the same time as the earlier scheduled jobs in the set. [This attribute is viewable only by the batch administrator.] [type: integer]

The following attributes are read-only, they are established by the server and are visible to the client but cannot be set by a client. Certain ones are only visible to privileged clients (those run by the batch administrator).

alt_id

For a few systems, such as Irix 6.x running Array Services, the session id is insufficient to track which processes belong to the job. Where a different identifier is required, it is recorded in this attribute. If set, it will also be recorded in the end-of-job accounting record.

For Irix 6.x running Array Services, the alt_id attribute is set to the Array Session Handle (ASH) assigned to the job.

ctime

The time that the job was created.

etime

The time that the job became eligible to run, i.e. in a queued state while residing in an execution queue.

exec_host

If the job is running, this is set to the name of the host on which the job is executing.

exit_status

The exit status of the job. This is only set on receipt of a job obituary notice from MOM, and probably only useful if the "keep_completed" server attribute is set. Note that negative values are generated internally by PBS to indicate system errors and are listed as the JOB_EXEC_* defines in pbs_job.h. Positive values are returned from the user script and cannot be interpreted by PBS.

egroup

If the job is queued in an execution queue, this attribute is set to the group name under which the job is to be run. [This attribute is available only to the batch administrator.]

euser

If the job is queued in an execution queue, this attribute is set to the user name under which the job is to be run. [This attribute is available only to the batch administrator.]

hashname

The name used as a basename for various files, such as the job file, script file, and the standard output and error of the job. [This attribute is available only to the batch administrator.]

interactive

True if the job is an interactive PBS job. Format: boolean, see Join_Paths; default value: false.

Job_Owner §

The login name on the submitting host of the user who submitted the batch job.

job_state

The state of the job.

E

for exiting, the job has completed execution, with or without errors, and the batch system is doing post-execution clean-up.

H

for Held, one or more holds have been applied to the job.

Q

for Queued, the job resides in a execution or routing queue pending execution or routing. It is not in held or waiting state.

R

for Running, the job resides in a execution queue and has been placed into execution.

S

for Suspend (Job running on Unicos only), the job was executing and has been suspended. The job retains its assigned resources but does not use cpu cycle or walltime.

T

for Transiting, the job is in process of being routed or moved to a new destination.

W

for Waiting, the job is not held but the Execution_Time attribute contains a time which has not yet been reached.

mtime

The time that the job was last modified, changed state, or changed locations.

qtime

The time that the job entered the current queue.

queue

The name of the queue in which the job currently resides.

queue_rank

An ordered, non-sequential number indicating the job's position with in the queue. This is provided as an aid to the scheduler. [This attribute is available to the batch manager only.]

queue_type

An identification of the the type of queue in which the job is currently residing. This is provided as an aid to the scheduler. [This attribute is available to the batch manager only.] Format: The letter E or the letter r.

resources_used §

The amount of resources used by the job. This is provided as part of job status information if the job is running.

server

The name of the server which is currently managing the job.

session_id

If the job is running, this is set to the session id of the first executing task.

substate

A numerical indicator of the substate of the job. The substate is used by the PBS job server internally. The attribute is visible to privileged clients, such as the scheduler. Format: integer.

## SEE ALSO
PBS ERS, qsub(1B), qalter(1B), pbs_resources(7B)