O recurso de folding (dobras) do Vim permite recolher blocos de linhas em uma única linha visível na tela. Isso facilita a navegação e a leitura de arquivos extensos, especialmente código-fonte com muitas funções, classes ou seções.
Todos os comandos de folding começam com a tecla
z— que, segundo a documentação oficial do Vim, lembra a silhueta de um pedaço de papel dobrado.
O Vim oferece seis métodos para definir como as dobras são criadas. O método ativo é controlado pela opção foldmethod:
:set foldmethod? " Exibe o método atual
:set foldmethod=manual " Define o método como manual
| Método | Descrição |
|---|---|
manual |
Dobras são criadas manualmente pelo usuário com comandos. É o método padrão. |
indent |
Linhas com o mesmo nível de indentação formam dobras automaticamente. |
syntax |
As dobras seguem as regras de destaque de sintaxe da linguagem. |
expr |
As dobras são calculadas por uma expressão definida pelo usuário (foldexpr). |
marker |
Marcadores especiais inseridos no texto delimitam início e fim das dobras. |
diff |
Usado automaticamente no modo diff para ocultar linhas sem diferenças. |
Cada método é detalhado nas seções a seguir.
Com foldmethod=manual (padrão), o usuário tem controle total sobre quais linhas serão dobradas.
O operador zf (fold) segue a gramática do Vim: operador + movimento/objeto de texto.
Com movimentos:
zf3j " Dobra a linha atual + as 3 linhas abaixo (4 linhas no total)
zf2k " Dobra a linha atual + as 2 linhas acima
zfgg " Dobra do cursor até o início do arquivo
zfG " Dobra do cursor até o fim do arquivo
zf/padrão " Dobra do cursor até a primeira ocorrência de "padrão"
Com objetos de texto:
zfip " Dobra o parágrafo interno
zfa{ " Dobra o bloco delimitado por { }
zfa( " Dobra o bloco delimitado por ( )
zf% " Dobra até o delimitador correspondente (com cursor em {, (, [, etc.)
No modo Visual:
v (caractere), V (linha) ou Ctrl-v (bloco).zf para criar a dobra.No modo de Comando:
:5,20fold " Dobra as linhas 5 a 20
:5,20fo " Forma abreviada do comando acima
:,+4fold " Dobra da linha atual até 4 linhas abaixo
:.,$ fold " Dobra da linha atual até o final do arquivo
Dado o arquivo abaixo:
def saudacao():
nome = "Mundo"
print(f"Olá, {nome}!")
def despedida():
print("Até logo!")
Para dobrar toda a função saudacao():
def saudacao():.zf2j (dobra a linha atual + 2 abaixo).O resultado exibido será algo como:
+-- 3 lines: def saudacao():·······
Com foldmethod=indent, o Vim cria dobras automaticamente com base no nível de indentação de cada linha, comparando com o valor de shiftwidth.
:set foldmethod=indent
:set shiftwidth? " Verifica o valor atual (padrão: 2 ou 4, depende da config)
shiftwidth gera um nível de dobra.Com shiftwidth=4 e o seguinte arquivo:
class Animal:
def __init__(self, nome):
self.nome = nome
def falar(self):
print(f"{self.nome} faz um som")
class Cachorro(Animal):
def falar(self):
print(f"{self.nome} diz: Au au!")
Ao ativar :set foldmethod=indent, as funções são dobradas dentro das classes, e as classes podem ser dobradas como um todo.
Nota: Não é possível criar dobras manuais (
zf) quando o método éindent, pois isso conflitaria com a lógica de indentação.
Com foldmethod=syntax, as dobras são definidas pelas regras de destaque de sintaxe da linguagem em uso.
:set foldmethod=syntax
Requer que o arquivo de sintaxe da linguagem inclua definições de fold. Plugins como vim-polyglot oferecem suporte abrangente a diversas linguagens.
const nums = [
one,
two,
three,
four
]
Com foldmethod=syntax e o plugin adequado, o conteúdo do array será automaticamente dobrável.
Com foldmethod=expr, o nível de dobra de cada linha é calculado por uma expressão definida em foldexpr. É o método mais flexível.
:set foldmethod=expr
:set foldexpr=<expressão>
:set foldmethod=expr
:set foldexpr=strlen(substitute(substitute(getline(v:lnum),'\\s','','g'),'[^>].*','',''))
Isso dobra blocos de linhas que começam com >, agrupando os níveis de citação:
> texto citado
> texto citado
> > citação dupla
> > citação dupla
Com foldmethod=marker, as dobras são delimitadas por marcadores inseridos diretamente no texto. O padrão é {{{ para abrir e }}} para fechar.
:set foldmethod=marker
/* funcao_principal() {{{ */
int funcao_principal() {
/* retorno {{{ */
return 42;
/* }}} */
}
/* }}} */
Os marcadores podem incluir um número para indicar o nível da dobra:
/* Seção A {{{1 */
...
/* Subseção A.1 {{{2 */
...
/* }}}2 */
/* }}}1 */
As dobras ficam persistentes no arquivo, podendo ser compartilhadas entre diferentes usuários e sessões. A desvantagem é que os marcadores modificam o conteúdo do arquivo.
Para alterar os caracteres usados como marcador:
:set foldmarker=<<<,>>>
| Comando | Ação |
|---|---|
zo |
Abre a dobra (1 nível) |
zO |
Abre todas as dobras aninhadas |
zc |
Fecha a dobra (1 nível) |
zC |
Fecha todas as dobras aninhadas |
za |
Alterna (toggle) a dobra — abre se fechada, fecha se aberta |
zA |
Alterna todas as dobras aninhadas |
| Comando | Ação |
|---|---|
zr |
Abre 1 nível de dobras em todo o arquivo (reduz foldlevel) |
zR |
Abre todas as dobras do arquivo |
zm |
Fecha 1 nível de dobras em todo o arquivo (aumenta foldlevel) |
zM |
Fecha todas as dobras do arquivo |
zi |
Liga/desliga o folding globalmente (toggle foldenable) |
:10,50foldopen " Abre dobras no intervalo de linhas 10 a 50
:10,50foldopen! " Abre todas as dobras (recursivo) no intervalo
:10,50foldclose " Fecha dobras no intervalo
:10,50foldclose! " Fecha todas as dobras (recursivo) no intervalo
| Comando | Ação |
|---|---|
zj |
Move o cursor para a próxima dobra (aberta ou fechada) |
zk |
Move o cursor para a dobra anterior |
[z |
Move para o início da dobra aberta atual |
]z |
Move para o fim da dobra aberta atual |
| Comando | Ação |
|---|---|
zd |
Exclui a dobra sob o cursor (o texto não é afetado) |
zD |
Exclui recursivamente todas as dobras aninhadas sob o cursor |
zE |
Exclui todas as dobras do arquivo |
Atenção: O desfazer (
u) não restaura dobras excluídas. Não há como recuperá-las com undo.
O Vim trata uma seção dobrada como uma única linha para fins de edição:
dd sobre uma dobra fechada deleta todo o bloco de linhas contido na dobra.yy ou Y sobre uma dobra fechada copia (yank) todo o bloco.p ou P cola o bloco copiado/deletado na posição desejada.Isso permite mover ou duplicar seções inteiras de código de forma rápida.
Controla quais níveis de dobra ficam abertos ao carregar o arquivo.
:set foldlevel=0 " Todas as dobras fechadas
:set foldlevel=1 " Apenas dobras de nível 1 abertas
:set foldlevel=99 " Todas as dobras abertas
Exibe uma coluna lateral indicando visualmente os níveis de dobra:
:set foldcolumn=4 " Exibe coluna com largura 4 (máx: 12)
Os símbolos exibidos são:
- (hífen): linha dentro de uma dobra aberta.+ (mais): dobra fechada.| (barra): continuação de uma dobra aberta.Define o número mínimo de linhas para que uma dobra possa ser exibida como fechada:
:set foldminlines=3 " Dobras com menos de 3 linhas não serão recolhidas
Limita o nível máximo de aninhamento de dobras (para os métodos indent e syntax):
:set foldnestmax=3 " No máximo 3 níveis de dobras aninhadas
Habilita ou desabilita o folding:
:set foldenable " Ativa o folding
:set nofoldenable " Desativa (todas as dobras ficam abertas)
Define o texto exibido na linha da dobra recolhida. O padrão é a função foldtext(), mas pode ser personalizado:
:set foldtext=printf('+---%d\ linhas:\ %s',v:foldend-v:foldstart+1,getline(v:foldstart))
Dobras manuais são perdidas ao fechar o arquivo. Para preservá-las:
:mkview " Salva as dobras atuais (e outras configurações de visualização)
:loadview " Restaura as dobras salvas
Adicione o seguinte ao seu .vimrc para salvar e restaurar dobras automaticamente:
augroup SalvarDobras
autocmd!
autocmd BufWinLeave *.* mkview
autocmd BufWinEnter *.* silent! loadview
augroup END
Dica: Para evitar conflitos com mapeamentos locais de buffer, adicione também:
set viewoptions-=options
Com foldmethod=marker, as dobras ficam persistentes diretamente no texto do arquivo, pois os marcadores ({{{ / }}}) são salvos junto com o conteúdo.
Um ponto de partida para usar folding de forma produtiva:
" --- Folding ---
set foldmethod=indent " Dobras automáticas por indentação
set foldlevel=99 " Inicia com todas as dobras abertas
set foldcolumn=2 " Coluna lateral indicando dobras
set foldminlines=2 " Não dobra blocos com menos de 2 linhas
set foldnestmax=5 " Máximo de 5 níveis aninhados
" Persistência de dobras entre sessões
augroup SalvarDobras
autocmd!
autocmd BufWinLeave *.* mkview
autocmd BufWinEnter *.* silent! loadview
augroup END
set viewoptions-=options
" Toggle rápido com F9
nnoremap <F9> za
vnoremap <F9> zf
| Comando | Ação |
|---|---|
zf{movimento} |
Cria dobra usando um movimento |
{Visual}zf |
Cria dobra com a seleção visual |
:{range}fold |
Cria dobra pelo modo de Comando |
zd |
Exclui a dobra sob o cursor |
zD |
Exclui dobras recursivamente |
zE |
Exclui todas as dobras do arquivo |
| Comando | Ação |
|---|---|
zo |
Abre dobra (1 nível) |
zO |
Abre dobras aninhadas |
zc |
Fecha dobra (1 nível) |
zC |
Fecha dobras aninhadas |
za |
Toggle da dobra |
zA |
Toggle recursivo |
zr |
Abre 1 nível (arquivo inteiro) |
zR |
Abre tudo |
zm |
Fecha 1 nível (arquivo inteiro) |
zM |
Fecha tudo |
zi |
Toggle do foldenable |
| Comando | Ação |
|---|---|
zj |
Próxima dobra |
zk |
Dobra anterior |
[z |
Início da dobra atual |
]z |
Fim da dobra atual |
| Comando | Ação |
|---|---|
:mkview |
Salva dobras da sessão atual |
:loadview |
Restaura dobras salvas |