Added git commands.

This commit is contained in:
Elf M. Sternberg 2022-06-13 18:25:11 -07:00
parent 3a499aa5dd
commit d079e33c04
9 changed files with 253 additions and 86 deletions

View File

@ -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 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: of a project you want to place under source control and initialize it:
```shell ```bash
$ mkdir a-new-project $ mkdir a-new-project
$ touch README.md
$ git init $ git init
``` ```
This creates a new folder, `.git`, where Git will store your commit history and 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 ## Putting files into git
To put files under source control, you must add them. To update the entire 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: folder, switch to the root of the project and add _all_ of it:
```shell ```bash
$ git add . $ git add .
$ git commit $ 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 If your commit message could be a single line, you can add it directly from the
command line: command line:
```shell ```bash
$ git add . $ git add .
$ git commit -m "Updated the widget to widgetize." $ 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 repository. (Deleted files still exist in the history and can always be
recovered.) recovered.)
```shell ```bash
$ git commit -am "Updated the widget to widgetize." $ 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 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 keep your personal information and command aliases, which is one of three ways
you can add your own commands to Git. you can add your own commands to Git.
```shell ```bash
[user] [user]
name = Elf M. Sternberg name = Elf M. Sternberg
email = someguy@example.com email = someguy@example.com
@ -77,13 +79,68 @@ you can add your own commands to Git.
unstage = reset -q HEAD -- unstage = reset -q HEAD --
nevermind = !git reset --hard HEAD && git clean -d -f 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 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\" 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 ## Git Aliases {#aliases}
your commits to be attributed to the right person, you must have the `[user]`
block, and 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.

View File

@ -17,18 +17,20 @@ categories=["Web Development", "Static Site Generation", "Zola"]
collection of markdown documents in a folder-structured hierarchy, using a collection of markdown documents in a folder-structured hierarchy, using a
corresponding collection of HTML templates, which in turn use a corresponding corresponding collection of HTML templates, which in turn use a corresponding
collection of SASS collection and a collection of HTML templates. The templating 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 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. toolchains for those.
## Mental Model for Zola ## Mental Model for Zola
A website built with Zola originates with the `content/` folder. Inside that Elf, a website built with Zola originates with the `content/` folder. Inside
folder, every markdown document and every folder creates a corresponding page in that folder, every markdown document and every folder creates a corresponding
the constructed website. There are only *two* models you have to understand page in the constructed website. There are only *two* models you have to
Zola: *sections* and *pages*. understand Zola: *sections* and *pages*.
A *section* is a folder with a file named `_index.md` in it; note the 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 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 every other markdown document, arranged in the hierarchy described in the
`content` folder. `content` folder.
### Recommendation ### Proces Recommendation
1. Design your document hierarchy first. 1. Design your document hierarchy first.
2. Construct your content folder to support that hierarchy. 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. 5. Build the corresponding `Page` templates.
6. Worry about Sass afterward 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 ## Running Zola
Zola has only a few commands: 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 render the section info, otherwise Zola falls back to the default at
`./templates/section.html`. `./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: The arguments that con be placed into the TOML header of a the `_index.md` file are:
- `title`: a string {{ definition_list(source="zola/section_arguments.json") }}
- `description`: a string
- `draft`: `true`/`false` if this section should be included in builds #### Section Object delivered to the template:
- `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
The context for a section page contains the following fields, which will be The context for a section page contains the following fields, which will be
available to the template: available to the template:
- `content`: The content of the `_index.md` file {{ definition_list(source="zola/section_fields.json") }}
- `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.
### Pages {#page} ### 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 such as JavaScript or images, that you want to load alongside the content within
the markdown page. the markdown page.
#### Page Header in every page file
The following items can appear in the TOML header of a page: The following items can appear in the TOML header of a page:
- `title`: The title of this page. {{ definition_list(source="zola/page_arguments.json") }}
- `description`: A description of this page
- `date`: Date this page was published #### Page Object delivered to templates
- `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
Pages derive the following information in their context: Pages derive the following information in their context:
- `content`: The markdown content from the page's file {{ definition_list(source="zola/page_fields.json") }}
- `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.
### Pagination ### Pagination

View File

@ -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" }
]
}

View File

@ -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." }
]
}

View File

@ -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" }
]
}

View File

@ -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." }
]
}

View File

@ -232,5 +232,17 @@ body {
padding: var(--space-m) var(--space-s) var(--space-m-l) var(--space-s); padding: var(--space-m) var(--space-s) var(--space-m-l) var(--space-s);
flex: 0 0 auto; flex: 0 0 auto;
width: 56.25%; width: 56.25%;
dd {
padding-left: var(--space-s);
}
ul {
padding-left: var(--step-0);
}
pre {
padding: var(--space-2xs);
}
} }
} }

View File

@ -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 %}

View File

@ -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>