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
`git-draft` is a git-centric way to edit code with AI.
30
30
31
+
Its workhorse command is `git draft --new` (and its shorthand, `git draft`) which suggests code changes using LLMs.
32
+
Prompts can be specified inline or via customizable templates.
33
+
Prompt templates can get augmented with information about the files in the repository, and give the LLM access to tools for reading and writing files.
34
+
Once the response has been received and changes applied, a commit is created in a dedicated draft branch.
35
+
The `--new` step can be repeated as many times as needed.
36
+
37
+
Once satisfied with the changes, run `git draft --quit` to return to the original branch.
38
+
This keeps the working directory's current state.
39
+
31
40
32
41
== Options
33
42
@@ -39,7 +48,8 @@ This option can be repeated up to 3 times, with the following behavior at each l
39
48
+
40
49
* `-a`: Merge changes conservatively, flagging any conflicts for manual user resolution.
41
50
* `-aa`: Merge changes aggressively, resolving all conflicts in favor of the generated change.
42
-
* `-aaa`: Merge changes aggressively (same as `-aa`) then run `--quit` automatically.
51
+
* `-aaa`: Merge changes aggressively (same as `-aa`) then run `--quit`.
52
+
43
53
+
44
54
By default, changes are not merged - keeping the working directory untouched.
45
55
A different default can be set in the configuration file.
@@ -53,29 +63,33 @@ Defaults to the first bot defined in the configuration.
53
63
-e::
54
64
--edit::
55
65
Enable interactive editing of draft prompts and templates.
56
-
See `--new` and `--templates` for details.
66
+
When used with `--new`, it opens an editor with the rendered prompt.
67
+
The updated prompt will be used by the bot after the editor exits.
68
+
When used with `--templates`, it opens an editor with the selected template.
69
+
The template will be created automatically if it did not already exist.
57
70
58
71
-h::
59
72
--help::
60
73
Show help message and exit.
61
74
62
75
-j::
63
76
--json::
64
-
Use JSON output.
77
+
Use JSON output.
65
78
66
79
--log-path::
67
-
Show log path and exit.
80
+
Show log path and exit.
68
81
69
82
-N::
70
83
--new::
71
-
Create an AI-generated draft.
72
-
If the `--edit` option is set, an interactive editor will be opened with the rendered prompt to allow modification before it is forwarded to the bot.
84
+
Generate a draft commit for a given prompt.
85
+
`-` can be specified instead of a template name to read the prompt from stdin.
86
+
Otherwise if no template is specified and stdin is a TTY, `$EDITOR` will be opened to enter the prompt.
73
87
74
88
-Q::
75
89
--quit::
76
90
Go back to the draft's origin branch, keeping the working directory's current state.
77
91
This will delete the draft branch and its upstream.
78
-
Generated commits remain available via `ref/drafts`.
92
+
Generated commits and the draft branch's final state remain available via `ref/drafts`.
79
93
80
94
--root::
81
95
Repository search root.
@@ -84,77 +98,75 @@ Defaults to the current working directory.
84
98
-T::
85
99
--templates::
86
100
With no argument, lists available templates.
87
-
With an template name argument, displays the corresponding template's contents or, if the `--edit` option is set, opens an interactive editor.
101
+
With an template name argument, displays the corresponding template's contents or, if the `--edit` option is set, opens an interactive editor with its contents.
88
102
89
103
--version::
90
104
Show version and exit.
91
105
92
106
93
107
== Examples
94
108
95
-
The workhorse command is `git draft --new` which leverages AI to edit code.
96
-
A prompt can be specified as standard input, for example `echo "Add a test for compute_offset in chart.py" | git draft --generate`.
97
-
If no prompt is specified and stdin is a TTY, `$EDITOR` will be opened to enter the prompt.
98
-
99
-
By default, the prompt gets augmented with information about the files in the repository, and give the AI access to tools for reading and writing files.
100
-
Once the response has been received and changes applied, a commit is created in a separate branch.
109
+
=== Commit graphs
101
110
102
-
The `--generate` step can be repeated as many times as needed.
103
-
Once you are satisfied with the changes, run `git draft --finalize` to apply them.
104
-
This will check out the branch used when creating the draft, adding the final state of the draft to the worktree.
105
-
Note that you can come back to an existing draft anytime (by checking its branch out), but you will not be able to apply it if its origin branch has moved since the draft was created.
111
+
This section shows representative commit histories in draft branches for various scenarios.
106
112
113
+
When the working directory is clean, a single commit is created and set as the draft branch's upstream (suffixed with `+`).
107
114
108
-
o Foo (main)
109
-
o Sync (drafts/123/pub)
115
+
[source]
116
+
----
117
+
o <some commit> (main, draft/123)
118
+
o draft! prompt: <prompt> (draft/123+, refs/drafts/123/1)
119
+
----
110
120
111
-
# After generate without accept
112
-
o Foo (main)
113
-
o Sync (drafts/123)
114
-
o draft! <prompt> (drafts/123+, refs/drafts/123/1)
121
+
If the working directory is dirty, a sync commit is added to identify the LLM-generated changes.
115
122
116
-
# After generate with accept
117
-
o Foo (main)
118
-
o Sync
119
-
|\
120
-
| o draft! prompt: <prompt> (refs/drafts/123/1)
121
-
o | Sync
122
-
|/
123
-
o Merge (drafts/123/pub)
123
+
[source]
124
+
----
125
+
o <some commit> (main, draft/123)
126
+
o draft! sync(prompt)
127
+
o draft! prompt: <prompt> (draft/123+, refs/drafts/123/1)
128
+
----
124
129
130
+
If merging is enabled, it have both the LLM-generated changes and manual edits as parents.
125
131
126
-
o Foo (main)
127
-
o draft! sync
128
-
|\
129
-
| o draft! prompt: <prompt> (drafts/123+, refs/drafts/123/1)
130
-
o Something
131
-
o Also something (drafts/123)
132
-
133
-
134
-
o Foo (main)
135
-
o draft! sync
132
+
[source]
133
+
----
134
+
o <some commit> (main)
136
135
|\
136
+
| o draft! sync(prompt)
137
+
o | draft! sync(merge)
137
138
| o draft! prompt: <prompt> (refs/drafts/123/1)
138
-
o Something
139
-
o Also something (drafts/123/pub)
140
-
o draft! prompt: <prompt> (drafts/123+, refs/drafts/123/2)
139
+
|/
140
+
o Merge (draft/123, draft/123/+)
141
+
----
141
142
143
+
Otherwise, the user is free to incorporate the changes as needed.
144
+
Note that the steps above can be repeated arbitrarily many times within a given draft branch, both with and without automatic merging.
142
145
143
-
o Foo (main)
144
-
o draft! sync (drafts/123/pub)
146
+
[source]
147
+
----
148
+
o <some commit> (main)
145
149
|\
146
-
| o draft! prompt: <prompt> (refs/drafts/123/1)
147
-
\
148
-
o draft! prompt: <prompt> (drafts/123+, refs/drafts/123/2)
149
-
150
-
o Foo (main)
151
-
o draft! sync (drafts/123/pub)
150
+
| o draft! prompt: <prompt1> (refs/drafts/123/1)
151
+
o draft! sync(prompt)
152
+
o draft! prompt: <prompt2> (refs/drafts/123/2)
153
+
o <a manual commit> (draft/123)
154
+
o draft! prompt: <prompt3> (draft/123+, refs/drafts/123/3)
155
+
----
156
+
157
+
Sync commits will be reused if no new changes were added.
158
+
This can be useful when iterating on a prompt, and discarding results from prior iterations.
159
+
160
+
[source]
161
+
----
162
+
o <some commit> (main)
163
+
o draft! sync(prompt)
152
164
|\
153
-
| o draft! prompt: <prompt> (refs/drafts/123/1)
154
-
|/
155
-
o draft! sync
156
-
\
157
-
o draft! prompt: <prompt> (drafts/123+, refs/drafts/123/2)
0 commit comments