From f1a9fdddab79f4d4404b1a7a8e69459fe1cdb9b6 Mon Sep 17 00:00:00 2001 From: Nate Butler Date: Tue, 25 Mar 2025 08:22:01 -0400 Subject: [PATCH] docs: Improve Git page (#26566) Release Notes: - N/A --------- Co-authored-by: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Co-authored-by: Danilo Leal --- .../src/templates/keybinding.rs | 5 + docs/src/git.md | 104 +++++++++++++----- docs/theme/css/general.css | 21 ++-- 3 files changed, 93 insertions(+), 37 deletions(-) diff --git a/crates/docs_preprocessor/src/templates/keybinding.rs b/crates/docs_preprocessor/src/templates/keybinding.rs index 518bea2358b4c88ce1f0fd78ffd205ff7b85b157..6523502e54992527be7f316b235ba379e01c3677 100644 --- a/crates/docs_preprocessor/src/templates/keybinding.rs +++ b/crates/docs_preprocessor/src/templates/keybinding.rs @@ -31,6 +31,11 @@ impl Template for KeybindingTemplate { let action = args.get("action").map(String::as_str).unwrap_or(""); let macos_binding = context.find_binding("macos", action).unwrap_or_default(); let linux_binding = context.find_binding("linux", action).unwrap_or_default(); + + if macos_binding.is_empty() && linux_binding.is_empty() { + return "
No default binding
".to_string(); + } + format!("{macos_binding}|{linux_binding}") } } diff --git a/docs/src/git.md b/docs/src/git.md index 67c31d9694c880c4bc9c1226495f11d45ccf38ef..a976c0739ebb908d6b250989bcd38de2abe81a42 100644 --- a/docs/src/git.md +++ b/docs/src/git.md @@ -1,65 +1,90 @@ # Git -Zed currently offers a set of fundamental Git features, with support for more advanced ones—like conflict resolution tools, line by line staging, and more—coming in the future. +Zed currently offers a set of fundamental Git features, with support coming in the future for more advanced ones, like conflict resolution tools, line by line staging, and more. Here's an overview of all currently supported features: - Committing - Staging, pushing, pulling, and fetching -- Changeset diff view +- Project Diff: A multibuffer view of all changes - Diff indicators in buffers and editor scrollbars - Inline diff toggle and reverts in the editor for unstaged changes -- Git status in the project panel +- Git status in the Project Panel - Branch creating and switching - Git blame viewing ## Git Panel The Git Panel gives you a birds-eye view of the state of your working tree and of Git's staging area. -You can see at a glance which files have changed, and which are staged for commit. -Zed monitors your repository so that changes you make on the command line are instantly reflected. - +You can open the Git Panel using {#action git_panel::ToggleFocus}, or by clicking the Git icon in the status bar. -### Fetch, push, and pull +In the panel you can see the state of your project at a glance—which repository and branch are active, what files have changed and the current staging state of each file. -You can fetch, push, or pull from your Git repository in Zed via the buttons available on the Git Panel or via the Command Palette by looking at the respective actions: `git fetch`, `git push`, and `git pull`. +Zed monitors your repository so that changes you make on the command line are instantly reflected. -## Diff View +## Project Diff -You can see all of the changes captured by Git in Zed by opening the Diff View, accessible via the `git: diff` action in the Command Palette or the Git Panel. +You can see all of the changes captured by Git in Zed by opening the Project Diff ({#kb git::Diff}), accessible via the {#action git::Diff} action in the Command Palette or the Git Panel. -All of the changes displayed in the Diff View behave exactly the same as any other multibuffer: they are all editable excerpts of files. +All of the changes displayed in the Project Diff behave exactly the same as any other multibuffer: they are all editable excerpts of files. You can stage or unstage each hunk as well as a whole file by hitting the buttons on the tab bar or their corresponding keybindings. - + -## Git with AI +## Fetch, push, and pull -Zed currently supports LLM-powered commit message generation. This can be done when focused on the commit message editor in the Git Panel. +Fetch, push, or pull from your Git repository in Zed via the buttons available on the Git Panel or via the Command Palette by looking at the respective actions: {#action git::Fetch}, {#action git::Push}, and {#action git::Pull}. -> Note that you need to have an LLM provider configured. +## Staging Workflow - +Zed has two primary staging workflows, using either the Project Diff or the panel directly. -More advanced AI integration with Git features may come in the future. +### Using the Project Diff + +In the Project Diff view, you can focus on each hunk and stage them individually by clicking on the tab bar buttons or via the keybindings {#action git::StageAndNext} ({#kb git::StageAndNext}). + +Similarly, stage all hunks at the same time with the {#action git::StageAll} ({#kb git::StageAll}) keybinding and then immediately commit with {#action git::Commit} ({#kb git::Commit}). + +### Using the Git Panel + +From the panel, you can simply type a commit message and hit the commit button, or {#action git::Commit}. This will automatically stage all tracked files (indicated by a `[·]` in the entry's checkbox) and commit them. + + + +Entries can be staged using each individual entry's checkbox. All changes can be staged using the button at the top of the panel, or {#action git::StageAll}. + + - +1. The first one is available right at the bottom of the Git Panel. Hitting {#kb git::Commit} immediately commits all of your staged changes. +2. The second is available via the action {#action git::ExpandCommitEditor} or via hitting the {#kb git::ExpandCommitEditor} while focused in the Git Panel commit textarea. + +### Undoing a Commit + +As soon as you commit in Zed, in the Git Panel, you'll see a bar right under the commit textarea, which will show the recently submitted commit. +In there, you can reach for the "Uncommit" button, which performs the `git reset HEADˆ--soft` command. + +## AI Support in Git + +Zed currently supports LLM-powered commit message generation. +You can ask AI to generate a commit message by focusing on the message editor within the Git Panel and either clicking on the pencil icon in the bottom left, or reaching for the {#action git::GenerateCommitMessage} ({#kb git::GenerateCommitMessage}) keybinding. + +> Note that you need to have an LLM provider configured. Visit [the Assistant configuration page](/assistant/configuration.md) to learn how to do so. + + + +More advanced AI integration with Git features may come in the future. ## Git Integrations -Zed integrates with popular Git hosting services to ensure that Git commit hashes and references to Issues / Pull Requests / Merge Requests become clickable links. +Zed integrates with popular Git hosting services to ensure that Git commit hashes and references to Issues, Pull Requests, and Merge Requests become clickable links. -Zed currently support links to the hosted versions of +Zed currently supports links to the hosted versions of [GitHub](https://github.com), [GitLab](https://gitlab.com), [Bitbucket](https://bitbucket.org), @@ -72,3 +97,30 @@ Trigger this action via the [Command Palette](./getting-started.md#command-palet by creating a [custom key bindings](key-bindings.md#custom-key-bindings) to the `editor::CopyPermalinkToLine` or `editor::OpenPermalinkToLine` actions or by simply right clicking and selecting `Copy Permalink` with line(s) selected in your editor. + +## Action Reference + +| Action | Keybinding | +| -------------------------------------- | ---------------------------------- | +| {#action git::Add} | {#kb git::Add} | +| {#action git::StageAll} | {#kb git::StageAll} | +| {#action git::UnstageAll} | {#kb git::UnstageAll} | +| {#action git::ToggleStaged} | {#kb git::ToggleStaged} | +| {#action git::StageAndNext} | {#kb git::StageAndNext} | +| {#action git::UnstageAndNext} | {#kb git::UnstageAndNext} | +| {#action git::Commit} | {#kb git::Commit} | +| {#action git::ExpandCommitEditor} | {#kb git::ExpandCommitEditor} | +| {#action git::Push} | {#kb git::Push} | +| {#action git::ForcePush} | {#kb git::ForcePush} | +| {#action git::Pull} | {#kb git::Pull} | +| {#action git::Fetch} | {#kb git::Fetch} | +| {#action git::Diff} | {#kb git::Diff} | +| {#action git::Restore} | {#kb git::Restore} | +| {#action git::RestoreFile} | {#kb git::RestoreFile} | +| {#action git::Branch} | {#kb git::Branch} | +| {#action git::Switch} | {#kb git::Switch} | +| {#action git::CheckoutBranch} | {#kb git::CheckoutBranch} | +| {#action editor::ToggleGitBlame} | {#kb editor::ToggleGitBlame} | +| {#action editor::ToggleGitBlameInline} | {#kb editor::ToggleGitBlameInline} | + +> Not all actions have default keybindings, but can be bound by [customizing your keymap](/key-bindings.md#user-keymaps). diff --git a/docs/theme/css/general.css b/docs/theme/css/general.css index 4f8331bd6c26a12a066823cbf059e7316d6c7bf7..b03e87ff7023784fe125c748533ae6cb755af588 100644 --- a/docs/theme/css/general.css +++ b/docs/theme/css/general.css @@ -168,12 +168,12 @@ h6:target::before { margin: 0; } .content ol { + marker: none; line-height: 1.8; - + padding-left: 2em; ::marker { font-size: 1.4rem; } - li { padding-left: 0; } @@ -182,9 +182,6 @@ h6:target::before { line-height: 1.8; padding-left: 1.8em; } -.content li { - padding-left: 0.5em; -} .content a { text-decoration: underline; text-decoration-color: var(--link-line-decoration); @@ -261,12 +258,13 @@ blockquote > p { } blockquote:before { + --size: 1.4rem; position: absolute; content: "ⓘ"; margin: 0.3rem 0; - width: 1.6rem; - height: 1.6rem; - font-size: 1.6rem; + width: var(--size); + height: var(--size); + font-size: var(--size); font-weight: bold; color: var(--icons); display: flex; @@ -294,12 +292,13 @@ blockquote .warning:before { } .warning:before { + --size: 1.4rem; position: absolute; content: "ⓘ"; margin: 0.3rem 0; - width: 1.6rem; - height: 1.6rem; - font-size: 1.6rem; + width: var(--size); + height: var(--size); + font-size: var(--size); font-weight: bold; color: var(--warning-icon); display: flex;