You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/copilot/copilot-edits.md
+95-46Lines changed: 95 additions & 46 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,8 +14,8 @@ Use Copilot Edits to start an AI-powered code editing session and iterate quickl
14
14
15
15
Copilot Edits can function in two modes:
16
16
17
-
-*Edit mode*: select which files to edit, provide the relevant context and prompt, and Copilot will suggest code edits.
18
-
-*Agent mode* (preview): let Copilot determine which files to edit and commands to run by using different tools. Copilot will autonomously iterate and resolve issues to achieve the desired outcome.
17
+
*[*Edit mode*](#use-edit-mode): select which files to edit, provide the relevant context and prompt, and Copilot will suggest code edits.
18
+
*[*Agent mode*](#use-agent-mode-preview) (preview): let Copilot determine which files to edit and which commands to run. Copilot will autonomously use different tools to iterate and resolve issues to achieve the desired outcome.
19
19
20
20
> [!TIP]
21
21
> If you don't yet have a Copilot subscription, you can use Copilot for free by signing up for the [Copilot Free plan](https://github.com/github-copilot/signup) and get a monthly limit of completions and chat interactions.
@@ -27,37 +27,87 @@ The following video demonstrates how to use Copilot Edits to extend a basic Expr
27
27
> [!NOTE]
28
28
> The Copilot Edits feature is currently in preview. You can provide feedback and report problems in [our issues](https://github.com/microsoft/vscode-copilot-release/issues).
29
29
30
-
## Get started with Copilot Edits
30
+
## Start a Copilot Edits session
31
31
32
-
You use the Copilot Edits view to start an edit session. Making code changes is often an iterative process and consists of multiple steps before you're satisfied with the result. An edit session consists of a sequence of requests (or turns) to Copilot Edits for making code edits. An edit session can go on for as long as you like, and you can send as many requests as you need to get the code to where you want it.
32
+
You access Copilot Edits through the Copilot Edits view, where you can enter natural language prompts for getting edit suggestions. By default, the Copilot Edits view is available in the Secondary Side Bar.
33
33
34
-
There are different ways to get started open the Copilot Edits view:
34
+
35
+
36
+
To access the Copilot Edits view:
35
37
36
38
* Use the `kb(workbench.action.chat.openEditSession)` keyboard shortcut
37
39
38
-
* Open the Copilot menu in the Command Center, and then select **Open Copilot Edits**
40
+
* Open the Copilot menu in the VS Code title bar, and then select **Open Copilot Edits**
39
41
40
-
42
+
41
43
42
44
* Use the **View: Toggle Copilot Edits** or **Copilot Edits: Focus on Copilot Edits View** command in the Command Palette (`kb(workbench.action.showCommands)`)
43
45
44
-
* Move a previous [chat conversation to Copilot](#send-a-chat-request-to-copilot-edits) Edits by selecting **Edit with Copilot** in the Chat view
46
+
Because making code changes can be an iterative process, an *edit session* in Copilot Edits can consist of a sequence of requests (or turns). You can send as many requests as you need to get the code to where you want it.
45
47
46
-
48
+
## Use edit mode
47
49
48
-
When you first open the Copilot Edits view or start a new edit session, a welcome message is presented.
50
+
In edit mode, you select which files to edit and provide the relevant context and prompt. Copilot will suggest code edits based on your prompt.
49
51
50
-
52
+
1. Open the Copilot Edits view
51
53
52
-
## Add files to the working set
54
+
1. Select **Edit** from the mode dropdown
53
55
54
-
The first step when you start an edit session is to add the relevant files you want to work with. These files are also known as the _working set_ for your edit session. Copilot Edits does not make changes outside the working set, except when suggesting to create a new file.
56
+
1. Use **Add Files**to add files to the _working set_
55
57
56
-
> [!IMPORTANT]
57
-
> The working set is currently limited to 10 files.
58
+
The working set indicates which files in the workspace can be edited by Copilot Edits.
59
+
60
+
1. Enter a prompt to request code edits. Be specific and precise about the changes you want, and decompose larger tasks into smaller tasks.
61
+
62
+
Copilot Edits streams the edits in the editor. In the working set, edited files are marked in bold.
63
+
64
+
> [!TIP]
65
+
> Add more specific context by using chat variables like `#file` or `#sym` to reference files or symbols. Use `#codebase` to let Copilot collect relevant context from your entire workspace.
66
+
67
+
1. Review the suggested edits and accept or discard the suggested edits
68
+
69
+
1. Iterate on the code changes
70
+
71
+
If you're not entirely happy with the edits, you can ask follow-up questions, such as "don't include the phone number", or "use jest instead of vitest". Or you can incrementally edit your code further. For example, when building a web app, use a series of prompts such as "add a navigation bar", "add a theme switcher", "store order items in JSON format in MongoDB".
72
+
73
+
## Use agent mode (preview)
74
+
75
+
In agent mode, Copilot Edits operates in a more autonomous and dynamic manner to achieve the desired outcome:
76
+
77
+
* Creates a plan of action and decomposes the request into smaller tasks.
78
+
* Determines the relevant context and files to edit autonomously.
79
+
* Offers both code changes and terminal commands to complete the task. For example, Copilot might compile code, install packages, run tests, and more.
80
+
* Monitors correctness of code edits and terminal command output and iterates to remediate issues.
81
+
82
+
Copilot Edits agent mode uses a set of _tools_ to accomplish these tasks. For example, to determine which files to edit, gather project context, run terminal commands, read terminal output, and more.
83
+
84
+
To enable agent mode in Copilot Edits, set the `setting(github.copilot.chat.agent.enabled)` setting to `true`.
85
+
86
+
1. Open the Copilot Edits view
87
+
88
+
1. Select **Agent** from the mode dropdown
89
+
90
+
1. Enter a prompt to request code edits.
91
+
92
+
In agent mode, Copilot Edits will determine the relevant context and files to edit autonomously.
93
+
94
+
Copilot Edits streams the edits in the editor and updates the working set. In addition, Copilot can suggest terminal commands to run.
95
+
96
+
1. Review the suggested code edits, and confirm if Copilot can run the proposed terminal commands
97
+
98
+
You have to confirm the commands to run because they might result in changes to your project.
99
+
100
+
1. Copilot Edits detects issues and problems in code edits and terminal commands, and will iterate and perform additional actions to resolve them.
101
+
102
+
## Manage the working set
103
+
104
+
The _working set_ is the set of files that you want Copilot Edits to work on for your edit session. Copilot Edits does not make changes outside the working set, except when suggesting to create a new file. When you use agent mode, Copilot autonomously determines which files to edit and adds them to the working set.
58
105
59
106
60
107
108
+
> [!IMPORTANT]
109
+
> The working set is currently limited to 10 files.
110
+
61
111
Copilot Edits automatically adds the active editor to the working set. If you have multiple [editor groups](/docs/getstarted/userinterface.md#editor-groups), the active editor for each group is added to the working set. To add all open editors, select **Add Files...**, and then choose **Open Editors** from the Files Quick Pick.
62
112
63
113
You have many options to add files to the working set:
@@ -81,26 +131,31 @@ You have many options to add files to the working set:
81
131
82
132
If you don't want to see these suggestions, you can disable them with the `setting(github.copilot.chat.edits.suggestRelatedFilesFromGitHistory)` setting.
83
133
84
-
To further help Copilot Edits provide better code suggestions, you can also add relevant context to your prompt, such as `#selection` or `#terminalSelection`. Reference context by typing the `#` symbol, or by using the <iclass="codicon codicon-attach"></i> icon (`kb(workbench.action.chat.attachContext)`).
134
+
To further help Copilot Edits provide better code suggestions, you can also add relevant context to your prompt, such as `#selection` or `#terminalSelection`. Use `#codebase` to let Copilot collect relevant context from your entire workspace. Type the `#` symbol or use the <iclass="codicon codicon-attach"></i> icon (`kb(workbench.action.chat.attachContext)`) to add context to your prompt.
85
135
86
-
You can also add file or symbol references in your prompt by using `#` as an IntelliSense trigger for file or symbol suggestions. If Copilot decides to make changes to the files you mentioned in your prompt, they are added automatically to your working set.
136
+
You can also add specific file or symbol references in your prompt by using `#` as an IntelliSense trigger for file or symbol suggestions. If Copilot decides to make changes to the files you mentioned in your prompt, they are added automatically to your working set.
87
137
88
-
## Request code edits
138
+
When Copilot Edits generates edits for your project, it visually indicates which files in the working set are edited. Select a file in the working set to open it and view the proposed edits in the editor.
89
139
90
-
After you've added the relevant files, enter a chat prompt using natural language about the specific edit you want to make. For example, "Add a contact page that shows email, telephone and postal address", or "convert all unit tests to vitest".
140
+
91
141
92
-
> [!TIP]
93
-
> Be specific and precise about the changes you want Copilot Edits to make. If you have a larger task, decompose it in smaller tasks and iterate often to steer Copilot in the right direction.
142
+
## Accept or discard edits
94
143
95
-
In response to your prompt, Copilot Edits lists the files that are edited and provides a short description of the change. In addition, the suggested editsare applied to your code. As the edits stream in, Copilot Edits opens editor tabs for the affected files.
144
+
Copilot Edits gives you a code review flow where you can accept or discard each of the AI-generated edits. When you accept the AI-generated edits, the file changes are confirmed in the working set. If you discard the edits, the files are restored to their previously accepted state.
96
145
97
-
<videosrc="images/copilot-edits/copilot-edits-streaming-edits.mp4"title="Screen capture showing the edits from Copilot Edits stream into the open editor."loopcontrolsmuted></video>
146
+
Navigate between the different edits in your project by using the editor overlay controls. Use the **Accept** and **Discard** controls to accept or reject all changes for a given file.
98
147
99
-
When Copilot Edits generates edits for your project, it visually indicates which files in the working set are edited. Select a file in the working set to open it and view the proposed edits in the editor.
148
+
100
149
101
-
150
+
For more fine-grained control over which edit you want to accept or reject within a file, hover over the code edit and select the **Undo** control to reject a change.
102
151
103
-
You can further iterate and send more requests in your edit session. If you're not entirely happy with the edits, you can ask follow-up question, such as "don't include the phone number", or "use jest instead of vitest". Or you can incrementally edit your code further. For example, when building a web app, use a series of prompts such as "add a navigation bar", "add a theme switcher", "store order items in JSON format in MongoDB".
152
+
Alternatively, you can also accept or discard the changes from the working set in the Copilot Edits view:
153
+
154
+
* Select **Accept** (`kb(chatEditing.acceptAllFiles)`) or **Discard** (`kb(chatEditing.discardAllFiles)`) in the working set title bar to accept or discard all edits in the working set
155
+
156
+
* Select the **Accept** or **Discard** icon on an individual working set file to apply the action to that specific file
157
+
158
+
104
159
105
160
## Save generated edits
106
161
@@ -113,24 +168,6 @@ When you save a file that contains AI-generated changes, a confirmation dialog i
113
168
> [!NOTE]
114
169
> Saving the files doesn't mean that you automatically accept the changes. After saving the files, you can still accept or discard the generated edits.
115
170
116
-
## Accept or discard edits
117
-
118
-
Copilot Edits gives you a code review flow, where you can accept or discard each of the AI-generated edits. When you accept the AI-generated edits, the file changes are confirmed in the working set. If you discard the edits, the files are restored to their previously accepted state.
119
-
120
-
You can navigate between the different edits across your project by using the editor overlay controls. Use the **Accept** and **Discard** controls to accept or reject all changes for a given file.
121
-
122
-
123
-
124
-
For more fine-grained control over which edit you want to accept or reject within a file, hover over the code edit and select the **Undo** control to reject a change.
125
-
126
-
Alternatively, you can also accept or discard the changes from the working set:
127
-
128
-
* Select **Accept** (`kb(chatEditing.acceptAllFiles)`) or **Discard** (`kb(chatEditing.discardAllFiles)`) in the working set title bar to accept or discard all edits in the working set
129
-
130
-
* Select the **Accept** or **Discard** icon on an individual file in the working set to limit the action to that specific file
131
-
132
-
133
-
134
171
## Undo edits
135
172
136
173
As you're sending requests to make edits to your code, you might want to roll back some of these changes, for example because you want to use another implementation strategy.
@@ -148,11 +185,11 @@ You can also use the **Undo Edits (Delete)** control when hovering over a reques
148
185
149
186
## Send a chat request to Copilot Edits
150
187
151
-
Copilot Chat is great for asking questions and exploring ideas and code suggestions about your project or technology topics in general. Once you're ready to apply the suggested code changes, you can transfer your chat session over to Copilot Edits. The advantage of doing this is that you can let Copilot Edits apply all the changes across your project, instead of having to apply each code block individually from the Chat view.
188
+
Copilot Chat is great for asking questions and exploring ideas about your project or technology topics in general. Rather than applying each code block from Copilot Chat to your code, you can transfer the chat session to Copilot Edits. Copilot Edits is optimized for code editing and can apply code suggestions directly in your code, across multiple files simultaneously.
152
189
153
190
In the Chat view, select the **Edit with Copilot** button at the bottom of the chat conversation to apply the suggested code changes with Copilot Edits. If you have multiple chat requests in the chat session, you can select which requests you want to transfer to Copilot Edits.
154
191
155
-
192
+
156
193
157
194
After moving a chat request to Copilot Edits, the chat request is removed from the chat conversation in the Chat view.
158
195
@@ -163,6 +200,8 @@ The following list contains the settings related to Copilot Edits. You can confi
163
200
*`setting(chat.editing.confirmEditRequestRemoval)` - ask for confirmation before undoing an edit (default: `true`)
164
201
*`setting(chat.editing.confirmEditRequestRetry)` - ask for confirmation before performing a redo of the last edit (default: `true`)
165
202
*`setting(chat.editing.alwaysSaveWithGeneratedChanges)` - automatically save generated changes from Copilot Edits to disk (default: `false`)
203
+
*`setting(github.copilot.chat.agent.enabled)` <iclass="codicon codicon-beaker"></i> - enable or disable agent mode in Copilot Edits (default: `false`)
204
+
*`setting(chat.agent.maxRequests)` - maximum number of requests that Copilot Edits can make in agent mode (default: 15)
166
205
167
206
## Keyboard shortcuts
168
207
@@ -222,6 +261,16 @@ The following table shows a comparison of the capabilities of each experience.
222
261
223
262
You can drag and drop the Copilot Edits view into the Activity Bar to show it in the Primary Side Bar. You can also move it to the Secondary Side Bar. Learn more about [custom layouts](/docs/editor/custom-layout.md#workbench) in VS Code.
224
263
264
+
### Why would I use edit mode instead of agent mode?
265
+
266
+
Consider the following criteria
267
+
268
+
***Edit scope**: you might use edit mode if your request involves only code edits and you know the precise scope and working set for the changes.
269
+
***Preview feature**: agent mode is still in preview and might not work for all scenarios.
270
+
***Response time**: agent mode involves more steps to process a request, so it might take longer to get a response. For example, to determine the relevant context and files to edit, determine the plan of action, and more.
271
+
***Request quota**: in agent mode, depending on the complexity of the task, one prompt might result in many requests to the backend.
272
+
273
+
225
274
## Related content
226
275
227
276
*[Get a quick overview of the Copilot features in VS Code](/docs/copilot/copilot-vscode-features.md)
0 commit comments