Diff options
| author | Bryce Kwon <bryce@brycekwon.com> | |
|---|---|---|
| committer | Bryce Kwon <bryce@brycekwon.com> | |
| commit | ||
| parent | ||
| tree | ||
| download | ||
Add a help page with common workflows
| -rw-r--r-- | assets/cgit.css | 27 | |
| -rw-r--r-- | cgitrc.5.txt | 6 | |
| -rw-r--r-- | examples/cgitrc | 4 | |
| -rw-r--r-- | source/cgit.c | 3 | |
| -rw-r--r-- | source/cgit.h | 1 | |
| -rw-r--r-- | source/cgit.mk | 1 | |
| -rw-r--r-- | source/cmd.c | 10 | |
| -rw-r--r-- | source/ui-help.c | 93 | |
| -rw-r--r-- | source/ui-help.h | 6 | |
| -rw-r--r-- | source/ui-shared.c | 6 | |
| -rw-r--r-- | tests/t0200-security.sh | 25 |
11 files changed, 182 insertions, 0 deletions
diff --git a/assets/cgit.css b/assets/cgit.css index f441faa..b55f002 100644 --- a/assets/cgit.css +++ b/assets/cgit.css @@ -604,6 +604,33 @@ div#cgit .markdown td { div#cgit .markdown th { background: var(--surface-2); } +/* ---- Help page -------------------------------------------------------- */ + +div#cgit div.help { + max-width: 52em; + line-height: 1.6; +} + +div#cgit div.help h2 { + font-size: 125%; + font-weight: bold; + margin: 1.3em 0 0.4em; +} + +div#cgit div.help p { + margin: 0.5em 0; +} + +div#cgit div.help pre.urls { + background: var(--surface-2); + border: 1px solid var(--border); + border-radius: 4px; + padding: 0.6em 0.9em; + font-family: var(--font-mono); + font-size: 90%; + overflow-x: auto; +} + div#cgit table#downloads { float: right; border-collapse: collapse; diff --git a/cgitrc.5.txt b/cgitrc.5.txt index 0c78ecb..a07d190 100644 --- a/cgitrc.5.txt +++ b/cgitrc.5.txt @@ -167,6 +167,12 @@ enable-follow-links:: Flag which, when set to "1", allows users to follow a file in the log view. Default value: "0". +enable-help:: + Flag which, when set to "1", adds a "help" tab to the repository index + with a built-in guide to the interface, covering the URL patterns for + common workflows such as comparing two tags or downloading a snapshot. + Default value: "1". + enable-git-config:: Flag which, when set to "1", will allow cgit to use git config to set any repo specific settings. This option is used in conjunction with diff --git a/examples/cgitrc b/examples/cgitrc index f65c310..c035742 100644 --- a/examples/cgitrc +++ b/examples/cgitrc @@ -197,6 +197,10 @@ enable-commit-graph=0 # Default is 0. enable-follow-links=0 +# Add a help tab to the index page with a built-in guide to the interface. +# Values are 0 or 1. Default is 1. +enable-help=1 + # Generate extra summary, commit and tree links per repo on the index. Values # are 0 or 1. Default is 0. enable-index-links=0 diff --git a/source/cgit.c b/source/cgit.c index caa90de..ce8b340 100644 --- a/source/cgit.c +++ b/source/cgit.c @@ -183,6 +183,8 @@ static void config_cb(const char *name, const char *value) ctx.cfg.enable_filter_overrides = atoi(value); else if (!strcmp(name, "enable-follow-links")) ctx.cfg.enable_follow_links = atoi(value); + else if (!strcmp(name, "enable-help")) + ctx.cfg.enable_help = atoi(value); else if (!strcmp(name, "enable-http-clone")) ctx.cfg.enable_http_clone = atoi(value); else if (!strcmp(name, "enable-index-links")) @@ -406,6 +408,7 @@ static void prepare_context(void) ctx.cfg.logo = "/cgit.png"; ctx.cfg.favicon = "/favicon.ico"; ctx.cfg.local_time = 0; + ctx.cfg.enable_help = 1; ctx.cfg.enable_http_clone = 1; ctx.cfg.enable_index_owner = 1; ctx.cfg.enable_tree_linenumbers = 1; diff --git a/source/cgit.h b/source/cgit.h index 5de7968..d921e76 100644 --- a/source/cgit.h +++ b/source/cgit.h @@ -229,6 +229,7 @@ struct cgit_config { int embedded; int enable_filter_overrides; int enable_follow_links; + int enable_help; int enable_http_clone; int enable_index_links; int enable_index_owner; diff --git a/source/cgit.mk b/source/cgit.mk index 1e5b5e1..ace8fd1 100644 --- a/source/cgit.mk +++ b/source/cgit.mk @@ -90,6 +90,7 @@ CGIT_OBJ_NAMES += ui-blob.o CGIT_OBJ_NAMES += ui-clone.o CGIT_OBJ_NAMES += ui-commit.o CGIT_OBJ_NAMES += ui-diff.o +CGIT_OBJ_NAMES += ui-help.o CGIT_OBJ_NAMES += ui-log.o CGIT_OBJ_NAMES += ui-patch.o CGIT_OBJ_NAMES += ui-plain.o diff --git a/source/cmd.c b/source/cmd.c index 477bb3f..a8768eb 100644 --- a/source/cmd.c +++ b/source/cmd.c @@ -23,6 +23,7 @@ #include "ui-repolist.h" #include "ui-snapshot.h" #include "ui-stats.h" +#include "ui-help.h" #include "ui-summary.h" #include "ui-tag.h" #include "ui-tree.h" @@ -32,6 +33,14 @@ static void HEAD_fn(void) cgit_clone_head(); } +static void help_fn(void) +{ + if (ctx.cfg.enable_help) + cgit_print_help(); + else + cgit_print_error_page(404, "Not found", "Help is disabled"); +} + static void atom_fn(void) { cgit_print_atom(ctx.qry.head, ctx.qry.path, ctx.cfg.max_atom_items); @@ -184,6 +193,7 @@ struct cgit_cmd *cgit_get_cmd(void) def_cmd(blob, 1, 0, 0), def_cmd(commit, 1, 1, 0), def_cmd(diff, 1, 1, 0), + def_cmd(help, 0, 0, 0), def_cmd(info, 1, 0, 1), def_cmd(log, 1, 1, 0), def_cmd(ls_cache, 0, 0, 0), diff --git a/source/ui-help.c b/source/ui-help.c new file mode 100644 index 0000000..981733d --- /dev/null +++ b/source/ui-help.c @@ -0,0 +1,93 @@ +/* ui-help.c: built-in guide to the cgit interface + * + * Copyright (C) 2006-2018 cgit Development Team <cgit@lists.zx2c4.com> + * + * Licensed under GNU General Public License v2 + * (see LICENSE.txt for full license text) + */ + +#include "cgit.h" +#include "ui-help.h" +#include "html.h" +#include "ui-shared.h" + +static void print_workflow(const char *title, const char *intro, + const char *pattern, const char *example) +{ + html("<h2>"); + html_txt(title); + html("</h2>\n<p>"); + html_txt(intro); + html("</p>\n"); + if (pattern) { + html("<pre class='urls'>"); + html_txt(pattern); + if (example) { + html("\n"); + html_txt(example); + } + html("</pre>\n"); + } +} + +void cgit_print_help(void) +{ + cgit_print_layout_start(); + html("<div class='help'>\n"); + + html("<p>Every page on this site has a stable address, so anything " + "you can see can also be linked, scripted or fetched. The " + "patterns below cover the common workflows. Angle brackets " + "mark the parts you replace.</p>\n"); + + print_workflow("Browse a repository", + "Each repository has a summary page, and the tabs on it lead " + "to the branch and tag list, the commit history and the file " + "tree.", + "/<repo>/ /<repo>/refs/ /<repo>/log/ /<repo>/tree/", + NULL); + + print_workflow("Pin what you are looking at", + "Add h= to select a branch, or id= to select any commit, tag " + "or object hash. They work on nearly every page, so a pinned " + "URL always shows the same content.", + "/<repo>/tree/?h=<branch> /<repo>/tree/?id=<commit>", + "/linux/tree/?h=stable /linux/tree/?id=v6.1"); + + print_workflow("View a file", + "Append a path to the tree page for the rendered view, use " + "plain for the raw bytes, and blame to see which commit last " + "touched each line.", + "/<repo>/tree/<path> /<repo>/plain/<path> /<repo>/blame/<path>", + "/linux/tree/kernel/fork.c?h=v6.1"); + + print_workflow("Compare two points in history", + "The diff page compares id2, the older point, with id, the " + "newer one. Both accept tags, branches and commit hashes. " + "Use rawdiff for the plain patch text.", + "/<repo>/diff/?id=<new>&id2=<old>", + "/linux/diff/?id=v6.2&id2=v6.1"); + + print_workflow("Follow the history of a path", + "The log page takes a path to limit history to it. The " + "search box above the log searches the message, author or " + "committer, and the range type accepts any revision range.", + "/<repo>/log/<path> /<repo>/log/?qt=range&q=<rev1>..<rev2>", + "/linux/log/?qt=range&q=v6.1..v6.2"); + + print_workflow("Download a release or a patch", + "Snapshots are archives of a tag or commit, named after the " + "repository and version. The patch page emits a single " + "commit as an emailable patch.", + "/<repo>/snapshot/<repo>-<version>.tar.gz /<repo>/patch/?id=<commit>", + "/linux/snapshot/linux-v6.1.tar.gz"); + + print_workflow("Subscribe to changes", + "Every repository serves an Atom feed of its history, and " + "h= scopes it to a branch.", + "/<repo>/atom/ /<repo>/atom/?h=<branch>", + NULL); + + html("</div>\n"); + cgit_print_layout_end(); +} diff --git a/source/ui-help.h b/source/ui-help.h new file mode 100644 index 0000000..85a4db7 --- /dev/null +++ b/source/ui-help.h @@ -0,0 +1,6 @@ +#ifndef UI_HELP_H +#define UI_HELP_H + +extern void cgit_print_help(void); + +#endif /* UI_HELP_H */ diff --git a/source/ui-shared.c b/source/ui-shared.c index df7ad1f..61ce3ca 100644 --- a/source/ui-shared.c +++ b/source/ui-shared.c @@ -1192,6 +1192,12 @@ void cgit_print_pageheader(void) NULL, NULL, 0, 1); html("</li>\n"); } + if (ctx.cfg.enable_help) { + html("<li>"); + site_link("help", "help", "How to use this site", hc("help"), + NULL, NULL, 0, 1); + html("</li>\n"); + } html("</ul>\n"); html("<form class='search' method='get' action='"); html_attr(currenturl); diff --git a/tests/t0200-security.sh b/tests/t0200-security.sh index d3ac472..44703c9 100644 --- a/tests/t0200-security.sh +++ b/tests/t0200-security.sh @@ -124,4 +124,29 @@ test_expect_success 'tree groups directories before files' ' test "$dirline" -lt "$fileline" ' +# --- Fork feature: built-in help page ---------------------------------------- +test_expect_success 'help tab appears on the index by default' ' + cgit_query "" >tmp && + grep "p=help" tmp +' + +test_expect_success 'help page renders the workflow guide' ' + cgit_query "p=help" >tmp && + grep "Compare two points in history" tmp +' + +test_expect_success 'enable-help=0 hides the tab and the page' ' + { + echo "virtual-root=/" && + echo "cache-size=0" && + echo "enable-help=0" && + echo "repo.url=sec" && + echo "repo.path=$PWD/repos/sec/.git" + } >nohelprc && + CGIT_CONFIG="$PWD/nohelprc" QUERY_STRING="" cgit >tmp && + ! grep "p=help" tmp && + CGIT_CONFIG="$PWD/nohelprc" QUERY_STRING="p=help" cgit >tmp && + grep "Status: 404" tmp +' + test_done |