starship/docs/pt-BR/advanced-config

Configuração avançada

Ainda que Starship seja um shell versátil, às vezes você precisará fazer algumas outras coisas além de editar o arquivo starship.toml. Esta página detalha algumas das técnicas de configuração avançadas utilizadas no starship.

::: atenção

As configurações nesta seção estão sujeitas a alterações em futuras versões do Starship.

:::

TransientPrompt in PowerShell

It is possible to replace the previous-printed prompt with a custom string. This is useful in cases where all the prompt information is not always needed. To enable this, run Enable-TransientPrompt in the shell session. To make it permanent, put this statement in your $PROFILE. Transience can be disabled on-the-fly with Disable-TransientPrompt.

By default, the left side of input gets replaced with >. To customize this, define a new function called Invoke-Starship-TransientFunction. For example, to display Starship's character module here, you would do

function Invoke-Starship-TransientFunction {
  &starship module character
}

Invoke-Expression (&starship init powershell)

Enable-TransientPrompt

TransientPrompt and TransientRightPrompt in Cmd

Clink allows you to replace the previous-printed prompt with custom strings. This is useful in cases where all the prompt information is not always needed. To enable this, run clink set prompt.transient <value> where <value> can be one of:

• always: always replace the previous prompt
• same_dir: replace the previous prompt only if the working directory is same
• off: do not replace the prompt (i.e. turn off transience)

You need to do this only once. Make the following changes to your starship.lua to customize what gets displayed on the left and on the right:

• By default, the left side of input gets replaced with >. To customize this, define a new function called starship_transient_prompt_func. This function receives the current prompt as a string that you can utilize. For example, to display Starship's character module here, you would do

function starship_transient_prompt_func(prompt)
  return io.popen("starship module character"
    .." --keymap="..rl.getvariable('keymap')
  ):read("*a")
end
load(io.popen('starship init cmd'):read("*a"))()

• By default, the right side of input is empty. To customize this, define a new function called starship_transient_rprompt_func. This function receives the current prompt as a string that you can utilize. For example, to display the time at which the last command was started here, you would do

function starship_transient_rprompt_func(prompt)
  return io.popen("starship module time"):read("*a")
end
load(io.popen('starship init cmd'):read("*a"))()

Comandos personalizados de pré-prompt e pré-execução no Cmd

O Clink fornece APIs extremamente flexíveis para executar comandos pré-prompt e pré-execução em Cmd shell. É bastante simples de usar com o Starship. Faça as seguintes alterações no seu arquivo starship.lua conforme suas necessidades:

• Para executar uma função personalizada logo antes do prompt ser inicializado, defina um novo função chamada starship_preprompt_user_func. Esta função recebe o prompt atual como uma string que você pode utilizar. Por exemplo, para exibir um foguete antes do prompt, você faria

function starship_preprompt_user_func(prompt)
  print("🚀")
end

load(io.popen('starship init cmd'):read("*a"))()

• Para executar uma função personalizada logo antes de um comando ser executado, defina um novo função chamada starship_precmd_user_func. Esta função recebe a linha de comando atual como uma string que você pode utilizar. Por exemplo, para imprimir o comando que está prestes a ser executado, você faria

function starship_precmd_user_func(line)
  print("Executing: "..line)
end

load(io.popen('starship init cmd'):read("*a"))()

Comandos personalizados de pre-prompt e pre-execution no Bash

O Bash não possui uma estrutura formal para os hooks preexec/precmd como a maioria dos outros shells. Por esse motivo, é difícil fornecer hooks totalmente customizáveis no bash. No entanto, Starship te oferece uma capacidade limitada de inserir suas próprias funções na processo de prompt-rendering:

• Para rodar uma função personalizada antes do prompt iniciar, defina uma nova função e atribua seu nome para starship_precmd_user_func. Por exemplo, para desenhar um foguete antes do prompt iniciar você faria

function blastoff(){
    echo "🚀"
}
starship_precmd_user_func="blastoff"

• Para rodar uma função personalizada antes que um comando seja executado, você pode usar DEBUG como mecanismo de armadilha. No entanto, você deve capturar o sinal DEBUG antes de inicializar o Starship! O Starship consegue preservar o valor da armadilha DEBUG, mas se a armadilha for substituída depois do starship iniciar, algumas funções iram quebrar.

function blastoff(){
    echo "🚀"
}
trap blastoff DEBUG     # Captura o DEBUG *antes* de executar a nave estelar
set -o functrace
eval $(starship init bash)
set +o functrace

Comandos personalizados de pre-prompt e pre-execution no PowerShell

O PowerShell não possui uma estrutura formal para os hooks preexec/precmd como a maioria dos outros shells. Por esse motivo, é difícil fornecer hooks totalmente customizáveis no powershell. No entanto, Starship te oferece uma capacidade limitada de inserir suas próprias funções na processo de prompt-rendering:

Crie uma função chamada Invoke-Starship-PreCommand

function Invoke-Starship-PreCommand {
    $host.ui.Write("🚀")
}

Altera o título da janela

Alguns shell prompts iram alterar o titulo da janela automaticamente para você (e.x: para espelhar o diretório atual). Fish faz isso por padrão. Starship não faz isso, mas é bastante simples adicionar essa funcionalidade para bash, zsh, cmd ou powershell.

Primeiro, defina uma função de alteração de titulo de janela (é o mesmo para bash e zsh):

function set_win_title(){
    echo -ne "\033]0; YOUR_WINDOW_TITLE_HERE \007"
}

Você pode usar variáveis para customizar o titulo ($USER, $HOSTNAME, e $PWD são escolhas populares).

No bash, defina esta função como a precedente da função starship:

starship_precmd_user_func="set_win_title"

No zsh, adicione no array precmd_functions:

precmd_functions+=(set_win_title)

Se você gostar do resultado, adicione esta linha ao seu arquivo de configuração de shell (~/.bashrc or ~/.zshrc) para torna-lo permanente.

Por exemplo, se você quiser exibir seu diretório atual no seu titulo de aba do terminal, adicione o seguinte snippet ao seu ~/.bashrc ou ~/.zshrc:

function set_win_title(){
    echo -ne "\033]0; $(basename "$PWD") \007"
}
starship_precmd_user_func="set_win_title"

Para Cmd, você pode alterar o título da janela usando a função starship_preprompt_user_func.

function starship_preprompt_user_func(prompt)
  console.settitle(os.getenv('USERNAME').."@"..os.getenv('COMPUTERNAME')..": "..os.getcwd())
end

load(io.popen('starship init cmd'):read("*a"))()

Você também pode definir uma saída semelhante com o PowerShell criando uma função chamada Invoke-Starship-PreCommand.

# edit $PROFILE
function Invoke-Starship-PreCommand {
  $host.ui.Write("`e]0; PS> $env:USERNAME@$env:COMPUTERNAME`: $pwd `a")
}

Invoke-Expression (&starship init powershell)

Ativando o Prompt Direito

Alguns shells suportam um prompt no lado direito que renderiza na mesma linha do input. Starship consegue definir o conteúdo do prompt direito usando a opção right_format. Qualquer módulo pode ser usado no format é suportado o right_format. A variável $all só irá alterar os módulos que não usaram de forma explicita o format ou right_format.

Nota: O prompt direito é uma linha única seguindo o local de entrada. Para alinhar módulos à direita acima da linha de entrada em um prompt de várias linhas, consulte o módulo fill.

right_format é atualmente compatível com os seguintes shells: elvish, fish, zsh, xonsh, cmd.

Exemplo

# ~/.config/starship.toml

# Um prompt esquerdo minimo 
format = """$character"""

# Move o resto do prompt para direita
right_format = """$all"""

Gera um prompt parecido com o seguinte:

▶                                   starship on  rprompt [!] is 📦 v0.57.0 via 🦀 v1.54.0 took 17s

Prompt de Continuação

Alguns shells suportam um prompt de continuação junto com o prompt normal. Esse prompt é renderizado em vez do prompt normal quando o usuário insere uma instrução incompleta (como um único parêntese esquerdo ou aspas).

Starship pode definir o prompt de continuação usando a opção continuation_prompt. O prompt padrão é "[∙](bright-black) ".

Nota: continuation_prompt deve ser definido como uma string literal sem nenhuma variável.

Nota: os prompts de continuação estão disponíveis apenas nos seguintes shells:

• bash
• zsh
• PowerShell

Exemplo

# ~/.config/starship.toml

# Um prompt de continuação que exibe duas setas preenchidas
continuation_prompt = "▶▶"

Estilo dos textos

Estilo de strings são uma lista de palavras, separadas por espaço. As palavras não são case sensitive (ou seja bold e BoLd são consideradas iguais). Cada palavra pode ser uma das seguintes:

• bold
• italic
• underline
• dimmed
• inverted
• blink
• hidden
• strikethrough
• bg:<color>
• fg:<color>
• <color>
• none

onde <color> é uma especialista de cores (discutido abaixo). fg:<color> e <color> atualmente fazem a mesma coisa, isto deve mudar no futuro. inverted troca as cores de background e foreground. A ordem de palavras na string não importa.

O token none substitui todos os outros tokens na string se ele não fizer parte de um bg: especificado que seja, por exemplo fg:red none fg:blue ainda criará uma string sem estilo. bg:none define a cor padrão de background então fg:red bg:none é equivalente a red ou fg:red e bg:green fg:red bg:none é equivalente a fg:red oured. Pode se transformar em um erro ao usar none em um conjunto de outros tokens no futuro.

Um especialista em cores pode ser um dos seguintes:

• Uma das cores padrão do terminal: black, red, green, blue, yellow, purple, cyan, white. Você pode, opcionalmente, prefixar esses com bright- para obter a versão brilhante/clara (por exemplo, bright-white).
• Um # seguido por um número de seis dígitos hexadecimais. Isto especifica um Código RGB em formato hexadecimal.
• Um número entre 0-255. Este especifica um Código de Cor ANSI 8 bits.

Se múltiplas cores forem especificadas para foreground/background, a ultima da string que terá prioridade.

Not every style string will be displayed correctly by every terminal. In particular, the following known quirks exist:

• Many terminals disable support for blink by default
• hidden is not supported on iTerm (https://gitlab.com/gnachman/iterm2/-/issues/4564).
• strikethrough is not supported by the default macOS Terminal.app