.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "STRING-PAD" "1" "Nov 13, 2025" "4.2" "fish-shell"
.SH NAME
string-pad \- pad strings to a fixed width
.SH SYNOPSIS
.nf
\fBstring\fP \fBpad\fP [\fB\-r\fP | \fB\-\-right\fP] [\fB\-C\fP | \fB\-\-center\fP] [(\fB\-c\fP | \fB\-\-char\fP) \fICHAR\fP] [(\fB\-w\fP | \fB\-\-width\fP) \fIINTEGER\fP]
           [\fISTRING\fP \&...]
.fi
.sp
.SH DESCRIPTION
.sp
\fBstring pad\fP extends each \fISTRING\fP to the given visible width by adding \fICHAR\fP to the left. That means the width of all visible characters added together, excluding escape sequences and accounting for \fI\%fish_emoji_width\fP and \fI\%fish_ambiguous_width\fP\&. It is the amount of columns in a terminal the \fISTRING\fP occupies.
.sp
The escape sequences reflect what fish knows about, and how it computes its output. Your terminal might support more escapes, or not support escape sequences that fish knows about.
.sp
If \fB\-C\fP or \fB\-\-center\fP is given, add the padding to before and after the string. If it is impossible to perfectly center the result (because the required amount of padding is an odd number), extra padding will be added to the left, unless \fB\-\-right\fP is also given.
.sp
If \fB\-r\fP or \fB\-\-right\fP is given, add the padding after a string.
.sp
If \fB\-c\fP or \fB\-\-char\fP is given, pad with \fICHAR\fP instead of whitespace.
.sp
The output is padded to the maximum width of all input strings. If \fB\-w\fP or \fB\-\-width\fP is given, use at least that.
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>_ string pad \-w 10 abc abcdef
       abc
    abcdef

>_ string pad \-\-right \-\-char=🐟 \(dqfish are pretty\(dq \(dqrich. \(dq
fish are pretty
rich.  🐟🐟🐟🐟

>_ string pad \-w$COLUMNS (date)
# Prints the current time on the right edge of the screen.
.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
.INDENT 0.0
.IP \(bu 2
The \fI\%printf\fP command can do simple padding, for example \fBprintf %10s\en\fP works like \fBstring pad \-w10\fP\&.
.IP \(bu 2
\fI\%string length\fP with the \fB\-\-visible\fP option can be used to show what fish thinks the width is.
.UNINDENT
.SH COPYRIGHT
fish-shell developers
.\" Generated by docutils manpage writer.
.