Skip to content

Commit fe769bb

Browse files
alokedesaialokedesai
authored
Merge pull request #23 from warpdotdev/aloke/add_documentation
Add documentation to workflows repo
2 parents 0d4bac4 + bfa0677 commit fe769bb

2 files changed

Lines changed: 88 additions & 84 deletions

File tree

‎FORMAT.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Workflows File Format
2+
3+
The workflow file format is a [yaml](https://yaml.org/) file and must have either a `.yml ` or `yaml` extension. If you're new to YAML and want to learn more, see "[Learn YAML in Y minutes](https://learnxinyminutes.com/docs/yaml/)."
4+
5+
6+
_Compatibility Note_: Warp is still in Beta and this format is subject to change.
7+
8+
### `name`
9+
---
10+
The name of the Workflow. Required.
11+
12+
### `command`
13+
----
14+
The command that is executed when the Workflow is selected. Required.
15+
16+
### `tags`
17+
----
18+
An array of tags that are useful to categorize the Workflow. Optional.
19+
20+
```yaml
21+
tags: ["git", "GitHub"]
22+
```
23+
24+
### `description`
25+
----
26+
The description of the Workflow and what it does. Optional.
27+
28+
### `source_url`
29+
----
30+
The URL from where the Workflow was originally generated from. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional.
31+
32+
33+
### `author`
34+
----
35+
The original author of the Workflow. For example, if this workflow was generated from StackOverflow, the `author` would be the `author` of the StackOverflow post. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional.
36+
37+
### `author_url`
38+
----
39+
The URL of original author of the Workflow. For example, if this workflow was generated from StackOverflow, the `author_url` would be the StackOverflow author's profile page. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional.
40+
41+
### `shells`
42+
----
43+
The list of shells where this Workflow is valid. If not specified, the Workflow is assumed to be valid in all shells. This must be one of `zsh`, `bash`, or `fish`.
44+
45+
46+
## `arguments`
47+
----
48+
A Workflow can have parameterized arguments to specify pieces of the Workflow that need to be filled in by the user.
49+
50+
You can specify which part of the Workflow command maps to an argument by surrounding it with two curly braces (`{{<argument>}}`).
51+
52+
For example the workflow command:
53+
```bash
54+
for {{variable} in {{sequence}}}; do
55+
{{command}}
56+
done
57+
```
58+
Includes 3 arguments: `variable`, `sequence`, and `command`.
59+
60+
## `arguments.name`
61+
-----
62+
The name of the argument. The argument name is used within the command to specify the ranges of the argument. Required.
63+
64+
```yaml
65+
name: Example workflow
66+
command: echo {{string}}
67+
arguments:
68+
- name: string
69+
- description: The value to echo
70+
```
71+
72+
## `arguments.description`
73+
-----
74+
The description of the argument. This is surfaced in both commands.dev and Warp to help users fill in Workflow arguments. Optional
75+
76+
## `arguments.default_value`
77+
-----
78+
The default value for the argument. If specified, the `default_value` replaces the argument name within the command. Optional

‎README.md‎

Lines changed: 10 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,16 @@
1-
# [0] Overview and Mockups
1+
# Workflows
2+
The repo for Workflows that appear within Warp and within [commands.dev](https://www.commands.dev/)
23

3-
Entering commands in the terminal can be tedious and hard–developers often need to construct commands one argument and flag at a time, often using StackOverflow.
44

5-
Workflows (formerly called Tasks) make it easy to browse, search, execute and share commands (or a series of commands)--without needing to leave your terminal.
5+
## What are Workflows?
6+
Workflows are an easier way to execute and share commands within Warp. They are searchable by name, description, or command and are easily parameterized.
67

7-
Warp wants to make it easier to enter commands by launching with 100+ common workflows and an open-source file format--so devs can create private workflows for themselves or their team.
8+
## How Do I Access Workflows?
9+
Workflows can be accessed within Warp directly within the app, either through the command palette or by pressing `ctrl-shift-r`.
810

9-
Please comment with feedback, we’ll create an individual sub-thread for each mockup and memo section!
11+
All public workflows (i.e. workflows within this repo) are also available at [commands.dev](https://www.commands.dev/).
1012

13+
## Contributing
14+
Contributions are always welcome! If you have a workflow that would be useful to many Warp users, feel free to send a PR to add a Workflow spec.
1115

12-
13-
|[A] The Workflow’s menu.|
14-
|:--:|
15-
| ![A](https://user-images.githubusercontent.com/29553206/150206227-e5ae4eec-b322-4509-aba8-f67ee23eab39.png) |
16-
17-
|[B] Filling a Workflow in the Input Editor with the menu expanded.|
18-
|:--:|
19-
| ![B](https://user-images.githubusercontent.com/29553206/150206255-2288326d-4c5c-459a-b1fc-77c046c13bc7.png) |
20-
21-
|[C] Filling a Workflow in the Input Editor with the menu collapsed and tab completion.|
22-
|:--:|
23-
| ![C](https://user-images.githubusercontent.com/29553206/150207821-d0d02b9f-686e-475a-b1fe-a3741fb3f707.png) |
24-
25-
# [1] Pain Points and Goals
26-
27-
Our team, tends to run into a few pain points when entering commands:
28-
29-
1. We need to find a command but
30-
1. the arguments and flags do not represent the task we are trying to perform
31-
1. To “undo last git commit” -> `git reset --hard SOFT`
32-
2. our team's playbook (guide) lives outside of the terminal
33-
2. We can’t find aliases that other team members have made
34-
1. No store to browse aliases
35-
2. Sharing, revoking access, or updating aliases through version control is not straightforward, especially
36-
since aliases are global
37-
3. The shell does not provide enough documentation or UI to help enter parameters to commands
38-
39-
# [2] How is this Different from Aliases?
40-
41-
Power users tend to save aliases, create shell functions, and leverage CLI tools that streamline this.
42-
Aliases, however, have major pain points:
43-
44-
1. need to context switch
45-
1. leave vim, source dotfiles, or reset shell
46-
2. it’s difficult to attach documentation
47-
3. are not easily searchable or sharable
48-
4. are not easily parameterized
49-
50-
Getting aliases and functions to a productive state requires an upfront investment that’s justifiable for devs who
51-
spend most of their workday in the terminal but less so for beginners and casual users.
52-
53-
# [3] Workflows V1
54-
55-
We’re planning on the first launch of Workflows to include:
56-
57-
1. The ability to search and execute a workflow directly from the input editor
58-
2. The top 100 workflows across various commands already bundled
59-
1. `git`, `sed`, and `grep`
60-
3. The ability for devs to create private workflows in an open-source file-format, including repo-specific workflows that live in a `.warp` directory
61-
4. The ability to create a workflow from a Block by right-clicking on it
62-
63-
# [4] S/O Open Source Projects
64-
65-
These are some of the open source projects that we’ve gotten inspiration from: [tldr;](https://github.com/tldr-pages/tldr) [cheat.sh](https://github.com/chubin/cheat.sh), [cheatsheets](https://github.com/rstacruz/cheatsheets), [navi](https://github.com/denisidoro/navi), [howdoi](https://github.com/gleitz/howdoi), [cheat](https://github.com/cheat/cheat), [how2](https://github.com/santinic/how2), [kb](https://github.com/gnebbia/kb), [eg](https://github.com/srsudar/eg).
66-
67-
Navi [in particular!](https://github.com/denisidoro/navi/blob/master/docs/cheatsheet_syntax.md)
68-
69-
# [5] Question for the Community
70-
71-
We’ve made a thread for each section; please reply in the appropriate threads to help organize discussion!
72-
73-
### We'll ship with some prebuilt workflows, what are some workflows to include?
74-
If you can, try to use this format:
75-
76-
#### Title of workflow (what does it do)
77-
78-
Extract a field from a json
79-
80-
#### Command
81-
82-
`cat channel_versions.json | jq '.stable.versions'`
83-
84-
#### Parameters
85-
86-
`channel_versions.json` -> a json file
87-
88-
#### Articulation or links to StackOverflow (or other sites)
89-
90-
https://stackoverflow.com/questions/39228500/extract-a-specific-field-from-json-output-using-jq
16+
The existing preset files should serve as an example for the format, while the a more comprehensive description of the file format is available in [FORMAT.md](FORMAT.md). Please request a review from someone on the Warp team once a PR is ready for review.

0 commit comments

Comments
 (0)