# 🎨 GUIA DE INTERFACE VISUAL GIT (VSCODE) & COMANDOS EQUIVALENTES

Este guia reúne todas as explicações das funções visuais do painel **Source Control** do VSCode, mapeando-as aos seus comandos equivalentes no terminal Git e indicando as melhores práticas de uso na nossa arquitetura GitOps.

---

## 🗺️ 1. Mapeamento de Funções Rápidas (Principais)

| Botão Visual no VSCode | Comando no Terminal | O que faz na prática? |
| :--- | :--- | :--- |
| **📥 Pull** | `git pull` | Baixa as últimas alterações do Gitea (VPS 3) e as junta diretamente ao seu código local. |
| **📤 Push** | `git push` | Envia as alterações que você salvou (comitou) localmente para o repositório central no Gitea. |
| **👥 Clone** | `git clone <url>` | Baixa um repositório inteiro pela primeira vez do Gitea para a sua máquina de desenvolvimento. |
| **🔄 Checkout to...** | `git checkout <branch>` | Alterna entre ramificações de desenvolvimento (ex: mudar de `dev` para `main`) ou cria novas branches. |
| **📡 Fetch** | `git fetch` | Consulta o Gitea para ver se há novidades no histórico, mas **não altera** o seu código atual. |

---

## 🛠️ 2. Explicação dos Submenus Avançados

### 💾 Commit (Submenu de Confirmação)
*   **O que faz**: Agrupa as suas alterações de código locais preparadas e cria um ponto na história (um "commit") com uma mensagem descritiva.
*   **Equivalente no terminal**: `git commit -m "sua mensagem"`
*   **Dica no VSCode**: Use o campo de texto superior para escrever a mensagem e clique no botão azul **Commit** para fazer tudo de uma vez.

### 🔀 Changes (Submenu de Alterações)
*   **O que faz**: Permite preparar os arquivos que farão parte do próximo commit.
    *   Clicar no ícone de `+` ao lado do arquivo faz um `git add` (prepara o arquivo).
    *   Clicar na seta curvada descarta as alterações locais daquele arquivo, voltando ele ao estado anterior.

### 🔄 Pull, Push (Submenu de Sincronização Avançada)
*   **O que faz**: Reúne ações combinadas como **Sync** (que executa sequencialmente um `pull` e depois um `push` para manter tudo perfeitamente sincronizado).

### 🌿 Branch (Submenu de Ramos)
*   **O que faz**: Permite gerenciar as suas ramificações de código. Você pode mesclar duas branches (fazer um `git merge`) ou deletar branches locais que já foram concluídas.

### 📦 Stash (Submenu de Gaveta Temporária)
*   **O que faz**: Se você está no meio de um desenvolvimento complexo, mas precisa trocar de branch imediatamente para corrigir um bug urgente, você usa o **Stash**. Ele guarda suas alterações não salvas em uma "gaveta temporária", limpa sua tela e, quando você voltar, basta dar um **Stash Pop** para recuperar seu trabalho exatamente de onde parou.
*   **Equivalente no terminal**: `git stash` e `git stash pop`

### 🏷️ Tags (Submenu de Etiquetas)
*   **O que faz**: Permite marcar versões específicas do seu sistema (ex: etiqueta `v1.0.0` ou `v2.4.1`) para identificar marcos de lançamentos oficiais.

---

## 🚀 3. Fluxo de Trabalho Diário Recomendado (GitOps)

Para trabalhar de forma ágil na **VPS 4 (Dev)** integrada à **VPS 1 (Produção)** através do Webhook, utilize este fluxo visual direto no VSCode:

```mermaid
graph LR
    A[1. Codificar] --> B[2. Preparar +]
    B --> C[3. Commit 💾]
    C --> D[4. Sync / Push 📤]
    D -->|Gitea Webhook| E[5. Deploy Automático VPS 1 ⚡]
```

1.  **Codifique**: Faça as alterações necessárias na VPS 4.
2.  **Prepare**: No painel de controle de versão (Source Control), clique no botão de `+` ao lado de cada arquivo modificado para adicioná-los.
3.  **Comite**: Digite uma mensagem clara no campo de texto (ex: `feat: adicionado controle de rotas`) e clique no botão azul **Commit**.
4.  **Sincronize**: Clique no botão **Sync Changes** (ou no ícone de nuvem no rodapé esquerdo do VSCode).
5.  **Acompanhe**: O Gitea disparará o Webhook que compilará o código na VPS 4 e enviará para a VPS 1 de forma automática em segundo plano.

---

## 📊 4. Comparativo: Quando usar a Tela do VSCode vs. Terminal?

> [!TIP]
> A interface do VSCode é amplamente recomendada para **95% do seu fluxo diário** devido ao seu apelo visual e proteção contra erros de digitação.

| Tarefa | 🖥️ Interface Visual (VSCode) | 📟 Terminal |
| :--- | :--- | :--- |
| **Saber o que mudou no código** | **Excelente**: Mostra as diferenças de linhas lado a lado de forma colorida. | Ruim: Difícil de ler no console. |
| **Add, Commit, Pull e Push** | **Excelente**: Reduz o trabalho a 3 cliques simples de mouse. | Bom: Rápido se você tiver agilidade de digitação. |
| **Resolver Conflitos de Merge** | **Excelente**: O editor de conflitos destaca em cores o seu código e o do servidor, bastando clicar no botão para escolher qual manter. | Péssimo: Gera marcadores confusos no arquivo (`<<<<<<< HEAD`). |
| **Ações de Reparo** (Ex: redefinir histórico) | Não recomendado. | **Excelente**: Comandos como `git reset --hard` ou rebase interativo exigem a precisão do terminal. |

---

> [!IMPORTANT]
> **Dica Diagnóstica (Show Git Output)**:
> Se o sincronismo visual do VSCode travar ou falhar por causa da VPN, clique em **Show Git Output**. O painel mostrará o log do terminal do Git rodando em segundo plano, identificando rapidamente se o erro é de permissão de chave SSH ou de conexão de rede.