Skip to content

Commit 52e0eae

Browse files
rick-nurick-nu
committed
Add usefull tasks in the docs folder
1 parent b296557 commit 52e0eae

File tree

9 files changed

+233
-1
lines changed

9 files changed

+233
-1
lines changed

‎README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@ project and run common tasks via super simple commands.
99

1010
This project gives you a `Taskfile` base, and gives you a collection of usefull tasks to help out on your project.
1111

12-
Check [the full documentation](https://github.com/rick-nu/Taskfile).
12+
- [What is a Taskfile](docs/what-is-a-taskfile.md)
13+
- [The Taskfile base](docs/base.md)
14+
- [Usefull tasks](docs/usefull-tasks.md)
1315

1416
## Credits
1517

‎Taskfile

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
#!/bin/bash
22
set -eo pipefail
33

4+
# =========================================================
5+
# Taskfile gives you a set of quick tasks for your project.
6+
# Run ./Taskfile in your CLI to see all available tasks.
7+
# More info on: https://bit.ly/taskfile-base
8+
# =========================================================
9+
410
# =========================================================
511
## Documentation
612
# =========================================================

‎docs/base.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# The Taskfile base
2+
3+
➤ [Overview](../README.md) ➤ Taskfile base
4+
5+
Below is the Taskfile base we recommend you use. Below we will explain what sections are in the base and why.
6+
7+
```bash
8+
#!/bin/bash
9+
set -eo pipefail
10+
11+
# =========================================================
12+
# Taskfile gives you a set of quick tasks for your project.
13+
# Run ./Taskfile in your CLI to see all available tasks.
14+
# More info on: https://bit.ly/taskfile-base
15+
# =========================================================
16+
17+
# TODO:
18+
# This is where you add relevant tasks for your project.
19+
20+
# =========================================================
21+
## Taskfile
22+
# =========================================================
23+
24+
BLUE=$(printf '\033[36m')
25+
YELLOW=$(printf '\033[33m')
26+
RESET=$(printf '\033[0m')
27+
28+
function title {
29+
echo -e "\n${BLUE}=>${RESET} $1\n"
30+
}
31+
32+
function banner {
33+
echo ""
34+
echo "████████╗ █████╗ ███████╗██╗ ██╗███████╗██╗██╗ ███████╗"
35+
echo "╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝██╔════╝██║██║ ██╔════╝"
36+
echo " ██║ ███████║███████╗█████╔╝ █████╗ ██║██║ █████╗"
37+
echo " ██║ ██╔══██║╚════██║██╔═██╗ ██╔══╝ ██║██║ ██╔══╝"
38+
echo " ██║ ██║ ██║███████║██║ ██╗██║ ██║███████╗███████╗"
39+
echo " ╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚══════╝"
40+
}
41+
42+
function task:help { ## Show all available tasks
43+
title "Available tasks"
44+
awk 'BEGIN {FS = " { [#][#][ ]?"} /^([a-zA-Z_-]*:?.*)(\{ )?[#][#][ ]?/ \
45+
{printf "\033[33m%-34s\033[0m %s\n", $1, $2}' $0 |\
46+
sed -E "s/[#]{2,}[ ]*/${RESET}/g" |\
47+
sed -E "s/function task:*/ /g"
48+
echo -e "\n${BLUE}Usage:${RESET} $0 ${YELLOW}<task>${RESET} <args>"
49+
}
50+
51+
function task:shorthand { ## Create CLI shorthand task instead of ./Taskfile
52+
title "Creating task shorthand"
53+
if [ -f /usr/local/bin/task ]
54+
then
55+
echo "/usr/local/bin/task already exists."
56+
else
57+
echo -e "You are about to create /usr/local/bin/task that requires root permission..."
58+
sudo curl --location --silent --output /usr/local/bin/task https://bit.ly/taskfile-bin
59+
sudo chmod +x /usr/local/bin/task
60+
fi
61+
echo -e "${BLUE}You can now use:${RESET} task ${YELLOW}<task>${RESET} <args>"
62+
}
63+
64+
# Execute tasks (defaults to help)
65+
banner
66+
"task:${@:-help}"
67+
```
68+
69+
## Banner
70+
71+
By default we include a banner in your Taskfile. In the base you have a pretty ascii art of "Taskfile", but we recommend
72+
you replace this with your own project title. You can use http://patorjk.com/software/taag/ for that.
73+
74+
## Title
75+
76+
In order to give all the tasks a pretty and clear structre, a title function is added that we recommend you use at
77+
the start of every task. This will create a nice divider and let your user know that your Taskfile is about to start
78+
a new process.
79+
80+
```bash
81+
function task:my-new-task { ## My new task example
82+
title "Starting with my new task"
83+
# Your task continues here...
84+
}
85+
```
86+
87+
## Help section
88+
89+
A help section for your Taskfile is generated automatically. This is done by scanning the Taskfile itself, and checking
90+
if a line contains `##` (double comment). When it finds a `##`, it will either use the line as a new section in the
91+
help overview, or when it's combined with a `function task:* { ## Descriptoin` then the comment will be used as the
92+
task description. Using this will give your user a clear overview of what tasks can be run.
93+
94+
## Shorthand
95+
96+
If you're a lazy developer (that's a good thing, trust me), you're probably already tired of having to type
97+
`./Taskfile <task>` all the time. The `task:shorthand` gives you a quick and easy option to create a `task` binary on
98+
your system, so you can use `task <task>` in the future. It will look for a `Taskfile` in the current directory.
99+
100+
# Adding relevant tasks
101+
102+
Relevant tasks for your project can be found in [the overview](../README.md).

‎docs/section/docker.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Docker
2+
3+
➤ [Overview](../../README.md) ➤ [Usefull tasks](../usefull-tasks.md) ➤ Docker
4+
5+
An absolute must if your project is running via docker locally.
6+
7+
```bash
8+
# ===========================
9+
## Docker
10+
# ===========================
11+
12+
function task:build { ## (re)build the project docker containers
13+
title "Building project container"
14+
docker compose build
15+
}
16+
17+
function task:start { ## Run the project locally
18+
title "Starting project container"
19+
docker compose up -d
20+
title "Project running"
21+
echo "View the project on <project link>"
22+
}
23+
24+
function task:stop { ## Stop the local project
25+
title "Stopping project container"
26+
docker compose stop
27+
}
28+
29+
function task:restart { ## Restart the local project
30+
task:stop
31+
task:start
32+
}
33+
34+
function task:logs { ## Stop the local project
35+
title "Show the logs of the running project containers"
36+
docker compose logs -f
37+
}
38+
```

‎docs/section/github.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# GitHub
2+
3+
➤ [Overview](../../README.md) ➤ [Usefull tasks](../usefull-tasks.md) ➤ GitHub

‎docs/section/gitlab.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# GitLab
2+
3+
➤ [Overview](../../README.md) ➤ [Usefull tasks](../usefull-tasks.md) ➤ GitLab
4+
5+
If you use GitLab and want an easy way to check out Merge Requests locally,
6+
`task:mr` is a great addition to your project section in the Taskfile.
7+
8+
```bash
9+
function task:mr { ## Check out merge request <number> and update
10+
project:checkout-mr
11+
project:update
12+
}
13+
14+
function project:checkout-mr {
15+
title "Checking out merge request"
16+
if [ -z "$1" ]
17+
then
18+
echo "You need to provide a merge request number to check out."
19+
echo -e "${BLUE}Usage:${RESET} $0 mr ${YELLOW}<number>${RESET}"
20+
exit 422
21+
fi
22+
echo "Checking out merge request $1..."
23+
git fetch origin refs/merge-requests/$1/head:refs/remotes/origin/merge-requests/$1
24+
git checkout origin/merge-requests/$1
25+
}
26+
```

‎docs/section/project.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Project section
2+
3+
➤ [Overview](../../README.md) ➤ [Usefull tasks](../usefull-tasks.md) ➤ Project
4+
5+
A project section can be very usefull to quickly get your project up and running,
6+
including the latest changes. A common practice is to include a `task:init` to get your
7+
entire project up and running with a single command, and a `task:update` to make sure everything
8+
is up to date.
9+
10+
```bash
11+
# ===========================
12+
## Project
13+
# ===========================
14+
15+
function task:init { ## Initialise the project for local development
16+
project:local-files
17+
project:update
18+
# docker:start
19+
task:help
20+
}
21+
22+
function task:update { ## Update all dependencies and files
23+
project:update
24+
}
25+
26+
function project:update {
27+
title "Run project updates"
28+
# Todo: install dependencies, build scripts, etc...
29+
}
30+
31+
function project:local-files {
32+
title "Setting local files"
33+
# cp --no-clobber local.env .env
34+
# echo "Created .env file for local usage from local.env."
35+
}
36+
```

‎docs/usefull-tasks.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Usefull tasks
2+
3+
➤ [Overview](../README.md) ➤ Usefull tasks
4+
5+
We strongly recommend that your project uses a project section containing a `init` and a `update` task. Check out our
6+
example:
7+
8+
- [Project section](./section/project.md)
9+
10+
Check out the following sections for tasks that could be helpfull for your project's Taskfile:
11+
12+
- [Docker](./section/docker.md)
13+
- [GitHub](./section/github.md)
14+
- [GitLab](./section/gitlab.md)

‎docs/what-is-a-taskfile.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# What is a taskfile?!
2+
3+
➤ [Overview](../README.md) ➤ What is a Taskfile
4+
5+
TODO.

0 commit comments

Comments
 (0)