commands.texi

@node Commands, Files, Top, Top
@chapter Commands
This is the pacstall command reference page.

@menu
---- Managing & Interacting with Packages ----

* Handling Packages::       All commands relating to handling packages.
* Handling Repositories::   All commands relating to handling repositories.
* Other Assorted Commands:: Other commands that do not fall neatly into either category.

---- Miscellaneous ----

* Environmental Flags:: Flags that affect other flags.
* Environmental Variables:: Variables that affect pacstall.
@end menu

@node Handling Packages, -I, Commands, Commands
@section Handling Packages

These flags are used to directly or indirectly reference packages.

@menu
* -I::  Install a package.
* -R::  Remove a package.
* -S::  Search for a package.
* -Sd:: Search description for a package.
* -Si:: Show SRCINFO contents for a package.
* -Up:: Upgrade packages.
* -Ci:: Display installed package metadata.
* -L::  List installed packages.
* -Qa:: Test a package from a PR.
* -T::  Display a tree graph of an installed package.
@end menu

@node -I, -R, Handling Packages, Handling Packages
@section -I
@code{pacstall -I} is the primary command used to install packages:

@example
@command{pacstall} [@option{-P -K -B -Q -Nc -Ns}] -I @var{package}@enddots{}
@end example

@samp{-I} can take any environmental flags (@pxref{Environmental Flags}).

This flag installs a given package from a remote repository or a local @ref{Pacscript}. As of now, these are the providers that @samp{-I} has enhanced syntax for targeting repositories:

@itemize
@item @samp{github}
@item @samp{gitlab}
@item @samp{sourcehut}
@item @samp{codeberg}
@end itemize

Other git providers may use a direct link or submit a patch to add yours. Those providers must be added beforehand to the @ref{pacstallrepo} with @ref{-A}. If multiple repositories are enabled, pacstall will default to @samp{pacstall/pacstall-programs}, but you can still choose to install from other repositories.

You may also specify a local pacscript by including the @file{.pacscript} suffix.

@example
$ pacstall -I neofetch # Install neofetch
@end example

@example
$ pacstall -I "alacritty@@github:user/reponame" # Install 'alacritty' from @url{https://github.com/user/reponame}
@end example

@example
$ pacstall -I "alacritty@@https://raw.githubusercontent.com/user/reponame/master" # Install 'alacritty' from a raw link
@end example

@example
$ pacstall -I "citra@@piracy" # Install 'citra' from a repository @ref{alias} named 'piracy'
@end example

@example
$ pacstall -I foo.pacscript # Install a local file called @file{foo.pacscript}
@end example

@example
$ pacstall -I @strong{$parent}:pkgbase # Install all pkgnames in the pkgbase named @strong{parent}
@end example

@example
$ pacstall -I parent:@strong{$child} # Install only the pkgname @strong{child} from the pkgbase parent.
@end example

@node -R, -S, -I, Handling Packages
@section -R
@code{pacstall -R} is the primary way to remove a given package from the system:

@example
@command{pacstall} [@option{-P}] -R @var{package}
@end example

@node -S, -Sd, -R, Handling Packages
@section -S
@code{pacstall -S} is one of the ways to search for a given package:

@example
@command{pacstall} -S @var{package}
@end example

A clickable hyperlink to repositories are displayed in VTE terminals.

To search in a specific repository, use the @samp{@@} separator.

@example
$ pacstall -S -git # Search for all git packages
@end example

@example
$ pacstall -S "-bin@@github:user/reponame" # Search for all binary packages in a specific repo
@end example

@node -Sd, -Si, -S, Handling Packages
@section -Sd
@code{pacstall -Sd} is one of the ways to search for a given package with description searching:

@example
@command{pacstall} -Sd @var{package}
@end example

Like @ref{-S}, but both displays description on output, and searches through descriptions upon the query. To do case-sensitive search, use quotes within quotes ("''" or '""').

@example
$ pacstall -Sd browser # Search for 'browser' in name and description of packages
@end example

@example
$ pacstall -Sd "'Browser'" # Search for the literal string 'Browser' in name and description
@end example

@node -Si, -Up, -Sd, Handling Packages
@section -Si
@code{pacstall -Si} is one of the ways to display a given package's @url{https://wiki.archlinux.org/title/.SRCINFO, SRCINFO} contents.

@example
@command{pacstall} -Si @var{package}
@end example

Alongside the simple invocation, this flag can take packages just like @ref{-I}.

@node -Up, -Ci, -Si, Handling Packages
@section -Up
@code{pacstall -Up} is the primary method to upgrade packages.

@example
@command{pacstall} [@option{-P -K}] -Up
@end example

@node -Ci, -L, -Up, Handling Packages
@section -Ci
Display metadata of an installed package:

@example
@command{pacstall} -Ci @var{package} @option{key}
@end example

If no @option{key} is passed, terminal output will include all metadata values. If @option{key} is included, terminal output will only have the referenced key contents displayed.

@example
$ pacstall -Ci neofetch # Display metadata for neofetch
@end example

@example
$ pacstall -Ci firefox-bin version # Display version of firefox-bin
@end example

@node -L, -Qa, -Ci, Handling Packages
@section -L
List installed packages.

The output can come in two forms. If pacstall detects it is being piped, it will print a newline separated list of package names, which is useful for scripting. If pacstall is not being piped, it will print every package with some useful metadata. This second form is @strong{not} useful for scripting and should @strong{not} be used for it.

@node -Qa, -T, -L, Handling Packages
@section -Qa
Test a package from a PR downstream before merging.

@example
@command{pacstall} -Qa @var{package}#@var{number}@@@var{metalink}
@end example

Where the @var{package} is given first, followed by the pull request @var{number}, separated by a @samp{#}.

Optionally, a metalink separated by a @samp{@@} may be provided before or after @var{number}. The metalink is broken down into 3 parts:

@itemize
@item @samp{provider}
@item @samp{owner}
@item @samp{repo}
@end itemize

The @samp{owner} should be the owner of the repository the PR is being merged into, @strong{not} the user who created the PR. No other flags should be provided to this command.

@example
$ pacstall -Qa firefox-bin#5853
@end example

@example
$ pacstall -Qa firefox-bin#5853@@github:@value{SHORTHANDREPO}
@end example

@node -T, , -Qa, Handling Packages
@section -T
Display a tree graph of a package:

@example
@command{pacstall} -T @var{package}
@end example

This command is a holdout from when pacstall used @command{stow}, and one could just run @command{tree /usr/src/pacstall/pkg}.

@node Other Assorted Commands, -I, Commands, Commands
@section Other Assorted Commands

These commands are more general purpose.

@menu
* -U:: Update pacstall.
* -D:: Download pacscript.
@end menu

@node -U, -D, Other Assorted Commands, Other Assorted Commands
@section -U
This is the primary method of updating pacstall.

@example
@command{pacstall} -U [@option{username} [@option{branch}] | @samp{.}]
@end example

This updates pacstall and needed scripts. If no argument for @option{branch} is given, it will default to @samp{master}. When updating to a specific repository, the arguments will be saved (@pxref{update}) and passed in the next time @code{-U} is used, but only if no arguments are given. You may replace the space separating the username and branch with a @samp{:} if you want.

If the repository cannot be reached, pacstall will not update, and the current state will not be changed.

You may also pass in a literal period (@samp{.}) which will update from the current directory (assuming it is a pacstall repository)

@node -D, , -U, Other Assorted Commands
@section -D
Download pacscript to current directory.

@example
@command{pacstall} -D @var{package}
@end example

You may also specify an arbitrary repository in the same method as specifying repositories with @ref{-S}.

@node Handling Repositories, , Commands, Commands
@section Handling Repositories

These commands are used to deal with repositories.

@menu
* -A::  Add repositories.
* -Rr:: Remove a repository.
@end menu

@node -A, -Rr, Handling Repositories, Handling Repositories
@section -A
This is the primary method of adding repositories to pacstall.

If a plain GitHub or GitLab link is given without a @samp{branch}, pacstall will default to @samp{master}. Local repositories are also supported, which can be useful for testing pacscripts without pushing remotely, having portable repositories on a USB stick, custom/private applications, internal company repositories, etc. Additionally, an @ref{alias} can be optionally linked to a repository, so that it is easier to call and reference from. The following command are valid ways to add a repository:

@example
$ pacstall -A https://github.com/@emph{user}/@emph{repo}
@end example

@example
$ pacstall -A https://github.com/@emph{user}/@emph{repo}/tree/@emph{branch}
@end example

@example
$ pacstall -A github:@emph{user}/@emph{repo}
@end example

@example
$ pacstall -A github:@emph{user}/@emph{repo}#@emph{branch}
@end example

@example
$ pacstall -A github:@emph{user}/@emph{repo} @@@emph{alias}
@end example

These forms above can be duplicated for @samp{gitlab}, @samp{gitlab}, @samp{sourcehut}, and @samp{codeberg}.

@example
$ pacstall -A file://home/user/local-repository
@end example

@example
$ pacstall -A /home/user/local-repository
@end example

@example
$ pacstall -A local:/home/user/local-repository
@end example

@example
$ pacstall -A https://myonlinerepo.com/here
@end example

@node -Rr, , Handling Repositories, Handling Repositories
@section -Rr
Remove a given repository from pacstall. @xref{-A} for syntax usage. Passing only an alias is valid here as well:

@example
@command{pacstall} -Rr [@var{repo} | @@@option{alias}]
@end example

@example
$ pacstall -Rr github:pacstall/pacstall # Remove main repository
@end example

@example
$ pacstall -Rr @@piracy # For when you get caught by the feds
@end example

@node Environmental Flags, , Commands, Commands
@section Environmental Flags

These flags are used to modify the functionality of other flags.

@menu
* -P::  Disable prompts.
* -K::  Keep build files after finishing.
* -B::  Build deb file only.
* -Q::  Quiet downloading.
* -Nc:: Skip check() when building.
* -Ns:: Build without bwrap.
@end menu

@node -P, -K, Environmental Flags,
@section -P
If included, this will default all prompts to their default given value.

@node -K, -B, -P, Environmental Flags
@section -K
Keep the build of a package if the build process fails or succeeds.

@node -B, -Q, -K, Environmental Flags
@section -B
Only build the deb file, but do not install. This is useful for shipping software outside of pacstall.

@node -Q, -Nc, -B, Environmental Flags
@section -Q
Silence any download output.

@node -Nc, -Ns, -Q, Environmental Flags
@section -Nc
Skip @ref{check()} function when building package.

@node -Ns, , -Nc, Environmental Flags
@section -Ns
Build package without using @command{bwrap} system. This flag should be used with caution, and can lead to potential unwanted harm on a system. It is primarily intended for uses in environments such as @command{chroot}, @command{docker}, or WSL which have some primitive level of isolation or fundamental incompatibility with certain kernel features.

@node Environmental Variables, DISABLE_PROMPTS, Commands, Commands
@section Environmental Variables

@menu
* DISABLE_PROMPTS:: Disable prompts.
* PACSTALL_SUPPRESS_SOLUTIONS:: Remove suggestions given by Pacstall to fix problems.
* PACSTALL_BUILD_CORES:: Override build core count.
* PACSTALL_EDITOR:: Override editor used by pacstall.
* NO_COLOR:: Turn off all output colors.
@end menu

@node DISABLE_PROMPTS, PACSTALL_SUPPRESS_SOLUTIONS, Environmental Variables,
@section DISABLE_PROMPTS
Functionally the same as @ref{-P} but in a variable form.

@node PACSTALL_SUPPRESS_SOLUTIONS, PACSTALL_BUILD_CORES, DISABLE_PROMPTS, Environmental Variables
@section PACSTALL_SUPPRESS_SOLUTIONS
Set this to any value to remove suggestions given by Pacstall to fix problems. This would most likely be used in a CI where extra output is not needed.

@node PACSTALL_BUILD_CORES, , PACSTALL_SUPPRESS_SOLUTIONS, Environmental Variables
@section PACSTALL_BUILD_CORES
If set to a valid integer, this will override @command{nproc} output and the @var{$NCPU} variable used in many pacscripts.

@node PACSTALL_EDITOR, NO_COLOR, PACSTALL_BUILD_CORES, Environmental Variables
@section PACSTALL_EDITOR
Set to a valid command name to override the editor pacstall will use when editing text files (installing pacscripts).

@node NO_COLOR, , PACSTALL_EDITOR, Environmental Variables
@section NO_COLOR
Set to any value to turn off all output colors in pacstall.