Added git commands.
This commit is contained in:
parent
3a499aa5dd
commit
d079e33c04
|
|
@ -21,20 +21,22 @@ This is where I keep my notes on how to do things.
|
|||
Git is project and folder-centered, and to start using git go to the root folder
|
||||
of a project you want to place under source control and initialize it:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
$ mkdir a-new-project
|
||||
$ touch README.md
|
||||
$ git init
|
||||
```
|
||||
|
||||
This creates a new folder, `.git`, where Git will store your commit history and
|
||||
some configuration details.
|
||||
some configuration details. Git will usually not create a repository without
|
||||
_something_ to store in it, but see the [`git start` alias](#config) below.
|
||||
|
||||
## Putting files into git
|
||||
|
||||
To put files under source control, you must add them. To update the entire
|
||||
folder, switch to the root of the project and add _all_ of it:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
$ git add .
|
||||
$ git commit
|
||||
```
|
||||
|
|
@ -47,7 +49,7 @@ don't have to explain too much!
|
|||
If your commit message could be a single line, you can add it directly from the
|
||||
command line:
|
||||
|
||||
```shell
|
||||
```bash
|
||||
$ git add .
|
||||
$ git commit -m "Updated the widget to widgetize."
|
||||
```
|
||||
|
|
@ -58,17 +60,17 @@ been modified, and will delete any files that you have deleted, from the
|
|||
repository. (Deleted files still exist in the history and can always be
|
||||
recovered.)
|
||||
|
||||
```shell
|
||||
```bash
|
||||
$ git commit -am "Updated the widget to widgetize."
|
||||
```
|
||||
|
||||
## Git Configuration
|
||||
## Git Configuration {#config}
|
||||
|
||||
You can have a global Git configuration file, `$HOME/\.gitconfig`, in which you
|
||||
keep your personal information and command aliases, which is one of three ways
|
||||
you can add your own commands to Git.
|
||||
|
||||
```shell
|
||||
```bash
|
||||
[user]
|
||||
name = Elf M. Sternberg
|
||||
email = someguy@example.com
|
||||
|
|
@ -77,13 +79,68 @@ you can add your own commands to Git.
|
|||
unstage = reset -q HEAD --
|
||||
nevermind = !git reset --hard HEAD && git clean -d -f
|
||||
wip = for-each-ref --sort='authordate:iso8601' --format='%(color:green)%(authordate:relative)%09%(color:white)%(refname:short)' refs/heads
|
||||
stem = "!f() { git checkout -b $1 master; }; f"
|
||||
stem = "!f() { git checkout -b $1 develop; }; f"
|
||||
start = !git init && git commit --allow-empty -m \"Initial commit\"
|
||||
```
|
||||
|
||||
I'll explain each of these eventually, but for now, just know that if you want
|
||||
your commits to be attributed to the right person, you must have the `[user]`
|
||||
block, and
|
||||
## Git Aliases {#aliases}
|
||||
|
||||
Aliases are commands that you can run *in git* as if they were part of the git
|
||||
toolset, but their functionality is defined by you. The five aliases shown
|
||||
above are my "must haves." They represent the way I work.
|
||||
|
||||
- `unstage` is something I do a lot. Maybe it's my ADHD, but I often add
|
||||
something to the git staging area, then realize that the work was incomplete
|
||||
and have to go back. This command does that, and I hated memorizing it.
|
||||
- `nevermind` is for when your work has gone off the rails; your stab at solving
|
||||
the problem has taken you places you didn't want to be. This command resets
|
||||
you to exactly where you were before you started hacking.
|
||||
- `wip` stands for "works in progress"; it shows you a list of branches
|
||||
currently live in your local project, in the order from oldest to newest, with
|
||||
a text that tells you your last commit was "yesterday" or "3 months ago".
|
||||
- `stem` creates a new branch off the develop branch (you can change that to
|
||||
main or canon or whatever). This is the most common workflow I have at home,
|
||||
and this command allows me to get to it quickly. The syntax tells git to use
|
||||
the bash to populate the new branch name, as the default alias format can
|
||||
only take arguments at the end, and the new branch name must be injected
|
||||
before the source branch.
|
||||
- `start` creates a git repository out of a completely empty folder. This might
|
||||
seem odd, but it's actually a very useful way of introducing a new project and
|
||||
ensuring git is ready to go.
|
||||
|
||||
## Git Extensions
|
||||
|
||||
Just like aliases, you can add whole unique commands to git, as long as the
|
||||
extension name doesn't conflict with one of git's internal commands. The
|
||||
syntax for doing so is to create a script (in any language!) and name it
|
||||
`git-your-extension-name`, and you call it by invoking git and giving it the
|
||||
extension name.
|
||||
|
||||
For example, if you write documentation and you want to know how many words
|
||||
you've written since your last commit, you can create a Bash script named
|
||||
`git-wc` (word count):
|
||||
|
||||
``` bash
|
||||
#!/bin/bash
|
||||
REM=`git diff --word-diff=porcelain -U $* | grep '^-' | sed 's/^-//' | wc -w`
|
||||
ADD=`git diff --word-diff=porcelain -U $* | grep '^+' | sed 's/^+//' | wc -w`
|
||||
DIF=`expr $ADD - $REM`
|
||||
echo "Word count: $DIF"
|
||||
```
|
||||
|
||||
## Add vs Commit
|
||||
|
||||
You may have noticed that there's a two-step to committing your work; you `add`
|
||||
it, then `commit` it. `add`ing it puts it into the `staging area`. The primary
|
||||
goal of this design is to allow you to commit only parts of your project, rather
|
||||
than committing everything at once. By creating an index of what-to-commit, and
|
||||
then allowing you to write your commit message afterward, you have more control
|
||||
over the development process.
|
||||
|
||||
If you're completely reassured of your skillz as a _leet koder dood_, you could
|
||||
always create an alias that stages, commits, and pushes to your remote
|
||||
repository all at once. I don't recommend that.
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -17,18 +17,20 @@ categories=["Web Development", "Static Site Generation", "Zola"]
|
|||
collection of markdown documents in a folder-structured hierarchy, using a
|
||||
corresponding collection of HTML templates, which in turn use a corresponding
|
||||
collection of SASS collection and a collection of HTML templates. The templating
|
||||
language is called [Tera](https://tera.netlify.app).
|
||||
language is called [Tera](https://tera.netlify.app). For convenience, all the
|
||||
functions defined for both Tera and Zola have been compiled into lists in this
|
||||
document.
|
||||
|
||||
If you need anything else (Typescript built into Javascript, templates other
|
||||
than Zola's internal, static file conversion, etc.), you'll need separate
|
||||
than Zola's internal, static file conversion, etc.), you'll need separate build
|
||||
toolchains for those.
|
||||
|
||||
## Mental Model for Zola
|
||||
|
||||
A website built with Zola originates with the `content/` folder. Inside that
|
||||
folder, every markdown document and every folder creates a corresponding page in
|
||||
the constructed website. There are only *two* models you have to understand
|
||||
Zola: *sections* and *pages*.
|
||||
Elf, a website built with Zola originates with the `content/` folder. Inside
|
||||
that folder, every markdown document and every folder creates a corresponding
|
||||
page in the constructed website. There are only *two* models you have to
|
||||
understand Zola: *sections* and *pages*.
|
||||
|
||||
A *section* is a folder with a file named `_index.md` in it; note the
|
||||
underscore, which signifies the section definition file. For these documents, a
|
||||
|
|
@ -53,7 +55,7 @@ by which every template has access to the metadata (and even the content!) of
|
|||
every other markdown document, arranged in the hierarchy described in the
|
||||
`content` folder.
|
||||
|
||||
### Recommendation
|
||||
### Proces Recommendation
|
||||
|
||||
1. Design your document hierarchy first.
|
||||
2. Construct your content folder to support that hierarchy.
|
||||
|
|
@ -62,6 +64,13 @@ every other markdown document, arranged in the hierarchy described in the
|
|||
5. Build the corresponding `Page` templates.
|
||||
6. Worry about Sass afterward
|
||||
|
||||
### Construction Recommendation
|
||||
|
||||
Use the `include` block more than the `extends` block. Build your websites by
|
||||
composition, not inheritance with override. Ignore the way Django and everyone
|
||||
else does it. Composition may result in some small amount of repetition, but
|
||||
the legibility and coherency of your project will more than compensate.
|
||||
|
||||
## Running Zola
|
||||
|
||||
Zola has only a few commands:
|
||||
|
|
@ -314,42 +323,18 @@ some optional content. The TOML header _may_ specify which template to use to
|
|||
render the section info, otherwise Zola falls back to the default at
|
||||
`./templates/section.html`.
|
||||
|
||||
#### Section Header in every `_index.md` file
|
||||
|
||||
The arguments that con be placed into the TOML header of a the `_index.md` file are:
|
||||
|
||||
- `title`: a string
|
||||
- `description`: a string
|
||||
- `draft`: `true`/`false` if this section should be included in builds
|
||||
- `sort_by`: Sorting function to use: `date`, `title`, `weight`, or `none`
|
||||
- `weight`: Used to provide subsection weight to a parent section
|
||||
- `template`: The template to render this section. Defaults to `./templates/section.html`
|
||||
- `page_template`: The default template to render pages in this section. Pages with this field specified overide this setting
|
||||
- `paginate_by`: Number of pages to paginate by. Set to `0` for no pagination
|
||||
- `paginate_path`: The prefix for paginations. Default to "page"
|
||||
- `paginate_reversed`: boolean
|
||||
- `insert_anchor_links`: One of `left`, `right`, or `none`. Specifies whether an anchor-link should be provided for every header item. Probably overridable by the template.
|
||||
- `in_search_index`: Include this section in the search index. Only matters if search is enabled
|
||||
- `transparent`: `true`/`false`, specifies if this section should be inherited by the parent
|
||||
- `aliases`: An array of paths to redirect to this folder
|
||||
- `[extra]`: Your extra data block
|
||||
{{ definition_list(source="zola/section_arguments.json") }}
|
||||
|
||||
#### Section Object delivered to the template:
|
||||
|
||||
The context for a section page contains the following fields, which will be
|
||||
available to the template:
|
||||
|
||||
- `content`: The content of the `_index.md` file
|
||||
- `title`: The Title found in the TOML part of `_index.md`
|
||||
- `description`: (optional): The description
|
||||
- `path`: As provided by Zola
|
||||
- `components`: The path, split into atoms
|
||||
- `permalink`: The URL for this page
|
||||
- `extra`: The contents of the TOML's `[extra.*]` blocks.
|
||||
- `pages`: An array of all child pages _in this same folder_.
|
||||
- `subsections`: An array of all child sections _in this same folder_.
|
||||
- `toc`: An array of `Header` objects: id, title, permalink, children (Which is itself
|
||||
an array of `Header` objects)
|
||||
- `word_count`: Unicode-smart.
|
||||
- `reading_time`: Number;
|
||||
- `assets`: An array of assets available in this section.
|
||||
- `ancestors`: An array of parent paths, with the root being the last one.
|
||||
{{ definition_list(source="zola/section_fields.json") }}
|
||||
|
||||
### Pages {#page}
|
||||
|
||||
|
|
@ -359,49 +344,17 @@ underscore!). The latter syntax is preferred if the file has associated assets,
|
|||
such as JavaScript or images, that you want to load alongside the content within
|
||||
the markdown page.
|
||||
|
||||
#### Page Header in every page file
|
||||
|
||||
The following items can appear in the TOML header of a page:
|
||||
|
||||
- `title`: The title of this page.
|
||||
- `description`: A description of this page
|
||||
- `date`: Date this page was published
|
||||
- `updated`: Date this page was updated
|
||||
- `weight`: A number, used for sorting
|
||||
- `draft`: Boolean. Specifies if this page should be rendered at build time
|
||||
- `slug`: String. The slug Zola should use when generating the URL
|
||||
- `path`: A manually specified absolute path to this content
|
||||
- `aliases`: An array of former urls that lead here, to redirect people here
|
||||
- `in_search_index`: If set to false and search is enabled, this page will not be included
|
||||
- `template`: The template used to render this page. Defaults to `./templates/page.html`
|
||||
- `[taxonomies]`: The taxonomies for this page
|
||||
- `[extra]`: Your own extra data
|
||||
{{ definition_list(source="zola/page_arguments.json") }}
|
||||
|
||||
#### Page Object delivered to templates
|
||||
|
||||
Pages derive the following information in their context:
|
||||
|
||||
- `content`: The markdown content from the page's file
|
||||
- `title`: The title, if present in the TOML block
|
||||
- `description`: The description
|
||||
- `date`: The date this file was added
|
||||
- `updated`: The date this file was last updated
|
||||
- `slug`: The slug name of this file
|
||||
- `path`: The path to this file
|
||||
- `draft`: true/false, will tell Zola not to include this file during builds
|
||||
- `components`: The path, split by '/'
|
||||
- `permalink`: The URL Zola generates for this file
|
||||
- `summary`: A provided string
|
||||
- `taxonomies`: The taxonomies list, if any
|
||||
- `extra`: The extras block
|
||||
- `toc`: An array of `Header` objects as derived from the Markdown
|
||||
- `word_count`: A naive word count
|
||||
- `reading_time`: A primitive reading time, in minutes
|
||||
- `earlier`: The content of the previous page, if the section header entry 'sort_by' is set to 'date.'
|
||||
- `later`: The content of the next page
|
||||
- `heavier`: The content of the previous page, if the section header entry 'sort_by' is set to 'weight'
|
||||
- `lighter`: The content of the next page
|
||||
- `year`: Year as a number.
|
||||
- `month`: Month as a number.
|
||||
- `day`: Day as a number.
|
||||
- `assets`: An array of assets available to this page.
|
||||
- `ancestors`: An array of parent paths, with the root being the last one.
|
||||
{{ definition_list(source="zola/page_fields.json") }}
|
||||
|
||||
### Pagination
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,23 @@
|
|||
{
|
||||
"definitions": [
|
||||
{ "dt": "title", "dd": "The title of this page." },
|
||||
{ "dt": "description", "dd": "A description of this page" },
|
||||
{ "dt": "date", "dd": "Date this page was published" },
|
||||
{ "dt": "updated", "dd": "Date this page was updated" },
|
||||
{ "dt": "weight", "dd": "A number, used for sorting" },
|
||||
{ "dt": "draft", "dd": "Boolean. Specifies if this page should be rendered at build time" },
|
||||
{ "dt": "slug", "dd": "String. The slug Zola should use when generating the URL" },
|
||||
{ "dt": "path", "dd": "A manually specified absolute path to this content" },
|
||||
{ "dt": "aliases", "dd": "An array of former urls that lead here, to redirect people here" },
|
||||
{
|
||||
"dt": "in_search_index",
|
||||
"dd": "If set to false and search is enabled, this page will not be included"
|
||||
},
|
||||
{
|
||||
"dt": "template",
|
||||
"dd": "The template used to render this page. Defaults to <kbd>./templates/page.html</kbd>"
|
||||
},
|
||||
{ "dt": "[taxonomies]", "dd": "The taxonomies for this page" },
|
||||
{ "dt": "[extra]", "dd": "Your own extra data" }
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
{
|
||||
"definitions": [
|
||||
{ "dt": "content", "dd": "The markdown content from the page's file" },
|
||||
{ "dt": "title", "dd": "The title, if present in the TOML block" },
|
||||
{ "dt": "description", "dd": "The description" },
|
||||
{ "dt": "date", "dd": "The date this file was added" },
|
||||
{ "dt": "updated", "dd": "The date this file was last updated" },
|
||||
{ "dt": "slug", "dd": "The slug name of this file" },
|
||||
{ "dt": "path", "dd": "The path to this file" },
|
||||
{ "dt": "draft", "dd": "true/false, will tell Zola not to include this file during builds" },
|
||||
{ "dt": "components", "dd": "The path, split by '/'" },
|
||||
{ "dt": "permalink", "dd": "The URL Zola generates for this file" },
|
||||
{ "dt": "summary", "dd": "A provided string" },
|
||||
{ "dt": "taxonomies", "dd": "The taxonomies list, if any" },
|
||||
{ "dt": "extra", "dd": "The extras block" },
|
||||
{ "dt": "toc", "dd": "An array of <kbd>Header</kbd> objects as derived from the Markdown" },
|
||||
{ "dt": "word_count", "dd": "A naive word count" },
|
||||
{ "dt": "reading_time", "dd": "A primitive reading time, in minutes" },
|
||||
{
|
||||
"dt": "earlier",
|
||||
"dd": "The content of the previous page, if the section header entry 'sort_by' is set to 'date.'"
|
||||
},
|
||||
{ "dt": "later", "dd": "The content of the next page" },
|
||||
{
|
||||
"dt": "heavier",
|
||||
"dd": "The content of the previous page, if the section header entry 'sort_by' is set to 'weight'"
|
||||
},
|
||||
{ "dt": "lighter", "dd": "The content of the next page" },
|
||||
{ "dt": "year", "dd": "Year as a number. " },
|
||||
{ "dt": "month", "dd": "Month as a number." },
|
||||
{ "dt": "day", "dd": "Day as a number." },
|
||||
{ "dt": "assets", "dd": "An array of assets available to this page." },
|
||||
{ "dt": "ancestors", "dd": "An array of parent paths, with the root being the last one." }
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
{
|
||||
"definitions": [
|
||||
{ "dt": "title", "dd": "a string" },
|
||||
{ "dt": "description", "dd": "a string" },
|
||||
{
|
||||
"dt": "draft",
|
||||
"dd": "<kbd>true</kbd>/<kbd>false</kbd> if this section should be included in builds"
|
||||
},
|
||||
{
|
||||
"dt": "sort_by",
|
||||
"dd": "Sorting function to use: <kbd>date</kbd>, <kbd>title</kbd>, <kbd>weight</kbd>, or <kbd>none</kbd>"
|
||||
},
|
||||
{ "dt": "weight", "dd": "Used to provide subsection weight to a parent section" },
|
||||
{
|
||||
"dt": "template",
|
||||
"dd": "The template to render this section. Defaults to <kbd>./templates/section.html</kbd>"
|
||||
},
|
||||
{
|
||||
"dt": "page_template",
|
||||
"dd": "The default template to render pages in this section. Pages with this field specified overide this setting"
|
||||
},
|
||||
{
|
||||
"dt": "paginate_by",
|
||||
"dd": "Number of pages to paginate by. Set to <kbd>0</kbd> for no pagination"
|
||||
},
|
||||
{ "dt": "paginate_path", "dd": "The prefix for paginations. Defaults to \"page\"" },
|
||||
{ "dt": "paginate_reversed", "dd": "boolean" },
|
||||
{
|
||||
"dt": "insert_anchor_links",
|
||||
"dd": "One of <kbd>left</kbd>, <kbd>right</kbd>, or <kbd>none</kbd>. Specifies whether an anchor-link should be provided for every header item. Probably overridable by the template."
|
||||
},
|
||||
{
|
||||
"dt": "in_search_index",
|
||||
"dd": "Include this section in the search index. Only matters if search is enabled"
|
||||
},
|
||||
{
|
||||
"dt": "transparent",
|
||||
"dd": "<kbd>true</kbd>/<kbd>false</kbd>, specifies if this section should be inherited by the parent"
|
||||
},
|
||||
{ "dt": "aliases", "dd": "An array of paths to redirect to this folder" },
|
||||
{ "dt": "[extra]", "dd": "Your extra data block" }
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
{
|
||||
"definitions": [
|
||||
{ "dt": "content", "dd": "The content of the <kbd>_index.md</kbd> file" },
|
||||
{ "dt": "title", "dd": "The Title found in the TOML part of <kbd>_index.md</kbd>" },
|
||||
{ "dt": "description", "dd": "(optional): The description" },
|
||||
{ "dt": "path", "dd": "As provided by Zola" },
|
||||
{ "dt": "components", "dd": "The path, split into atoms" },
|
||||
{ "dt": "permalink", "dd": "The URL for this page" },
|
||||
{ "dt": "extra", "dd": "The contents of the TOML's <kbd>[extra.*]</kbd> blocks." },
|
||||
{ "dt": "pages", "dd": "An array of all child pages <em>in this same folder</em>." },
|
||||
{ "dt": "subsections", "dd": "An array of all child sections <em>in this same folder</em>." },
|
||||
{
|
||||
"dt": "toc",
|
||||
"dd": "An array of <kbd>Header</kbd> objects: id, title, permalink, children (Which is itself an array of <kbd>Header</kbd> objects)"
|
||||
},
|
||||
|
||||
{ "dt": "word_count", "dd": "Unicode-smart." },
|
||||
{ "dt": "reading_time", "dd": "Number;" },
|
||||
{ "dt": "assets", "dd": "An array of assets available in this section." },
|
||||
{ "dt": "ancestors", "dd": "An array of parent paths, with the root being the last one." }
|
||||
]
|
||||
}
|
||||
|
|
@ -232,5 +232,17 @@ body {
|
|||
padding: var(--space-m) var(--space-s) var(--space-m-l) var(--space-s);
|
||||
flex: 0 0 auto;
|
||||
width: 56.25%;
|
||||
|
||||
dd {
|
||||
padding-left: var(--space-s);
|
||||
}
|
||||
|
||||
ul {
|
||||
padding-left: var(--step-0);
|
||||
}
|
||||
|
||||
pre {
|
||||
padding: var(--space-2xs);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,17 @@
|
|||
{% macro definition_table(source) %}
|
||||
<table>
|
||||
<tbody>
|
||||
{% for entry in source -%}
|
||||
<tr>
|
||||
<td><code>{{ entry.dt | safe }}</code></td>
|
||||
<td>{{ entry.dd | safe }}</td>
|
||||
</tr>
|
||||
{% if entry.definitions -%}
|
||||
<tr>
|
||||
<td colspan="2" class="sub-definition">{{ self::definition_table(source=entry.definitions) }}</td>
|
||||
</tr>
|
||||
{%- endif %}
|
||||
{% endfor %}
|
||||
</tbody>
|
||||
</table>
|
||||
{% endmacro %}
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
{%- import 'macros/definition_table.html' as renderer -%}
|
||||
<div>
|
||||
{% set content = load_data(path=source) %}
|
||||
{{ renderer::definition_table(source=content.definitions) }}
|
||||
</div>
|
||||
Loading…
Reference in New Issue