7 | {{ config.repo_name }}
8 |
9 |
10 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Exclude all files from root directory
2 | /*
3 |
4 | # ------------------------
5 | # Common project files
6 | !CHANGELOG.md
7 | !README.md
8 | !LICENSE
9 |
10 | # ------------------------
11 | # Include MkDocs files
12 | !docs/
13 | !includes/
14 | !overrides/
15 | !mkdocs.yml
16 |
17 | # ------------------------
18 | # Project automation
19 | !Makefile
20 |
21 | # ------------------------
22 | # Version Control
23 | !.gitignore
24 | !.gitattributes
25 | !.github/
26 |
27 |
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | ## Unreleased
4 | ### Added
5 | - dev: ci scheduled stale issue & pr check (monthly)
6 |
7 | ### Changed
8 | - ci: spell lychee & repository trufflehog linters warn only (false positives)
9 |
10 |
11 | ## 2023-03-10
12 | ### Added
13 | - started a changelog
14 |
15 | ### Changed
16 | - [#90](https://github.com/practicalli/clojurescript/issues/90) convert ClojureScript book to MkDocs
17 | - Update figwheel logo name
18 | - Update ClojureScript REPL workflow image
19 |
--------------------------------------------------------------------------------
/docs/git/tips/creating-a-branch.md:
--------------------------------------------------------------------------------
1 | title: Managing Changes with Branches
2 | ---
3 |
4 | ## Why Branch
5 |
6 | * an easy way to experiment with code, as a branch can easily be discarded
7 | * Branches help you merge specific commits into another branch
8 | * Allows you to keep all your code in commits all the time.
9 | * Branching is quick and relatively simple
10 |
11 |
12 | ## How to Branch
13 |
14 | - should already be covered in the [Git Basics](/git-basics) Workshop
15 |
16 | ## Erm
17 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-tips/creating-a-branch.md:
--------------------------------------------------------------------------------
1 | title: Managing Changes with Branches
2 | ---
3 |
4 | ## Why Branch
5 |
6 | * an easy way to experiment with code, as a branch can easily be discarded
7 | * Branches help you merge specific commits into another branch
8 | * Allows you to keep all your code in commits all the time.
9 | * Branching is quick and relatively simple
10 |
11 |
12 | ## How to Branch
13 |
14 | - should already be covered in the [Git Basics](/git-basics) Workshop
15 |
16 | ## Erm
17 |
--------------------------------------------------------------------------------
/docs/git/tips/understanding-hunks.md:
--------------------------------------------------------------------------------
1 | title: Understanding Hunks in Git
2 | ---
3 |
4 | A hunk in Git terms is a line or several consecutive lines of a file that have changed since the last commit.
5 |
6 | Git identifies hunks in the files you change and when you use interactive staging you can be more selective about the hunks you add to the next commit.
7 |
8 | git add -p
9 |
10 |
11 | [Examples of hunks]
12 |
13 |
14 | ## Splitting Hunks
15 |
16 | [TODO] how does git decide where to split Hunks ?
17 |
18 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-tips/understanding-hunks.md:
--------------------------------------------------------------------------------
1 | title: Understanding Hunks in Git
2 | ---
3 |
4 | A hunk in Git terms is a line or several consecutive lines of a file that have changed since the last commit.
5 |
6 | Git identifies hunks in the files you change and when you use interactive staging you can be more selective about the hunks you add to the next commit.
7 |
8 | git add -p
9 |
10 |
11 | [Examples of hunks]
12 |
13 |
14 | ## Splitting Hunks
15 |
16 | [TODO] how does git decide where to split Hunks ?
17 |
18 |
--------------------------------------------------------------------------------
/.github/config/markdown-link-check.json:
--------------------------------------------------------------------------------
1 | {
2 | "ignorePatterns": [
3 | {
4 | "pattern": "^http://localhost"
5 | },
6 | {
7 | "pattern": "^mailto:*"
8 | },
9 | {
10 | "pattern": "^#*"
11 | },
12 | {
13 | "pattern": "^https://127.0.0.0/"
14 | }
15 | ],
16 | "timeout": "20s",
17 | "retryOn429": true,
18 | "retryCount": 5,
19 | "fallbackRetryDelay": "30s",
20 | "aliveStatusCodes": [
21 | 200,
22 | 206
23 | ]
24 | }
25 |
--------------------------------------------------------------------------------
/.github/config/gitleaks.toml:
--------------------------------------------------------------------------------
1 | title = "gitleaks config"
2 |
3 | [allowlist]
4 | description = "global allow lists"
5 | paths = [
6 | '''gitleaks.toml''',
7 | '''(.*?)(jpg|gif|doc|docx|zip|xls|pdf|bin|svg|socket)$''',
8 | '''(go.mod|go.sum)$''',
9 | '''gradle.lockfile''',
10 | '''node_modules''',
11 | '''package-lock.json''',
12 | '''pnpm-lock.yaml''',
13 | '''Database.refactorlog''',
14 | '''vendor''',
15 | ]
16 |
17 | [[rules]]
18 | description = "AWS Example API Key"
19 | id = "aws-example-api-key"
20 | regex = '''AKIAIOSFODNN7EXAMPLE'''
21 | keywords = [
22 | "awstoken",
23 | ]
24 |
--------------------------------------------------------------------------------
/.github/FUNDING.yaml:
--------------------------------------------------------------------------------
1 | ---
2 | # GitHub Supported funding model platforms
3 |
4 | github: [practicali-john]
5 | # patreon: # Replace with a single Patreon username
6 | # open_collective: # Replace with a single Open Collective username
7 | # ko_fi: # Replace with a single Ko-fi username
8 | # tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
9 | # community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
10 | # liberapay: # Replace with a single Liberapay username
11 | # issuehunt: # Replace with a single IssueHunt username
12 | # otechie: # Replace with a single Otechie username
13 | # custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
14 |
--------------------------------------------------------------------------------
/docs/git/creating-a-branch.md:
--------------------------------------------------------------------------------
1 | # Branch & merge
2 |
3 | Unless branches represent a completely isolated component in your project, then branches should be short lived. This makes them easier to work with, easier to merge and easier to get rid of when you dont need them.
4 |
5 | Rebasing (I dont like doing this on shared repos, your loosing tracability because you are rewriting history). There may be some merit when a team is working very closely on the same part of the code, where there is a lot of communicaton going on.
6 |
7 |
8 | Can use ... from labs to automatically deploy onto heroku from Github - probably dont want to do this for production - or at least make sure than anyone who triggers an automatic deploy knows that they are doing so.
9 |
10 |
11 | [Back to top...](#top)
12 |
13 | [Workshop homepage](index.html)
14 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/creating-a-branch.md:
--------------------------------------------------------------------------------
1 | # Branch & merge
2 |
3 | Unless branches represent a completely isolated component in your project, then branches should be short lived. This makes them easier to work with, easier to merge and easier to get rid of when you dont need them.
4 |
5 | Rebasing (I dont like doing this on shared repos, your loosing tracability because you are rewriting history). There may be some merit when a team is working very closely on the same part of the code, where there is a lot of communicaton going on.
6 |
7 |
8 | Can use ... from labs to automatically deploy onto heroku from Github - probably dont want to do this for production - or at least make sure than anyone who triggers an automatic deploy knows that they are doing so.
9 |
10 |
11 | [Back to top...](#top)
12 |
13 | [Workshop homepage](index.html)
14 |
--------------------------------------------------------------------------------
/docs/git/create-your-project.md:
--------------------------------------------------------------------------------
1 | title: Creating a Git version controlled project
2 | ---
3 |
4 | Create a new folder / project by either creating the project structure yourself or using a build tool to create it for you. Here are some of the example build tools you could use:
5 |
6 | ## Node project
7 | npm init
8 |
9 | ## Node project via Grunt-init
10 | grunt-init my-template
11 |
12 | ## Project via Yoman generator
13 | yo generator
14 |
15 | ## Java project with Maven
16 | mvn new my-project
17 |
18 | ## Clojure project with Leiningen
19 | lein new my-project
20 |
21 | ## Scala project using Play framework
22 | play new my-project
23 |
24 |
25 | Now you can see all the files you have created as untracked files in git using
26 |
27 | git status
28 |
29 |
30 | Show example screenshots of git status output for the above projects
31 |
32 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/create-your-project.md:
--------------------------------------------------------------------------------
1 | title: Creating a Git version controlled project
2 | ---
3 |
4 | Create a new folder / project by either creating the project structure yourself or using a build tool to create it for you. Here are some of the example build tools you could use:
5 |
6 | ## Node project
7 | npm init
8 |
9 | ## Node project via Grunt-init
10 | grunt-init my-template
11 |
12 | ## Project via Yoman generator
13 | yo generator
14 |
15 | ## Java project with Maven
16 | mvn new my-project
17 |
18 | ## Clojure project with Leiningen
19 | lein new my-project
20 |
21 | ## Scala project using Play framework
22 | play new my-project
23 |
24 |
25 | Now you can see all the files you have created as untracked files in git using
26 |
27 | git status
28 |
29 |
30 | Show example screenshots of git status output for the above projects
31 |
32 |
--------------------------------------------------------------------------------
/docs/git/chapter10-collaborating-with-github.md:
--------------------------------------------------------------------------------
1 | # Collaborating with Github
2 |
3 |
4 | Everyone has their own repository locally
5 |
6 | Everyone has their own local development environment - using their ide & foreman
7 |
8 | Developers can spin up another application on heroku as a different environment. Every time a new heorku app is created, a new git repository is created. This gives a lot of flexibility when it comes to managing changes, although you need to manage the progression of your changes through each repository.
9 |
10 | Using git log --decorate you can see the relative progression of your changes as commits to each repositories.
11 |
12 | When you are working with multiple heroku applications, then using environment variables will allow you to manage resource configuration in each environment. Hard coding configuration information in your application will not lead to a very secure, stable or scalable application.
13 |
14 |
15 |
16 | [Back to top...](#top)
17 |
18 | [Workshop homepage](index.html)
19 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/chapter10-collaborating-with-github.md:
--------------------------------------------------------------------------------
1 | # Collaborating with Github
2 |
3 |
4 | Everyone has their own repository locally
5 |
6 | Everyone has their own local development environment - using their ide & foreman
7 |
8 | Developers can spin up another application on heroku as a different environment. Every time a new heorku app is created, a new git repository is created. This gives a lot of flexibility when it comes to managing changes, although you need to manage the progression of your changes through each repository.
9 |
10 | Using git log --decorate you can see the relative progression of your changes as commits to each repositories.
11 |
12 | When you are working with multiple heroku applications, then using environment variables will allow you to manage resource configuration in each environment. Hard coding configuration information in your application will not lead to a very secure, stable or scalable application.
13 |
14 |
15 |
16 | [Back to top...](#top)
17 |
18 | [Workshop homepage](index.html)
19 |
--------------------------------------------------------------------------------
/.github/config/lychee.toml:
--------------------------------------------------------------------------------
1 |
2 | # ----------------------------------------
3 | # Base URL or website root directory to check relative URLs.
4 | base = "https://practical.li/gitops"
5 |
6 | # Only test links with the given schemes (e.g. https).
7 | # Omit to check links with any other scheme.
8 | # At the moment, we support http, https, file, and mailto.
9 | scheme = ["https"]
10 |
11 | # ----------------------------------------
12 | # Exclusions
13 |
14 | # Exclude URLs and mail addresses from checking (supports regex).
15 | exclude = ['^https://127.0.0.0', '^https://www\.linkedin\.com', '^https://web\.archive\.org/web/']
16 |
17 | # Exclude these filesystem paths from getting checked.
18 | exclude_path = ["mkdocs.yml", "overrides", "includes", ".github", ".git"]
19 |
20 | # Exclude all private IPs from checking.
21 | # Equivalent to setting `exclude_private`, `exclude_link_local`, and
22 | # `exclude_loopback` to true.
23 | exclude_all_private = true
24 |
25 | # Check mail addresses
26 | include_mail = false
27 | # ----------------------------------------
28 |
--------------------------------------------------------------------------------
/overrides/404.html:
--------------------------------------------------------------------------------
1 |
4 |
5 |
6 | {% extends "main.html" %}
7 |
8 |
9 | {% block content %}
10 | This is not the page you are looking for
11 | 12 |13 | Sorry we have arrived at a page that does not exist... 14 |
15 | 16 |17 | Practicalli GitOps is at a very early stage 18 |
19 | 20 |21 | Use the Search bar at the top of the page or left navigation to find the relevant content. 22 |
23 | 24 | 39 | 40 | {% endblock %} 41 | -------------------------------------------------------------------------------- /docs/git/to-review/git-basics/configure-git.md: -------------------------------------------------------------------------------- 1 | title: Identify yourself to Git 2 | --- 3 | 4 | There are lots of useful things to add to your git configuration. The most important thing is to set up your git user name and email, so people know who is creating commits. To add your username and email to git, either edit the `~/.gitconfig` file or run the following two commands: 5 | 6 | git config --global user.name "your name" 7 | git config --global user.email "your.name@domain.com" 8 | 9 | > You should use the same email address you have used for your Github account to make things easier. 10 | 11 | To check what has already been added to Git (some gui clients add information to your gitconfig), you can list all the current configuration entries using the command: 12 | 13 | git config --list 14 | 15 | 16 | Later in this workshop we will see how to set up aliases for the commands and options you regularly use. We will also show how to set up specify tools for merging changes and viewing *diffs* (differences between files and commits). 17 | 18 | Read the [official documentation on git customisation](http://git-scm.com/book/en/Customizing-Git-Git-Configuration) for more options. 19 | 20 | -------------------------------------------------------------------------------- /docs/git/ignoring-files.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Ignoring files 4 | 5 | There are often files inside your project that you do not want to put into git, these typically includes 6 | 7 | * Backup files 8 | * Developer tool configurations 9 | * Compiled source code 10 | * Graphics, sound and video files 11 | * Binary document formats 12 | 13 | Telling Git to exclude these types of files will prevent them appearing in your git status report as *untracked files* and help you focus on managing those files that should be versioned. 14 | 15 | You can add your project exclusions using filennames, folders and filename patterns. All these exclusions go into a project file called 16 | 17 | my-project-folder/.gitignore 18 | 19 | To keep your project .gitignore file simple and focused on the project, any files and patterns you want to ignore that are created by your own development environment (IDE, build tools, etc.) should be placed in a global ignore file, typically: 20 | 21 | ~/.gitignore_global 22 | 23 | Github has a [large collection of .gitignore files](https://github.com/github/gitignore/) for different programming languages and tools. 24 | 25 | [Back to top...](#top) 26 | 27 | [Workshop homepage](index.html) 28 | -------------------------------------------------------------------------------- /docs/git/to-review/git-basics/ignoring-files.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Ignoring files 4 | 5 | There are often files inside your project that you do not want to put into git, these typically includes 6 | 7 | * Backup files 8 | * Developer tool configurations 9 | * Compiled source code 10 | * Graphics, sound and video files 11 | * Binary document formats 12 | 13 | Telling Git to exclude these types of files will prevent them appearing in your git status report as *untracked files* and help you focus on managing those files that should be versioned. 14 | 15 | You can add your project exclusions using filennames, folders and filename patterns. All these exclusions go into a project file called 16 | 17 | my-project-folder/.gitignore 18 | 19 | To keep your project .gitignore file simple and focused on the project, any files and patterns you want to ignore that are created by your own development environment (IDE, build tools, etc.) should be placed in a global ignore file, typically: 20 | 21 | ~/.gitignore_global 22 | 23 | Github has a [large collection of .gitignore files](https://github.com/github/gitignore/) for different programming languages and tools. 24 | 25 | [Back to top...](#top) 26 | 27 | [Workshop homepage](index.html) 28 | -------------------------------------------------------------------------------- /docs/git/to-review/git-basics/git-in-2-minutes.md: -------------------------------------------------------------------------------- 1 | title: Git in 2 minutes 2 | date: 2014-08-24 18:22:00 3 | --- 4 | 5 | If you have installed Git and know the basic theory of version control, here are the basic commands to get you going: 6 | 7 | ;; Tell Git who you are (only done once) 8 | git config --global user.name "your name" 9 | git config --global user.email "your.name@domain.com" 10 | 11 | ;; Initialise a local repository (inside your project directlory) 12 | git init 13 | 14 | ;; See the status of your files and all uncommited changes 15 | git status 16 | 17 | ;; Tell Git which changes you want to make part of the next commit (staging) 18 | git add filename ; to add a specific file 19 | git add . ; to add everything 20 | git add *.HTML ; add all html files 21 | 22 | ;; Commit those files to create a new version 23 | git commit -m "meaningful commit message" 24 | 25 | ;; Push your code to a remote repository (eg. Github) 26 | git remote add repo-name git@github.com:github-account/repo-name.git 27 | git push repo-name master 28 | 29 | 30 | > The `;` character is a comment 31 | 32 | To see the basics of Git useage visualised, here is a diagram of the local git workflow: 33 | 34 |
35 |
36 |
37 |
38 |
--------------------------------------------------------------------------------
/overrides/partials/palette.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
37 |
--------------------------------------------------------------------------------
/docs/git/git-clients.md:
--------------------------------------------------------------------------------
1 | title: Choose your git client
2 | ---
3 |
4 | For the workshop the command line will be used so you can focus on understanding the commands that are used.
5 |
6 | You can follow along with either a command line or graphical git tool. Please note that installing a graphical tool for git should also provide git on the command line, so no need to install both!
7 |
8 | ## Command Line tools
9 |
10 | You can simply install the git command line tools from [www.git-scm.com](http://www.gitscm.com).
11 |
12 | If you have Ubuntu, then you can use the Ubuntu software center or install git on the command line
13 |
14 | apt-get install git
15 |
16 |
17 | ## GUI tools
18 |
19 | The simplest graphical tools to install are from Github. If you browse any repository on [www.github.com](https://www.github.com) you will notice a "Clone in Mac" or "Clone in Windows" button at the top left of the page. If you have not Git tool installed, then you are redirected to a page offering to install the Github graphical git client for you.
20 |
21 | [Github client for MacOSX](http://mac.github.com/)
22 | [Github client for Microsoft Windows](http://windows.github.com/)
23 |
24 | There are many other Git GUI tools listed on [git-scm.com](http://git-scm.com/downloads/guis) for Linux, MacOSX and Windows. A very comprehensive Git GUI is [SourceTree for MacOSX & Windows](http://www.sourcetreeapp.com/)
25 |
26 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/git-clients.md:
--------------------------------------------------------------------------------
1 | title: Choose your git client
2 | ---
3 |
4 | For the workshop the command line will be used so you can focus on understanding the commands that are used.
5 |
6 | You can follow along with either a command line or graphical git tool. Please note that installing a graphical tool for git should also provide git on the command line, so no need to install both!
7 |
8 | ## Command Line tools
9 |
10 | You can simply install the git command line tools from [www.git-scm.com](http://www.gitscm.com).
11 |
12 | If you have Ubuntu, then you can use the Ubuntu software center or install git on the command line
13 |
14 | apt-get install git
15 |
16 |
17 | ## GUI tools
18 |
19 | The simplest graphical tools to install are from Github. If you browse any repository on [www.github.com](https://www.github.com) you will notice a "Clone in Mac" or "Clone in Windows" button at the top left of the page. If you have not Git tool installed, then you are redirected to a page offering to install the Github graphical git client for you.
20 |
21 | [Github client for MacOSX](http://mac.github.com/)
22 | [Github client for Microsoft Windows](http://windows.github.com/)
23 |
24 | There are many other Git GUI tools listed on [git-scm.com](http://git-scm.com/downloads/guis) for Linux, MacOSX and Windows. A very comprehensive Git GUI is [SourceTree for MacOSX & Windows](http://www.sourcetreeapp.com/)
25 |
26 |
--------------------------------------------------------------------------------
/.github/pull_request_template.md:
--------------------------------------------------------------------------------
1 | :memo: Description
2 |
3 |
4 | :white_check_mark: Checklist
5 |
6 | - [ ] Commits should be cryptographically signed (SSH or GPG)
7 |
8 |
9 | ## Practicalli Guidelines
10 |
11 | Please follow these guidelines when submitting a pull request
12 |
13 | - refer to all relevant issues, using `#` followed by the issue number (or paste full link to the issue)
14 | - PR should contain the smallest possible change
15 | - PR should contain a very specific change
16 | - PR should contain only a single commit (squash your commits locally if required)
17 | - Avoid multiple changes across multiple files (raise an issue so we can discuss)
18 | - Avoid a long list of spelling or grammar corrections. These take too long to review and cherry pick.
19 |
20 | ## Submitting articles
21 |
22 | [Create an issue using the article template](https://github.com/practicalli/blog-content/issues/new?assignees=&labels=article&template=article.md&title=Suggested+article+title),
23 | providing as much detail as possible.
24 |
25 | ## Website design
26 |
27 | Suggestions about website design changes are most welcome, especially in terms of usability and accessibility.
28 |
29 | Please raise an issue so we can discuss changes first, especially changes related to aesthetics.
30 |
31 | ## Review process
32 |
33 | All pull requests are reviewed by @practicalli-johnny and feedback provided, usually the same day but please be patient.
34 |
--------------------------------------------------------------------------------
/.github/workflows/changelog-check.yaml:
--------------------------------------------------------------------------------
1 | ---
2 | # Check CHANGELOG.md file updated for every pull request
3 |
4 | name: Changelog Check
5 | on:
6 | pull_request:
7 | paths-ignore:
8 | - "README.md"
9 | types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
10 |
11 | jobs:
12 | changelog:
13 | name: Changelog Update Check
14 | runs-on: ubuntu-latest
15 | steps:
16 | - run: echo "🚀 Job automatically triggered by ${{ github.event_name }}"
17 | - run: echo "🐧 Job running on ${{ runner.os }} server"
18 | - run: echo "🐙 Using ${{ github.ref }} branch from ${{ github.repository }} repository"
19 |
20 | # Git Checkout
21 | - name: Checkout Code
22 | uses: actions/checkout@v4
23 | with:
24 | fetch-depth: 0
25 | sparse-checkout: |
26 | docs
27 | overrides
28 | .github
29 | CHANGELOG.md
30 | - run: echo "🐙 Sparse Checkout of ${{ github.repository }} repository to the CI runner."
31 |
32 | # Changelog Enforcer
33 | - name: Changelog Enforcer
34 | uses: dangoslen/changelog-enforcer@v3
35 | with:
36 | changeLogPath: "CHANGELOG.md"
37 | skipLabels: "skip-changelog-check"
38 |
39 | # Summary and status
40 | - run: echo "🎨 Changelog Enforcer quality checks completed"
41 | - run: echo "🍏 Job status is ${{ job.status }}."
42 |
--------------------------------------------------------------------------------
/docs/git/index.md:
--------------------------------------------------------------------------------
1 | # Git Client
2 |
3 | Git binary is available in most good operating systems or from [Git SCM website](https://git-scm.com/){target=_blank}
4 |
5 |
6 | ## Quick Start
7 |
8 | Configure Git identity
9 |
10 | ```shell
11 | git config --global user.name "your name"
12 | git config --global user.email "your.name@domain.com"
13 | ```
14 |
15 | !!! HINT "Anonymise email for user"
16 | GitHub user account **Settings** > **Emails** has an option to use a `@users.noreply.github.com` address rather than the real email address.
17 |
18 | The noreply address should be set as the `user.email` configuration.
19 |
20 |
21 | Initialise a local repository (inside your project directlory)
22 |
23 | ```shell
24 | git init
25 | ```
26 |
27 | Status of your files and all uncommited changes
28 |
29 | ```shell
30 | git status
31 | ```
32 |
33 | Tell Git which changes you want to make part of the next commit (staging)
34 |
35 | ```shell
36 | git add filename ; to add a specific file
37 | git add . ; to add everything
38 | git add *.HTML ; add all html files
39 | ```
40 |
41 | Commit those files to create a new version
42 |
43 | ```shell
44 | git commit -m "meaningful commit message"
45 | ```
46 |
47 | Push your code to a remote repository (eg. Github)
48 |
49 | ```shell
50 | git remote add repo-name git@github.com:github-account/repo-name.git
51 | git push repo-name master
52 | ```
53 |
54 |
55 |
56 |
--------------------------------------------------------------------------------
/docs/git/tips/common-pitfalls.md:
--------------------------------------------------------------------------------
1 | title: Git Common Pitfalls
2 | ---
3 |
4 | Here are some common pitfalls that people experience when using git and of course ways to dig yourself out of them.
5 |
6 | ## Loosing your head
7 |
8 | Confusing Git leads to your confusion
9 |
10 |
11 | ## Staging and Commiting to the wrong branch
12 |
13 | [Undo a commit to a local branch ]
14 |
15 | If using the command line for git, enhance your prompt to display the current branch you are on.
16 |
17 | Use Git status ....
18 |
19 | Learn how to use your git tool well, so that it visualises the current branch you are on or asks / checks you are pushing to the correct branch.
20 |
21 |
22 |
23 | ## Pushing to the wrong repository
24 |
25 | Warn everyone immediately, the longer you wait the more pain people will feel.
26 |
27 | Best approach is to create a new commit that resolved the problem you just created.
28 |
29 |
30 | ## Staging the wrong files
31 |
32 | Learn to use git diff well to see the changes before you add them.
33 |
34 | Use git status to see which files have been modified and which ones you have addded.
35 |
36 | [Undo staging a file, when tracked and untracked]
37 |
38 |
39 | ## Staging unwanted changes in a file
40 |
41 | - eg whitespace, formatting changes
42 |
43 | Use `git add -p filename` to select only the lines (hunks) you want to stage.
44 |
45 | Use `git checkout filename` to reset the file to be the same as that committed in Git, wiping out any unwanted changes (perhaps made by mistake or by your code writing tools).
46 |
47 |
48 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-tips/common-pitfalls.md:
--------------------------------------------------------------------------------
1 | title: Git Common Pitfalls
2 | ---
3 |
4 | Here are some common pitfalls that people experience when using git and of course ways to dig yourself out of them.
5 |
6 | ## Loosing your head
7 |
8 | Confusing Git leads to your confusion
9 |
10 |
11 | ## Staging and Commiting to the wrong branch
12 |
13 | [Undo a commit to a local branch ]
14 |
15 | If using the command line for git, enhance your prompt to display the current branch you are on.
16 |
17 | Use Git status ....
18 |
19 | Learn how to use your git tool well, so that it visualises the current branch you are on or asks / checks you are pushing to the correct branch.
20 |
21 |
22 |
23 | ## Pushing to the wrong repository
24 |
25 | Warn everyone immediately, the longer you wait the more pain people will feel.
26 |
27 | Best approach is to create a new commit that resolved the problem you just created.
28 |
29 |
30 | ## Staging the wrong files
31 |
32 | Learn to use git diff well to see the changes before you add them.
33 |
34 | Use git status to see which files have been modified and which ones you have addded.
35 |
36 | [Undo staging a file, when tracked and untracked]
37 |
38 |
39 | ## Staging unwanted changes in a file
40 |
41 | - eg whitespace, formatting changes
42 |
43 | Use `git add -p filename` to select only the lines (hunks) you want to stage.
44 |
45 | Use `git checkout filename` to reset the file to be the same as that committed in Git, wiping out any unwanted changes (perhaps made by mistake or by your code writing tools).
46 |
47 |
48 |
--------------------------------------------------------------------------------
/docs/git/tips/branching-stragegies.md:
--------------------------------------------------------------------------------
1 | title: Branching Stragegies
2 | ---
3 |
4 | Previously we discussed what a branch is in Git, how they are created and how to switch between branches. Now we will discuss different approaches to using branches, from the very simple to the complex.
5 |
6 | ## Local Branches only Strategy
7 |
8 | Branches created locally. Any changes to be shared are merged into the master branch first then that master branch is pushed to a common repository.
9 |
10 | ### Advantages
11 | * Very simple to use.
12 | * Only 1 branch to keep in sync with everyone else.
13 |
14 | ### Limitations
15 |
16 |
17 | ## Github Pull Model
18 |
19 | Branches created locally. Any changes to be shared are merged into the master branch first then that master branch is pushed to a common repository.
20 |
21 | ### Advantages
22 | * Quite simple to use.
23 | * Can work with multiple shared branches
24 | * Provides easy way to review, discuss and document changes
25 |
26 | ### Limitations
27 | * Requires a services such as Github that supports pull requests
28 |
29 |
30 | ## Git Flow
31 |
32 | ...
33 |
34 | ### Advantages
35 | * It makes you learn git really well
36 | * It can help with larger teams
37 |
38 | ### Limitations
39 | * It may be overkill
40 | * Learning curve for adoption, not to be rushed into
41 | * Need to ensure everyone understands the flow, human error easily introduced
42 | * Relying on tools to manage the flow can mean problems harder to fix if something goes wrong, as people may not understand the flow enough.
43 |
44 |
45 |
46 | See the [Git Flow section](git-flow.html) for more details.
47 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-tips/branching-stragegies.md:
--------------------------------------------------------------------------------
1 | title: Branching Stragegies
2 | ---
3 |
4 | Previously we discussed what a branch is in Git, how they are created and how to switch between branches. Now we will discuss different approaches to using branches, from the very simple to the complex.
5 |
6 | ## Local Branches only Strategy
7 |
8 | Branches created locally. Any changes to be shared are merged into the master branch first then that master branch is pushed to a common repository.
9 |
10 | ### Advantages
11 | * Very simple to use.
12 | * Only 1 branch to keep in sync with everyone else.
13 |
14 | ### Limitations
15 |
16 |
17 | ## Github Pull Model
18 |
19 | Branches created locally. Any changes to be shared are merged into the master branch first then that master branch is pushed to a common repository.
20 |
21 | ### Advantages
22 | * Quite simple to use.
23 | * Can work with multiple shared branches
24 | * Provides easy way to review, discuss and document changes
25 |
26 | ### Limitations
27 | * Requires a services such as Github that supports pull requests
28 |
29 |
30 | ## Git Flow
31 |
32 | ...
33 |
34 | ### Advantages
35 | * It makes you learn git really well
36 | * It can help with larger teams
37 |
38 | ### Limitations
39 | * It may be overkill
40 | * Learning curve for adoption, not to be rushed into
41 | * Need to ensure everyone understands the flow, human error easily introduced
42 | * Relying on tools to manage the flow can mean problems harder to fix if something goes wrong, as people may not understand the flow enough.
43 |
44 |
45 |
46 | See the [Git Flow section](git-flow.html) for more details.
47 |
--------------------------------------------------------------------------------
/.github/workflows/scheduled-version-check.yaml:
--------------------------------------------------------------------------------
1 | ---
2 | # ------------------------------------------
3 | # Scheduled check of versions
4 | # - use as non-urgent report on versions
5 | # - Uses POSIX Cron syntax
6 | # - Minute [0,59]
7 | # - Hour [0,23]
8 | # - Day of the month [1,31]
9 | # - Month of the year [1,12]
10 | # - Day of the week ([0,6] with 0=Sunday)
11 | #
12 | # Using liquidz/anta to check:
13 | # - GitHub workflows
14 | # - deps.edn
15 | # ------------------------------------------
16 |
17 | name: "Scheduled Version Check"
18 | on:
19 | schedule:
20 | # - cron: "0 4 * * *" # at 04:04:04 ever day
21 | # - cron: "0 4 * * 5" # at 04:04:04 ever Friday
22 | - cron: "0 4 1 * *" # at 04:04:04 on first day of month
23 | workflow_dispatch: # Run manually via GitHub Actions Workflow page
24 |
25 | jobs:
26 | scheduled-version-check:
27 | name: "Scheduled Version Check"
28 | runs-on: ubuntu-latest
29 | steps:
30 | - run: echo "🚀 Job automatically triggered by ${{ github.event_name }}"
31 | - run: echo "🐧 Job running on ${{ runner.os }} server"
32 | - run: echo "🐙 Using ${{ github.ref }} branch from ${{ github.repository }} repository"
33 |
34 | - name: Checkout Code
35 | uses: actions/checkout@v4
36 | with:
37 | fetch-depth: 0
38 | sparse-checkout: |
39 | .github
40 | - run: echo "🐙 ${{ github.repository }} repository sparse-checkout to the CI runner."
41 | - name: "Antq Check versions"
42 | uses: liquidz/antq-action@main
43 | with:
44 | excludes: ""
45 | skips: "boot clojure-cli pom shadow-cljs leiningen"
46 |
47 | # Summary
48 | - run: echo "🎨 library versions checked with liquidz/antq"
49 | - run: echo "🍏 Job status is ${{ job.status }}."
50 |
--------------------------------------------------------------------------------
/.github/workflows/publish-book.yaml:
--------------------------------------------------------------------------------
1 | ---
2 | name: Publish Book
3 | on:
4 | # Manually trigger workflow
5 | workflow_dispatch:
6 |
7 | # Run work flow conditional on linter workflow success
8 | workflow_run:
9 | workflows:
10 | - "MegaLinter"
11 | paths:
12 | - "docs/**"
13 | - "includes/**"
14 | - "overrides/**"
15 | - "mkdocs.yaml"
16 | branches:
17 | - main
18 | types:
19 | - completed
20 |
21 | permissions:
22 | contents: write
23 |
24 | jobs:
25 | publish-book:
26 | name: MkDocs Publish
27 | runs-on: ubuntu-latest
28 | steps:
29 | - run: echo "🚀 Job automatically triggered by ${{ github.event_name }}"
30 | - run: echo "🐧 Job running on ${{ runner.os }} server"
31 | - run: echo "🐙 Using ${{ github.ref }} branch from ${{ github.repository }} repository"
32 |
33 | - name: Checkout Code
34 | uses: actions/checkout@v4
35 | with:
36 | fetch-depth: 0
37 | sparse-checkout: |
38 | docs
39 | includes
40 | overrides
41 | - run: echo "🐙 ${{ github.repository }} repository sparse-checkout to the CI runner."
42 |
43 | - name: Setup Python
44 | uses: actions/setup-python@v5
45 | with:
46 | python-version: 3.x
47 |
48 | - name: Cache
49 | uses: actions/cache@v4
50 | with:
51 | key: ${{ github.ref }}
52 | path: .cache
53 |
54 | - run: pip install mkdocs-material mkdocs-callouts mkdocs-glightbox mkdocs-git-revision-date-localized-plugin mkdocs-redirects pillow cairosvg
55 | - run: mkdocs gh-deploy --force
56 | - run: echo "🐙 ."
57 |
58 | # Summary and status
59 | - run: echo "🎨 MkDocs Publish Book workflow completed"
60 | - run: echo "🍏 Job status is ${{ job.status }}."
61 |
--------------------------------------------------------------------------------
/docs/git/check-changes.md:
--------------------------------------------------------------------------------
1 | # Check For Changes
2 |
3 | Git provides several commands to help you see changes in your project files, helping you manage your project easily and helping you capture small and coheirent changes.
4 |
5 | ## Git Status
6 |
7 | Even experienced Git users will run the `git status` command very frequently. This command gives you an overview of all the files that contain changes, changes that have been staged and any files Git is not currenly tracking
8 |
9 | > untracked files are those that have not been added to the Git repository
10 |
11 | If you are using a GUI client for Git, it may be running `git status` regularly in the background so the information it is displaying is up to date.
12 |
13 | Git status only shows the changes happening locally, it will not show changes on any remote repository (ie. on Github). See the section on `git log` for tracking changes in remote repositories.
14 |
15 |
16 | ## Git Diff
17 |
18 | Compare changes between the working copy and the staging area. You can compare all files in the project or just the changes in a specific file or filename pattern
19 |
20 | ```shell
21 | git diff
22 | git diff filename
23 | git diff *.md
24 | ```
25 |
26 | Compare changes between the staging area and the latest commit
27 |
28 | ```shell
29 | git diff --cached
30 | git diff filename --cached
31 | git diff *.md --cached
32 | ```
33 |
34 | Compare changes against a specific commit (version)
35 |
36 | ```shell
37 | git diff v1.09 ; compare working directory against specific version
38 | git diff dev master ; difference between two branches
39 | ```
40 |
41 | Using the `--stat` option to see just the statistics about the changes - eg, you want to see the number of changes rather than all the change details.
42 |
43 | ```shell
44 | git diff v1.09 --stat
45 | ```
46 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/checking-for-changes.md:
--------------------------------------------------------------------------------
1 | title: Checking for Changes
2 | ---
3 |
4 | Git provides several commands to help you see changes in your project files, helping you manage your project easily and helping you capture small and coheirent changes.
5 |
6 | ## Git Status
7 |
8 | Even experienced Git users will run the `git status` command very frequently. This command gives you an overview of all the files that contain changes, changes that have been staged and any files Git is not currenly tracking
9 |
10 | > untracked files are those that have not been added to the Git repository
11 |
12 | If you are using a GUI client for Git, it may be running `git status` regularly in the background so the information it is displaying is up to date.
13 |
14 | Git status only shows the changes happening locally, it will not show changes on any remote repository (ie. on Github). See the section on `git log` for tracking changes in remote repositories.
15 |
16 | {% note info Exercise 1 %}
17 | This is a note, I wonder if it works. Yes it does, but it looks just like a blockquote using the > notation
18 | {% endnote %}
19 |
20 | ## Git Diff
21 |
22 | Compare changes between the working copy and the staging area. You can compare all files in the project or just the changes in a specific file or filename pattern
23 |
24 | git diff
25 | git diff filename
26 | git diff *.md
27 |
28 |
29 | Compare changes between the staging area and the latest commit
30 |
31 | git diff --cached
32 | git diff filename --cached
33 | git diff *.md --cached
34 |
35 |
36 | Compare changes against a specific commit (version)
37 |
38 | git diff v1.09 ; compare working directory against specific version
39 | git diff dev master ; difference between two branches
40 |
41 |
42 | Using the `--stat` option to see just the statistics about the changes - eg, you want to see the number of changes rather than all the change details.
43 |
44 | git diff v1.09 --stat
45 |
46 |
--------------------------------------------------------------------------------
/docs/reference/git/clone.md:
--------------------------------------------------------------------------------
1 | # Reference: Git Clone
2 |
3 | clone a repository from another location, typically a shared Git service (GitHub, GitLab, etc.)
4 |
5 | ```shell
6 | git clone --origin practicalli repository-url local-directory
7 | ```
8 |
9 | `--branch` option will checkout a specific branch name once cloned.
10 |
11 | [Clone - Git reference](https://www.git-scm.com/docs/git-clone){target=_blank .md-button}
12 |
13 |
14 | ## Managing Clone size
15 |
16 | Continuous Integration workflows can be more effective when cloning a small part of the repository.
17 |
18 |
19 | ### Partial Clone
20 |
21 | `--filter option` is used to clone a partial repository.
22 |
23 | `git rev-list --filter=
49 |
50 | I also like to add branch information to my status output....
51 |
52 | [alias]
53 | sitrep = status -sb
54 | sr = status -sb
55 | word = diff --word-diff
56 | unstage = reset HEAD
57 |
58 |
59 |
60 | Read the [official documentation on git customisation](http://git-scm.com/book/en/Customizing-Git-Git-Configuration) for more options.
61 |
62 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/aliases-for-nicer-git-output.md:
--------------------------------------------------------------------------------
1 | title: Aliases for nicer Git output
2 | ---
3 |
4 | Just like the Unix shell, you can add aliases to Git as short-cuts to the command that you use frequently, so you can use git even more effectively.
5 |
6 | Defining aliases for those tricky to remember commands you dont use very often, but help you get yourself out of trouble with Git.
7 |
8 |
9 | ## Git Log
10 | The default `git log` command is very verbose in its output, especially when you have many commits. Using a few options to the git log command you can get a much more useful output.
11 |
12 | ### oneline
13 | As you can probably guess, the `--oneline` option puts all the information of a commit on one line. This commit information is the abreviated commit number and the commit message.
14 |
15 | ### graph option
16 | This displays the log as a graph showing where branching and merging has taken place
17 |
18 | ### decorate option
19 | This shows which branches are on which commit versions, including remote repositories that have been added to the local repository. So you can easily see the most recent commit for repository and branch. This information help you understand if you need to push or merge commits between repositories and branches.
20 |
21 | ### Add the Git log alias
22 |
23 | Putting these three options together in the alias file:
24 |
25 | [alias]
26 | lg = log --oneline --graph --decorate
27 |
28 | ### hardcore customisation
29 |
30 | You can also define exactly what information you want displayed each line of the Git log (and in what color) using the `--pretty` option
31 |
32 |
33 | [alias]
34 | lp = log
35 | --graph
36 | --pretty=format:
37 | '%C(cyan)%h%Creset - %C(bold yellow)%d%Creset %s %C(blue)(%ar) %C(magenta)%an%Creset'
38 | --all
39 |
40 | > The above alias should all be on one line in the .gitconfig file
41 |
42 | ## Other useful aliases
43 |
44 | When you become a regular git user you will notice you type `git status` very often. You may also notice it is also quite verbose in its output. Once you know the different stages of your workflow of changes (untracked, modified, staged) you simply get a summary view of the status by using the `-s` option
45 |
46 | `git status -s`
47 |
48 |
49 |
50 | I also like to add branch information to my status output....
51 |
52 | [alias]
53 | sitrep = status -sb
54 | sr = status -sb
55 | word = diff --word-diff
56 | unstage = reset HEAD
57 |
58 |
59 |
60 | Read the [official documentation on git customisation](http://git-scm.com/book/en/Customizing-Git-Git-Configuration) for more options.
61 |
62 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | # ------------------------------------------
2 | # Practicalli: Makefile
3 | #
4 | # Consistent set of targets to support local book development
5 | # ------------------------------------------
6 |
7 | # .PHONY: ensures target used rather than matching file name
8 | # https://makefiletutorial.com/#phony
9 | .PHONY: all clean docs lint pre-commit-check test
10 |
11 | # ------- Makefile Variables --------- #
12 | # run help if no target specified
13 | .DEFAULT_GOAL := help
14 | SHELL := /usr/bin/zsh
15 |
16 | # Column the target description is printed from
17 | HELP-DESCRIPTION-SPACING := 24
18 |
19 | # Tool Commands
20 | MEGALINTER_RUNNER := npx mega-linter-runner --flavor documentation --env "'MEGALINTER_CONFIG=.github/config/megalinter.yaml'" --env "'VALIDATE_ALL_CODEBASE=true'" --remove-container
21 | MKDOCS_SERVER := mkdocs serve --dev-addr localhost:7777
22 |
23 | # Makefile file and directory name wildcard
24 | EDN-FILES := $(wildcard *.edn)
25 | # ------------------------------------ #
26 |
27 | # ------ Quality Checks ------------ #
28 | pre-commit-check: lint
29 |
30 | lint: ## Run MegaLinter with custom configuration (node.js required)
31 | $(info --------- MegaLinter Runner ---------)
32 | $(MEGALINTER_RUNNER)
33 |
34 | lint-fix: ## Run MegaLinter with custom configuration (node.js required)
35 | $(info --------- MegaLinter Runner ---------)
36 | $(MEGALINTER_RUNNER) --fix
37 |
38 | lint-clean: ## Clean MegaLinter report information
39 | $(info --------- MegaLinter Clean Reports ---------)
40 | - rm -rf ./megalinter-reports
41 |
42 | megalinter-upgrade: ## Upgrade MegaLinter config to latest version
43 | $(info --------- MegaLinter Upgrade Config ---------)
44 | npx mega-linter-runner@latest --upgrade
45 | # ------------------------------------ #
46 |
47 | # --- Documentation Generation ------ #
48 | python-venv: ## Enable Python Virtual Environment for MkDocs
49 | $(info --------- Mkdocs Local Server ---------)
50 | source ~/.local/venv/bin/activate
51 |
52 | docs: ## Build and run mkdocs in local server (python venv)
53 | $(info --------- Mkdocs Local Server ---------)
54 | source ~/.local/venv/bin/activate && $(MKDOCS_SERVER)
55 |
56 | docs-changed: ## Build only changed files and run mkdocs in local server (python venv)
57 | $(info --------- Mkdocs Local Server ---------)
58 | source ~/.local/venv/bin/activate && $(MKDOCS_SERVER) --dirtyreload
59 |
60 | docs-build: ## Build mkdocs (python venv)
61 | $(info --------- Mkdocs Local Server ---------)
62 | source ~/.local/venv/bin/activate && mkdocs build
63 | # ------------------------------------ #
64 |
65 | # ------------ Help ------------------ #
66 | # Source: https://nedbatchelder.com/blog/201804/makefile_help_target.html
67 |
68 | help: ## Describe available tasks in Makefile
69 | @grep '^[a-zA-Z]' $(MAKEFILE_LIST) | \
70 | sort | \
71 | awk -F ':.*?## ' 'NF==2 {printf "\033[36m %-$(HELP-DESCRIPTION-SPACING)s\033[0m %s\n", $$1, $$2}'
72 | # ------------------------------------ #
73 |
--------------------------------------------------------------------------------
/docs/git/tutorial.md:
--------------------------------------------------------------------------------
1 | # Git tutorial
2 |
3 | This tutorial will give you a practical guide to using the Git version control tool to managing changes to source code and configuration files in projects. The tutorial also covers collaborating on projects using Github public repositories. You can either read an [overview of Git](overview-of-git.html)
4 |
5 | ## Setting up Git & Github
6 | - [Choose your git client](choose-your-git-client.html)
7 | - [Identify yourself to Git](identify-yourself-to-git.html)
8 | - [Create an account on Github](create-account-on-github.html)
9 |
10 |
11 | ## Creating Git Projects
12 | * [Creating a Git managed project](chapter05-creating-a-git-managed-project.html)
13 | * [Ignoring files](chapter06-ignoring-files.html)
14 |
15 |
16 | ## Local Git Workflow
17 | * Checking the status - what has changed -- git status, git diff
18 | * Staging changes - basic add, git add -p, unstaging untracked files, unstaging tracked files, git diff --cached
19 | * Committing a new version
20 | * Git log
21 | * [Chapter 7: The local git workflow](chapter07-local-git-workflow.html)
22 |
23 |
24 | ## Branching & Merging - why do this
25 | - try out code and modifications to design, different algorithms
26 | - easily discard changes that are not needed - or leave them in a branch so they are not affecting / poluting the main codebase
27 |
28 | * [Branching and Merging](chapter09-branch-and-merge.html)
29 | * [merging changes](merging-changes.html)
30 |
31 |
32 | ## Collaborating with other developers using Git and Github
33 | * [Chapter 10: Collaborating with Github](collaborating-with-github.html)
34 | * Practices to avoid when using shared repos like Github
35 | - rebasing, forgetting to push changes (especially for sub modules)
36 |
37 |
38 | ## Troubleshooting]
39 | - what to do if you loose your head
40 | - if you really have to change a commit
41 | - unstage changes
42 |
43 |
44 | ## Resources
45 | * Git submodules
46 |
47 |
48 | # Git local workflow visualised
49 |
50 | You can quickly get versioning your code with Git, all on your own computer. You do not need to set up a server.
51 |
52 |
53 |
54 | # Git and Github workflow visualised
55 |
56 | To give you a big picture view of how you use Git and Github, here is a visualisation of the workflow for both. The details of this workflow are ocvered in the workshop from [Chapter 10: Collaborating with Github](chapter10-collaborating-with-github.html) onwards.
57 |
58 | 
59 |
60 | # Reference
61 |
62 | * [Git essential commands](/developer-guides/git-quickstart-guide.png) for the most common commands for using Git
63 | * [Git Visual cheat sheet](http://ndpsoftware.com/git-cheatsheet.html)
64 | * [Git Reference](http://gitref.org/)
65 | * [Learning Version Control wth Git](http://www.git-tower.com/learn/ebook/command-line/introduction) - git-tower.com
66 | * [StarLogs.net demo from my blog](http://starlogs.net/#jr0cket/jr0cket.github.io-hexo)
67 |
--------------------------------------------------------------------------------
/overrides/partials/header.html:
--------------------------------------------------------------------------------
1 |
2 | {% set class = "md-header" %} {% if "navigation.tabs.sticky" in features %} {%
3 | set class = class ~ " md-header--shadow md-header--lifted" %} {% elif
4 | "navigation.tabs" not in features %} {% set class = class ~ " md-header--shadow"
5 | %} {% endif %}
6 |
7 |
8 |
55 |
56 | # Git and Github workflow visualised
57 |
58 | To give you a big picture view of how you use Git and Github, here is a visualisation of the workflow for both. The details of this workflow are ocvered in the workshop from [Chapter 10: Collaborating with Github](chapter10-collaborating-with-github.html) onwards.
59 |
60 |
61 |
62 | # Reference
63 |
64 | * [Git essential commands](/developer-guides/git-quickstart-guide.png) for the most common commands for using Git
65 | * [Git Visual cheat sheet](http://ndpsoftware.com/git-cheatsheet.html)
66 | * [Git Reference](http://gitref.org/)
67 | * [Learning Version Control wth Git](http://www.git-tower.com/learn/ebook/command-line/introduction) - git-tower.com
68 | * [StarLogs.net demo from my blog](http://starlogs.net/#jr0cket/jr0cket.github.io-hexo)
69 |
70 | Last update: Tue 28 Oct 2014 10:10:44 GMT
71 |
72 |
--------------------------------------------------------------------------------
/docs/git/git-overview.md:
--------------------------------------------------------------------------------
1 | title: Overview of Git and Github
2 | ---
3 |
4 | Git is a very powerful tool for managing the changes you make as you develop source code for your software projects. Typically those changes tracked are the ones made to source code and configuration files. Git understands how to merge text files together, allowing you to pull in changes from others. It also helps you compare changes in different versions of text files using the diff tool.
5 |
6 | You can also manage binary files such as images and propriatory document formats, although git does not typically come with tools that help you merge or compare differences.
7 |
8 | Before the creation of Git (and Mercurial, Bazar and a few others), most versioning tools for source code used what is called a central model. Tools like CVS and SVN manage code changes in a single central server, shared across teams and the whole company. When developers work on code they only get a copy of current code locally on their development machine. To actually do any commits, to version the code, then they have to connect with the server. When looking at history and any other activitiy, developers have to communicate with the central server. If this server is off line or slow, then this can lead to problems working effectively together as a team.
9 |
10 | Git uses a distributed approach to managing changes (as does bazar & mercurial). This approach may seema little more complicated at first, but adds far more control and visiblity to your projects.
11 |
12 | A distributed model means that everyone involved gets a complete copy of the project repository. It is still common to have a shared repository that holds all the code (e.g. on Github), although this can easily be changed and may evolve over time.
13 |
14 | Using Git, developers create a copy of a project repository on their development machine, this is called *cloning*. This creates a local copy of the repository along with all the files managed by git in your project. As you have a local repository, all the code changes that have ever been made are right there giving you a full history of the project.
15 |
16 | One of the benefits of git therefore is to be able to constantly commit changes, regardless of if you are connected to a shared repository. You commit all your changes locally first (even if you are connected) and then when ready you can push your changes to a shared repository.
17 |
18 | It is common to have a common shared repository that is seen as the canonical version of the code for a project. The core members of the project team, refered to as *committers* have direct access to update this shared repository. Anyone with access to the project repository can take a copy (clone).
19 |
20 | Should you wish to work on the project you can create your own copy, called a fork. Your fork is your own exact copy of the oringinal repository, including all the history. As this is your repository, you can commit changes directly.
21 |
22 | Should you wish to submit your chages back to the original project, you can create a pull request from your fork. A pull request is a message and one or more commits that are sent to the original project team, inviting them to pull in the changes from your forked repository.
23 |
24 |
25 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/git-overview.md:
--------------------------------------------------------------------------------
1 | title: Overview of Git and Github
2 | ---
3 |
4 | Git is a very powerful tool for managing the changes you make as you develop source code for your software projects. Typically those changes tracked are the ones made to source code and configuration files. Git understands how to merge text files together, allowing you to pull in changes from others. It also helps you compare changes in different versions of text files using the diff tool.
5 |
6 | You can also manage binary files such as images and propriatory document formats, although git does not typically come with tools that help you merge or compare differences.
7 |
8 | Before the creation of Git (and Mercurial, Bazar and a few others), most versioning tools for source code used what is called a central model. Tools like CVS and SVN manage code changes in a single central server, shared across teams and the whole company. When developers work on code they only get a copy of current code locally on their development machine. To actually do any commits, to version the code, then they have to connect with the server. When looking at history and any other activitiy, developers have to communicate with the central server. If this server is off line or slow, then this can lead to problems working effectively together as a team.
9 |
10 | Git uses a distributed approach to managing changes (as does bazar & mercurial). This approach may seema little more complicated at first, but adds far more control and visiblity to your projects.
11 |
12 | A distributed model means that everyone involved gets a complete copy of the project repository. It is still common to have a shared repository that holds all the code (e.g. on Github), although this can easily be changed and may evolve over time.
13 |
14 | Using Git, developers create a copy of a project repository on their development machine, this is called *cloning*. This creates a local copy of the repository along with all the files managed by git in your project. As you have a local repository, all the code changes that have ever been made are right there giving you a full history of the project.
15 |
16 | One of the benefits of git therefore is to be able to constantly commit changes, regardless of if you are connected to a shared repository. You commit all your changes locally first (even if you are connected) and then when ready you can push your changes to a shared repository.
17 |
18 | It is common to have a common shared repository that is seen as the canonical version of the code for a project. The core members of the project team, refered to as *committers* have direct access to update this shared repository. Anyone with access to the project repository can take a copy (clone).
19 |
20 | Should you wish to work on the project you can create your own copy, called a fork. Your fork is your own exact copy of the oringinal repository, including all the history. As this is your repository, you can commit changes directly.
21 |
22 | Should you wish to submit your chages back to the original project, you can create a pull request from your fork. A pull request is a message and one or more commits that are sent to the original project team, inviting them to pull in the changes from your forked repository.
23 |
24 |
25 |
--------------------------------------------------------------------------------
/docs/git/merging-changes.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | # Conflict resolution - managing the merge process
4 |
5 | During the development of your project you will make many changes to your files. If you follow the "commit early, commit often" idea, then most of your commits should be straight forward.
6 |
7 | Git is very good at merging changes together, although it has its limitations.
8 |
9 | The longer you leave a change to be commited or the bigger the change is you are making (especially to existing files), the more likely you will have to manage the merge process yourself.
10 |
11 |
12 | ## A common merge conflict with Github
13 |
14 | When you create a new repository on Github you are given the choice of creating a Readme.md file and a .gitignore file for one of numerous languages. These are both really useful things to have.
15 |
16 | However, if you already have a repository locally with a number of commits, when you create a github repository with these files then you are actually making a commit on the github repository as well.
17 |
18 | This leaves you with commits locally that you dont have on your github repository and a commit on your Github repository that you dont have locally. As the commit is newer on the Github repository, then git will not push your local changes as it will not create a "fast-forward" commit. A fast-forward commit is newer than any existing commits in that repository.
19 |
20 | To resolve this conflict, you have to pull the change you made in the Github (addint a Readme.md and/or .gitignore file) to your local repository. This is done with the ommand:
21 |
22 | git pull
62 | 
63 | This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images & stylesheets).
64 |
65 |
66 | [](https://practicalli.github.io/spacemacs/)
67 |
--------------------------------------------------------------------------------
/.github/config/megalinter.yaml:
--------------------------------------------------------------------------------
1 | ---
2 | # Configuration file for MegaLinter
3 | #
4 | # General configuration:
5 | # https://megalinter.io/latest/configuration/
6 | #
7 | # Specific Linters:
8 | # https://megalinter.io/latest/supported-linters/
9 |
10 | # ------------------------
11 | # Validate all files if true
12 | # or new / edited files if false
13 | VALIDATE_ALL_CODEBASE: false
14 |
15 | # ------------------------
16 | # Linters
17 |
18 | # Run linters in parallel
19 | PARALLEL: true
20 |
21 | # ENABLE specific linters, all other linters automatically disabled
22 | ENABLE:
23 | # - CLOJURE
24 | - CREDENTIALS
25 | - DOCKERFILE
26 | - MAKEFILE
27 | - MARKDOWN
28 | - GIT
29 | - SPELL
30 | - YAML
31 | - REPOSITORY
32 |
33 | # Linter specific configuration
34 |
35 | # CLOJURE_CLJ_KONDO_CONFIG_FILE: ".github/config/clj-kondo-ci-config.edn"
36 | # CLOJURE_CLJ_KONDO_ARGUMENTS: "--lint deps.edn"
37 | # CLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: "dev|develop"
38 | # CLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: "resources"
39 |
40 | # CREDENTIALS_SECRETLINT_DISABLE_ERRORS: true
41 | CREDENTIALS_SECRETLINT_CONFIG_FILE: ".github/config/secretlintrc.json"
42 |
43 | MARKDOWN_MARKDOWNLINT_CONFIG_FILE: ".github/config/markdown-lint.jsonc"
44 | MARKDOWN_MARKDOWNLINT_FILTER_REGEX_EXCLUDE: ".github/pull_request_template.md|CHANGELOG.md|README.md|GLOSSARY.md|java-17-flags.md|abbreviations.md"
45 | # MARKDOWN_MARKDOWNLINT_DISABLE_ERRORS: true
46 | MARKDOWN_MARKDOWN_LINK_CHECK_CONFIG_FILE: ".github/config/markdown-link-check.json"
47 | # MARKDOWN_MARKDOWN_LINK_CHECK_CLI_LINT_MODE: "project"
48 | # MARKDOWN_MARKDOWN_LINK_CHECK_DISABLE_ERRORS: false
49 | MARKDOWN_REMARK_LINT_DISABLE_ERRORS: true
50 | # MARKDOWN_MARKDOWN_TABLE_FORMATTER_DISABLE_ERRORS: false
51 |
52 | REPOSITORY_GITLEAKS_CONFIG_FILE: ".github/config/gitleaks.toml"
53 | REPOSITORY_TRUFFLEHOG_DISABLE_ERRORS: true # Errors only as warnings
54 |
55 | # SPELL_CSPELL_DISABLE_ERRORS: true
56 | SPELL_MISSPELL_DISABLE_ERRORS: true
57 | SPELL_LYCHEE_CONFIG_FILE: ".github/config/lychee.toml"
58 | SPELL_LYCHEE_DISABLE_ERRORS: true # Errors are only warnings
59 |
60 | # YAML_PRETTIER_FILTER_REGEX_EXCLUDE: (docs/)
61 | # YAML_YAMLLINT_FILTER_REGEX_EXCLUDE: (docs/)
62 |
63 | # Explicitly disable linters to ensure they are never run
64 | # DISABLE:
65 | # - COPYPASTE # checks for excessive copy-pastes
66 | # - SPELL # spell checking - often creates many false positives
67 | # - CSS #
68 |
69 | # Disable linter features
70 | DISABLE_LINTERS:
71 | - YAML_PRETTIER # draconian format rules
72 | - SPELL_CSPELL # many clojure references causing false positives
73 | - YAML_YAMLLINT # vague error mesages, investigation required
74 | - REPOSITORY_GIT_DIFF # warnings about LF to CRLF
75 | - REPOSITORY_SECRETLINT # reporting errors in its own config file
76 | # - REPOSITORY_DEVSKIM # unnecessary URL TLS checks
77 | - REPOSITORY_CHECKOV # fails on root user in Dockerfile
78 | - REPOSITORY_SECRETLINT
79 |
80 | # Ignore all errors and return without error status
81 | # DISABLE_ERRORS: true
82 |
83 | # ------------------------
84 |
85 | # ------------------------
86 | # Reporting
87 |
88 | # Activate sources reporter
89 | UPDATED_SOURCES_REPORTER: false
90 |
91 | # Show Linter timings in summary table at end of run
92 | SHOW_ELAPSED_TIME: true
93 |
94 | # Upload reports to file.io
95 | FILEIO_REPORTER: false
96 | # ------------------------
97 |
98 | # ------------------------
99 | # Over-ride errors
100 |
101 | # detect errors but do not block CI passing
102 | # DISABLE_ERRORS: true
103 | # ------------------------
104 |
--------------------------------------------------------------------------------
/docs/assets/stylesheets/extra.css:
--------------------------------------------------------------------------------
1 | [data-md-color-scheme="default"] {
2 | --md-default-bg-color: hsla(208, 100%, 96%, 0.94);
3 | --md-code-bg-color: hsla(208, 80%, 88%, 0.64);
4 | --md-code-hl-color: hsla(208, 88%, 80%, 0.92);
5 | --md-admonition-bg-color: hsla(208, 80%, 92%, 0.92);
6 | --md-typeset-kbd-color: hsla(208, 100%, 98%, 0.98);
7 | }
8 |
9 | /* Custom Admonitions */
10 |
11 |
12 | :root {
13 | /* Clojure Idiom*/
14 | --md-admonition-icon--clojure-idiom: url(https://raw.githubusercontent.com/practicalli/graphic-design/c40cc063cc5bb07525b524d8a3d638e2f42bc38a/logos/clojure-logo-bullet.svg);
15 |
16 | /* Round corners */
17 | --base-border-radius: 0.5rem;
18 | }
19 |
20 | /*Admonitions colors*/
21 | .md-typeset .admonition.clojure-idiom,
22 | .md-typeset details.clojure-idiom {
23 | border-color: rgb(43, 155, 70);
24 | }
25 | .md-typeset .clojure-idiom > .admonition-title,
26 | .md-typeset .clojure-idiom > summary {
27 | background-color: rgba(43, 155, 70, 0.1);
28 | }
29 | .md-typeset .clojure-idiom > .admonition-title::before,
30 | .md-typeset .clojure-idiom > summary::before {
31 | background-color: rgb(250, 250, 250);
32 | background-image: var(--md-admonition-icon--clojure-idiom);
33 | -webkit-mask-image: var(--md-admonition-icon--clojure-idiom);
34 | mask-image: var(--md-admonition-icon--clojure-idiom);
35 | }
36 |
37 |
38 | /* Change font family of filename present on top of code block. */
39 | .highlight span.filename {
40 | border-bottom: none;
41 | border-radius: var(--base-border-radius);
42 | display: inline;
43 | font-family: var(--md-code-font-family);
44 | border-bottom-left-radius: 0;
45 | border-bottom-right-radius: 0;
46 | margin-bottom: 5px;
47 | text-align: center;
48 | }
49 | .highlight span.filename + pre > code {
50 | border-radius: var(--base-border-radius);
51 | border-top-left-radius: 0;
52 | }
53 | .md-typeset pre > code {
54 | border-radius: var(--base-border-radius);
55 | }
56 |
57 | /* Grid Cards */
58 | .md-typeset .grid.cards > ul > li {
59 | border-radius: var(--base-border-radius);
60 | }
61 | .md-typeset .grid.cards > ul > li:hover {
62 | box-shadow: 0 0 0.2rem #ffffff40;
63 | }
64 |
65 | /* Markdown Button */
66 | .md-typeset .md-button {
67 | border-radius: var(--base-border-radius);
68 | }
69 |
70 | /* Critic, Mark */
71 | ins.critic,
72 | del.critic {
73 | text-decoration: none;
74 | }
75 |
76 | .md-typeset .critic,
77 | .md-typeset mark {
78 | border-radius: 0.2rem;
79 | padding: 0 0.2rem;
80 | }
81 |
82 | .md-typeset mark {
83 | box-shadow: 0 0 0 0.1rem var(--md-typeset-mark-color);
84 | }
85 |
86 | .md-typeset ins.critic {
87 | box-shadow: 0 0 0 0.1rem var(--md-typeset-ins-color);
88 | }
89 |
90 | .md-typeset del.critic {
91 | box-shadow: 0 0 0 0.1rem var(--md-typeset-del-color);
92 | }
93 |
94 | /* Forms */
95 | .md-search__form {
96 | border-radius: var(--base-border-radius);
97 | }
98 |
99 | [data-md-toggle="search"]:checked ~ .md-header .md-search__form {
100 | border-top-right-radius: var(--base-border-radius);
101 | border-top-left-radius: var(--base-border-radius);
102 | }
103 |
104 | [dir="ltr"] .md-search__output {
105 | border-bottom-right-radius: var(--base-border-radius);
106 | border-bottom-left-radius: var(--base-border-radius);
107 | }
108 |
109 | /* Blog - index.md */
110 | .md-post--excerpt {
111 | background-color: var(--md-accent-fg-color--transparent);
112 | box-shadow: 0 0 0 1rem var(--md-accent-fg-color--transparent);
113 | border-radius: var(--base-border-radius);
114 | }
115 |
116 | /* Table */
117 | .md-typeset table:not([class]) {
118 | border-radius: var(--base-border-radius);
119 | }
120 |
--------------------------------------------------------------------------------
/docs/introduction/contributing.md:
--------------------------------------------------------------------------------
1 | # Contributing to Practicalli
2 |
3 | Practicalli books are written in markdown and use MkDocs to generate the published website via a GitHub workflow. MkDocs can also run a local server using the `make docs` target from the `Makefile`
4 |
5 | By submitting content ideas and corrections you are agreeing they can be used in this book under the [Creative Commons Attribution ShareAlike 4.0 International license](https://creativecommons.org/licenses/by-sa/4.0/){target=_blank}. Attribution will be detailed via [GitHub contributors](https://github.com/practicalli/clojure/graphs/contributors){target=_blank}.
6 |
7 | All content and interaction with any persons or systems must be done so with respect and within the Practicalli Code of Conduct.
8 |
9 | ## Book status
10 |
11 | [](https://github.com/practicalli/gitops/actions/workflows/megalinter.yaml)[](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml){target=_blank}
12 | [](https://github.com/practicalli/gitops/actions/workflows/publish-book.yaml){target=_blank}
13 | [](https://github.com/practicalli/gitops/actions/workflows/pages/pages-build-deployment){target=_blank}
14 |
15 | [](https://github.com/practicalli/clojure/issues){target=_blank}
16 | [](https://github.com/practicalli/gitops/pulls){target=_blank}
17 |
18 | 
19 | 
20 |
21 | ## Submit and issue or idea
22 |
23 | If something doesnt seem quite right or something is missing from the book, please [raise an issue via the GitHub repository](https://github.com/practicalli/clojure/issues){target=_blank} explaining in as much detail as you can.
24 |
25 | **Raising an issue before creating a pull request will save you and the maintainer time**.
26 |
27 | ## Considering a Pull request?
28 |
29 | Before investing any time in a pull request, please raise an issue explaining the situation. This can save you and the maintainer time and avoid rejected pull requests.
30 |
31 | Please keep pull requests small and focused, as they are much quicker to review and easier to accept. Ideally PR's should be for a specific page or at most a section.
32 |
33 | A PR with a list of changes across different sections will not be merged, it will be reviewed eventually though.
34 |
35 | ## Thank you to everyone that has contributed
36 |
37 | A huge thank you to Rich Hickey and the team at Cognitect for creating and continually guiding the Clojure language. Special thank you to Alex Miller who has provided excellent advice on working with Clojure and the CLI tooling.
38 |
39 | The Clojure community has been highly supportive of everyone using Clojure and I'd like to thank everyone for the feedback and contributions. I would also like to thank everyone that has joined in with the [London Clojurins community](https://www.meetup.com/London-Clojurians/){target=_blank}, [ClojureBridgeLondon](https://clojurebridgelondon.github.io/){target=_blank}, [Clojurians Slack community](http://clojurians.net/){target=_blank}, [Clojurians Zulip](https://clojurians.zulipchat.com/){target=_blank} community and [Clojureverse community](https://clojureverse.org/){target=_blank}.
40 |
41 | Thank you to everyone who sponsors the Practicalli websites and videos and for the [Clojurists Together sponsorship](https://www.clojuriststogether.org/){target=_blank}, it helps me continue the work at a much faster pace.
42 |
43 | Special thanks to [Bruce Durling](https://twitter.com/otfrom){target=_blank} for getting me into Cloure in the first place.
44 |
45 | 
46 |
--------------------------------------------------------------------------------
/docs/git/create-a-git-repository.md:
--------------------------------------------------------------------------------
1 | title: Clone the Github repository
2 | ---
3 |
4 | You previously created a repository on Github so that you can share your code and versions with others. However the changes to your source code files happen on your laptop, so we need to first make a copy of the Github repository on your laptop.
5 |
6 | We take a complete copy of the repository on Github repository with all its history, creating an exact clone of it locally on the laptop. This is called **Cloning** and uses the command `git clone alias URL [directory]`, where `alias` is the short name for the repository `URL` and `directory` is an optional directory in which to create the repository
7 |
8 | ## Clone your Github repository
9 |
10 | Change into a suitable directory on your laptop, eg `my-projects`. Then clone the Github repository using the command:
11 |
12 | git clone github git@github.com:jr0cket/git-basics-example git-basics
13 |
14 |
15 | This creates a directory called `git-basics`. Inside this directory is another called .git which is your local copy of the repository (_so dont delete the .git directory_)
16 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 | ## Create a local Git repository
25 |
26 | Now you have a project you want to version, we are going to create a local repository
27 | Change into the new folder created for your project. Then create a new git repository using the git initialise command:
28 |
29 | cd my-projects
30 | git init
31 |
32 | You have just created an empty *local* git repository. In effect, you have created the *.git* folder within your project that will contain all the change history and changes themselves as the project develops. You dont need to understand what goes on in the .git folder, but you do need to remember that if you delete it then all your change history is deleted.
33 |
34 |
63 | This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images & stylesheets).
64 |
35 |
36 | ## Viewing changes to files (working copy)
37 |
38 | To see what changes you could commit to git, use the git status command:
39 |
40 | git status
41 |
42 | If you have files in your project they will show up as untracked files when you do a git status. This means that these files have yet to be put under git version control. You will soon see that *git status* is used all the time to let you know what the current situation is with your changes.
43 |
44 | ## Preparing to version your changes
45 |
46 | To tell git what changes you want to version, you tell git which files you want to add to make up part of the next commit using the *git add* command. You can specify a particular file or you can add all files at once.
47 |
48 | To add a specific file
49 |
50 | git add filename.ext
51 |
52 | To add all files that have been altered or added to the working copy since the last commit:
53 |
54 | git add .
55 |
56 | Adding files to git is not the same as doing a commit. With *git add* you are preparing one or more files to be committed. When you add a file, it is placed in what is called the staging area (or index). Staging files is a useful way to group changes over multiple files in order to make a meaningful commit. In [Chapter 7 - the local git workflow](#chapter07), we will cover the staging area and other steps in Git.
57 |
58 | To see what files are staged at any time, you use the *git status* command.
59 |
60 | # Commit your changes to the local repository
61 |
62 | When you have told git about all the changes you want to add, you use the `git commit` command.
63 |
64 | For each commit, you should provide a meaningful message that explains what you have commited. When you run the commit command, your default editor will open for you to type in the commit message. Alternativley you can specify the message with the `-m` option
65 |
66 | git commit -m "meaningful message describing the commit"
67 |
68 | For additional changes you continue the cycle of adding files (staging them) and then committing those changes. This gives you a very detailed history of changes, so you can see how the project has evolved, step back in time and more easily merge changes from different developers.
69 |
70 | # edit files
71 | git add filename
72 | git commit -m "describe the change"
73 |
74 | # Viewing the history of changes
75 |
76 | You can see all the changes that have been committed to your local repository using the `git log` command.
77 |
78 | By default, `git log` shows a very verbose commit history. Using options with the git log command you can make the output easier to read.
79 |
80 | git log --oneline --graph --decorate
81 |
82 | * `--oneline` shows the commit details on a single line
83 | * `--graph` shows where branches and merges have been made in the history
84 | * `--decorate` shows which commit version
85 |
86 | [TODO: image of git log]
87 |
88 |
--------------------------------------------------------------------------------
/docs/git/clone.md:
--------------------------------------------------------------------------------
1 | # Clone A Github repository
2 |
3 | You previously created a repository on Github so that you can share your code and versions with others. However the changes to your source code files happen on your laptop, so we need to first make a copy of the Github repository on your laptop.
4 |
5 | We take a complete copy of the repository on Github repository with all its history, creating an exact clone of it locally on the laptop. This is called **Cloning** and uses the command `git clone alias URL [directory]`, where `alias` is the short name for the repository `URL` and `directory` is an optional directory in which to create the repository
6 |
7 | ## Clone your Github repository
8 |
9 | Change into a suitable directory on your laptop, eg `my-projects`. Then clone the Github repository using the command:
10 |
11 | ```shell
12 | git clone github git@github.com:jr0cket/git-basics-example git-basics
13 | ```
14 |
15 |
16 | This creates a directory called `git-basics`. Inside this directory is another called .git which is your local copy of the repository (_so dont delete the .git directory_)
17 |
18 |
19 |
20 | ## Create a local Git repository
21 |
22 | Now you have a project you want to version, we are going to create a local repository
23 | Change into the new folder created for your project. Then create a new git repository using the git initialise command:
24 |
25 | ```shell
26 | git init
27 | ```
28 |
29 | You have just created an empty *local* git repository. In effect, you have created the *.git* folder within your project that will contain all the change history and changes themselves as the project develops. You dont need to understand what goes on in the .git folder, but you do need to remember that if you delete it then all your change history is deleted.
30 |
31 |
32 |
33 | ## Viewing changes to files (working copy)
34 |
35 | To see what changes you could commit to git, use the git status command:
36 | ```
37 | git status
38 | ```
39 |
40 | If you have files in your project they will show up as untracked files when you do a git status. This means that these files have yet to be put under git version control. You will soon see that *git status* is used all the time to let you know what the current situation is with your changes.
41 |
42 | ## Preparing to version your changes
43 |
44 | To tell git what changes you want to version, you tell git which files you want to add to make up part of the next commit using the *git add* command. You can specify a particular file or you can add all files at once.
45 |
46 | To add a specific file
47 |
48 | ```
49 | git add filename.ext
50 | ```
51 |
52 | To add all files that have been altered or added to the working copy since the last commit:
53 |
54 | ```
55 | git add .
56 | ```
57 |
58 | Adding files to git is not the same as doing a commit. With *git add* you are preparing one or more files to be committed. When you add a file, it is placed in what is called the staging area (or index). Staging files is a useful way to group changes over multiple files in order to make a meaningful commit. In [Chapter 7 - the local git workflow](#chapter07), we will cover the staging area and other steps in Git.
59 |
60 | To see what files are staged at any time, you use the *git status* command.
61 |
62 | ## Commit your changes to the local repository
63 |
64 | When you have told git about all the changes you want to add, you use the `git commit` command.
65 |
66 | For each commit, you should provide a meaningful message that explains what you have commited. When you run the commit command, your default editor will open for you to type in the commit message. Alternativley you can specify the message with the `-m` option
67 |
68 | ```
69 | git commit -m "meaningful message describing the commit"
70 | ```
71 |
72 | For additional changes you continue the cycle of adding files (staging them) and then committing those changes. This gives you a very detailed history of changes, so you can see how the project has evolved, step back in time and more easily merge changes from different developers.
73 |
74 | ```
75 | git add filename
76 | ```
77 |
78 |
79 | ```
80 | git commit -m "describe the change"
81 | ```
82 |
83 | # Viewing the history of changes
84 |
85 | You can see all the changes that have been committed to your local repository using the `git log` command.
86 |
87 | By default, `git log` shows a very verbose commit history. Using options with the git log command you can make the output easier to read.
88 |
89 | ```
90 | git log --oneline --graph --decorate
91 | ```
92 |
93 | * `--oneline` shows the commit details on a single line
94 | * `--graph` shows where branches and merges have been made in the history
95 | * `--decorate` shows which commit version
96 |
97 | [TODO: image of git log]
98 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/create-a-git-repository.md:
--------------------------------------------------------------------------------
1 | title: Clone the Github repository
2 | ---
3 |
4 | You previously created a repository on Github so that you can share your code and versions with others. However the changes to your source code files happen on your laptop, so we need to first make a copy of the Github repository on your laptop.
5 |
6 | We take a complete copy of the repository on Github repository with all its history, creating an exact clone of it locally on the laptop. This is called **Cloning** and uses the command `git clone alias URL [directory]`, where `alias` is the short name for the repository `URL` and `directory` is an optional directory in which to create the repository
7 |
8 | ## Clone your Github repository
9 |
10 | Change into a suitable directory on your laptop, eg `my-projects`. Then clone the Github repository using the command:
11 |
12 | git clone github git@github.com:jr0cket/git-basics-example git-basics
13 |
14 |
15 | This creates a directory called `git-basics`. Inside this directory is another called .git which is your local copy of the repository (_so dont delete the .git directory_)
16 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 | ## Create a local Git repository
25 |
26 | Now you have a project you want to version, we are going to create a local repository
27 | Change into the new folder created for your project. Then create a new git repository using the git initialise command:
28 |
29 | cd my-projects
30 | git init
31 |
32 | You have just created an empty *local* git repository. In effect, you have created the *.git* folder within your project that will contain all the change history and changes themselves as the project develops. You dont need to understand what goes on in the .git folder, but you do need to remember that if you delete it then all your change history is deleted.
33 |
34 |
35 |
36 | ## Viewing changes to files (working copy)
37 |
38 | To see what changes you could commit to git, use the git status command:
39 |
40 | git status
41 |
42 | If you have files in your project they will show up as untracked files when you do a git status. This means that these files have yet to be put under git version control. You will soon see that *git status* is used all the time to let you know what the current situation is with your changes.
43 |
44 | ## Preparing to version your changes
45 |
46 | To tell git what changes you want to version, you tell git which files you want to add to make up part of the next commit using the *git add* command. You can specify a particular file or you can add all files at once.
47 |
48 | To add a specific file
49 |
50 | git add filename.ext
51 |
52 | To add all files that have been altered or added to the working copy since the last commit:
53 |
54 | git add .
55 |
56 | Adding files to git is not the same as doing a commit. With *git add* you are preparing one or more files to be committed. When you add a file, it is placed in what is called the staging area (or index). Staging files is a useful way to group changes over multiple files in order to make a meaningful commit. In [Chapter 7 - the local git workflow](#chapter07), we will cover the staging area and other steps in Git.
57 |
58 | To see what files are staged at any time, you use the *git status* command.
59 |
60 | # Commit your changes to the local repository
61 |
62 | When you have told git about all the changes you want to add, you use the `git commit` command.
63 |
64 | For each commit, you should provide a meaningful message that explains what you have commited. When you run the commit command, your default editor will open for you to type in the commit message. Alternativley you can specify the message with the `-m` option
65 |
66 | git commit -m "meaningful message describing the commit"
67 |
68 | For additional changes you continue the cycle of adding files (staging them) and then committing those changes. This gives you a very detailed history of changes, so you can see how the project has evolved, step back in time and more easily merge changes from different developers.
69 |
70 | # edit files
71 | git add filename
72 | git commit -m "describe the change"
73 |
74 | # Viewing the history of changes
75 |
76 | You can see all the changes that have been committed to your local repository using the `git log` command.
77 |
78 | By default, `git log` shows a very verbose commit history. Using options with the git log command you can make the output easier to read.
79 |
80 | git log --oneline --graph --decorate
81 |
82 | * `--oneline` shows the commit details on a single line
83 | * `--graph` shows where branches and merges have been made in the history
84 | * `--decorate` shows which commit version
85 |
86 | [TODO: image of git log]
87 |
88 |
--------------------------------------------------------------------------------
/docs/assets/favicon.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
--------------------------------------------------------------------------------
/docs/assets/stylesheets/practicalli-light.css:
--------------------------------------------------------------------------------
1 | // ----------------------------------------------------------------------------
2 | // Rules
3 | // ----------------------------------------------------------------------------
4 |
5 | // Color variables
6 | :root {
7 | @extend %root;
8 |
9 | // Primary color shades
10 | --md-primary-fg-color: hsla(#{hex2hsl($clr-indigo-500)}, 1);
11 | --md-primary-fg-color--light: hsla(#{hex2hsl($clr-indigo-400)}, 1);
12 | --md-primary-fg-color--dark: hsla(#{hex2hsl($clr-indigo-700)}, 1);
13 | --md-primary-bg-color: hsla(0, 0%, 100%, 1);
14 | --md-primary-bg-color--light: hsla(0, 0%, 100%, 0.7);
15 |
16 | // Accent color shades
17 | --md-accent-fg-color: hsla(#{hex2hsl($clr-indigo-a200)}, 1);
18 | --md-accent-fg-color--transparent: hsla(#{hex2hsl($clr-indigo-a200)}, 0.1);
19 | --md-accent-bg-color: hsla(0, 0%, 100%, 1);
20 | --md-accent-bg-color--light: hsla(0, 0%, 100%, 0.7);
21 | }
22 |
23 | // ----------------------------------------------------------------------------
24 |
25 | // Allow to explicitly use color schemes in nested content
26 | [data-md-color-scheme="practicalli"] {
27 | @extend %root;
28 | }
29 |
30 | // ----------------------------------------------------------------------------
31 | // Placeholders
32 | // ----------------------------------------------------------------------------
33 |
34 | // Default theme, i.e. light mode
35 | %root {
36 |
37 | // Default color shades
38 | --md-default-fg-color: hsla(0, 0%, 0%, 0.87);
39 | --md-default-fg-color--light: hsla(0, 0%, 0%, 0.54);
40 | --md-default-fg-color--lighter: hsla(0, 0%, 0%, 0.32);
41 | --md-default-fg-color--lightest: hsla(0, 0%, 0%, 0.07);
42 | --md-default-bg-color: hsla(53, 90%, 90%, 1);
43 | --md-default-bg-color--light: hsla(53, 90%, 90%, 0.7);
44 | --md-default-bg-color--lighter: hsla(53, 90%, 90%, 0.3);
45 | --md-default-bg-color--lightest: hsla(53, 90%, 90%, 0.12);
46 |
47 | // Code color shades
48 | --md-code-fg-color: hsla(200, 18%, 26%, 1);
49 | --md-code-bg-color: hsla(0, 0%, 96%, 1);
50 |
51 | // Code highlighting color shades
52 | --md-code-hl-color: hsla(#{hex2hsl($clr-yellow-a200)}, 0.5);
53 | --md-code-hl-number-color: hsla(0, 67%, 50%, 1);
54 | --md-code-hl-special-color: hsla(340, 83%, 47%, 1);
55 | --md-code-hl-function-color: hsla(291, 45%, 50%, 1);
56 | --md-code-hl-constant-color: hsla(250, 63%, 60%, 1);
57 | --md-code-hl-keyword-color: hsla(219, 54%, 51%, 1);
58 | --md-code-hl-string-color: hsla(150, 63%, 30%, 1);
59 | --md-code-hl-name-color: var(--md-code-fg-color);
60 | --md-code-hl-operator-color: var(--md-default-fg-color--light);
61 | --md-code-hl-punctuation-color: var(--md-default-fg-color--light);
62 | --md-code-hl-comment-color: var(--md-default-fg-color--light);
63 | --md-code-hl-generic-color: var(--md-default-fg-color--light);
64 | --md-code-hl-variable-color: var(--md-default-fg-color--light);
65 |
66 | // Typeset color shades
67 | --md-typeset-color: var(--md-default-fg-color);
68 |
69 | // Typeset `a` color shades
70 | --md-typeset-a-color: var(--md-primary-fg-color);
71 |
72 | // Typeset `mark` color shades
73 | --md-typeset-mark-color: hsla(#{hex2hsl($clr-yellow-a200)}, 0.5);
74 |
75 | // Typeset `del` and `ins` color shades
76 | --md-typeset-del-color: hsla(6, 90%, 60%, 0.15);
77 | --md-typeset-ins-color: hsla(150, 90%, 44%, 0.15);
78 |
79 | // Typeset `kbd` color shades
80 | --md-typeset-kbd-color: hsla(0, 0%, 98%, 1);
81 | --md-typeset-kbd-accent-color: hsla(0, 100%, 100%, 1);
82 | --md-typeset-kbd-border-color: hsla(0, 0%, 72%, 1);
83 |
84 | // Typeset `table` color shades
85 | --md-typeset-table-color: hsla(0, 0%, 0%, 0.12);
86 |
87 | // Admonition color shades
88 | --md-admonition-fg-color: var(--md-default-fg-color);
89 | --md-admonition-bg-color: var(--md-default-bg-color);
90 |
91 | // Footer color shades
92 | --md-footer-fg-color: hsla(0, 0%, 100%, 1);
93 | --md-footer-fg-color--light: hsla(0, 0%, 100%, 0.7);
94 | --md-footer-fg-color--lighter: hsla(0, 0%, 100%, 0.3);
95 | --md-footer-bg-color: hsla(0, 0%, 0%, 0.87);
96 | --md-footer-bg-color--dark: hsla(0, 0%, 0%, 0.32);
97 |
98 | // Shadow depth 1
99 | --md-shadow-z1:
100 | 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.05),
101 | 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.1);
102 |
103 | // Shadow depth 2
104 | --md-shadow-z2:
105 | 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.1),
106 | 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.25);
107 |
108 | // Shadow depth 3
109 | --md-shadow-z3:
110 | 0 #{px2rem(4px)} #{px2rem(10px)} hsla(0, 0%, 0%, 0.2),
111 | 0 0 #{px2rem(1px)} hsla(0, 0%, 0%, 0.35);
112 | }
113 |
--------------------------------------------------------------------------------
/docs/introduction/gitops.md:
--------------------------------------------------------------------------------
1 | # GitOps Overview
2 |
3 |
4 | This is a placeholder for the GitOps Overview page
5 |
6 |
7 | TODO:rewrite blurb from GitLab to something Practicalli
8 |
9 | https://about.gitlab.com/topics/gitops/
10 |
11 | GitOps is an operational framework that takes DevOps best practices used for application development such as version control, collaboration, compliance, and CI/CD tooling, and applies them to infrastructure automation. While the software development lifecycle has been automated, infrastructure has remained a largely manual process that requires specialized teams. With the demands made on today’s infrastructure, it has become increasingly crucial to implement infrastructure automation. Modern infrastructure needs to be elastic so that it can effectively manage cloud resources that are needed for continuous deployments.
12 |
13 | Modern applications are developed with speed and scale in mind. Organizations with a mature DevOps culture can deploy code to production hundreds of times per day. DevOps teams can accomplish this through development best practices such as version control, code review, and CI/CD pipelines that automate testing and deployments.
14 |
15 | GitOps is used to automate the process of provisioning infrastructure. Similar to how teams use application source code, operations teams that adopt GitOps use configuration files stored as code (infrastructure as code). GitOps configuration files generate the same infrastructure environment every time it’s deployed, just as application source code generates the same application binaries every time it’s built.
16 |
17 | ## How do teams put GitOps into practice?
18 |
19 | GitOps is not a single product, plugin, or platform. GitOps workflows help teams manage IT infrastructure through processes they already use in application development.
20 |
21 | GitOps requires three core components:
22 |
23 | GitOps = IaC + MRs + CI/CD
24 |
25 | IaC: GitOps uses a Git repository as the single source of truth for infrastructure definitions. Git is an open source version control system that tracks code management changes, and a Git repository is a .git folder in a project that tracks all changes made to files in a project over time. Infrastructure as code (IaC) is the practice of keeping all infrastructure configuration stored as code. The actual desired state may or may not be not stored as code (e.g., number of replicas or pods).
26 |
27 | MRs: GitOps uses merge requests (MRs) as the change mechanism for all infrastructure updates. The MR is where teams can collaborate via reviews and comments and where formal approvals take place. A merge commits to your main (or trunk) branch and serves as an audit log.
28 |
29 | CI/CD: GitOps automates infrastructure updates using a Git workflow with continuous integration (CI) and continuous delivery (CI/CD). When new code is merged, the CI/CD pipeline enacts the change in the environment. Any configuration drift, such as manual changes or errors, is overwritten by GitOps automation so the environment converges on the desired state defined in Git. GitLab uses CI/CD pipelines to manage and implement GitOps automation, but other forms of automation, such as definitions operators, can be used as well.
30 |
31 | 32 | 33 |
34 | 35 | 36 | ## GitOps challenges 37 | 38 | With any collaborative effort, change can be tricky and GitOps is no exception. GitOps is a process change that will require discipline from all participants and a commitment to doing things in a new way. It is vital for teams to write everything down. 39 | 40 | GitOps allows for greater collaboration, but that is not necessarily something that comes naturally for some individuals or organizations. A GitOps approval process means that developers make changes to the code, create a merge request, an approver merges these changes, and the change is deployed. This sequence introduces a “change by committee” element to infrastructure, which can seem tedious and time-consuming to engineers used to making quick, manual changes. 41 | 42 | It is important for everyone on the team to record what’s going on in merge requests and issues. The temptation to edit something directly in production or change something manually is going to be difficult to suppress, but the less “cowboy engineering” there is, the better GitOps will work. 43 | 44 | 45 | ## What makes GitOps work? 46 | 47 | As with any emerging technology term, GitOps isn’t strictly defined the same way by everyone across the industry. GitOps principles can be applied to all types of infrastructure automation including VMs and containers, and can be very effective for teams looking to manage Kubernetes-based infrastructure. 48 | 49 | While many tools and methodologies promise faster deployment and seamless management between code and infrastructure, GitOps differs by focusing on a developer-centric experience. Infrastructure management through GitOps happens in the same version control system as the application development, enabling teams to collaborate more in a central location while benefiting from Git’s built-in features. 50 | -------------------------------------------------------------------------------- /docs/git/local-git-workflow.md: -------------------------------------------------------------------------------- 1 | # The local git workflow 2 | 3 | To recap, we have our working copy of our files on our laptop. When we add those files using git, a copy is placed in what git calls Staging. This allows you to assemble several files for the commit. 4 | 5 | As we have a local repository right there on our laptop, we can commit all the files added to the staging area. If you can add a series of small commits and do this often, it gives you a more detaled version history and gives you more points to jump back in time. Regular commits helps to reduce merge conflicts when working in teams and using smaller commits gives other developers lots of details about how the project has evolved. 6 | 7 | In this visual representation you can see the different git stages in which commits can reside. 8 | 9 |
10 |
11 |
12 | ## Understanding git add and the staging area
13 |
14 |
15 |
16 | When you add a file, you are telling git that you want it to be part of the change you are going to commit.
17 |
18 | Lets say you create a new file with 10 lines of content and then use *git add filenname.ext* to add it to git. Then you continue to add another 5 lines the contents of that file. If you do a commit without adding that file to git again, only the first 10 lines of content will be in that commit.
19 |
20 | If you do a second *git add filenname.ext* before you commit, then all 15 lines of content will be included in the commit.
21 |
22 | Having to add changes in this way helps you control exactly what makes up your commit without restricting the files you are working on. Please note that it is advisable to either git add & git commit often so that your changes form part of a meaningful history.
23 |
24 |
25 | ## What has been added - What has changed (using diff)
26 |
27 | Once you have added files to the staging area with *git add*, you can compare any changes made to files in your workspace. Using git diff you can see all changes or specifying a file will show only the differences in that one file.
28 |
29 | git diff
30 | git diff filename
31 |
32 | You can also compare the files you have added to the staging area to those you have committed using the diff option *--staging*
33 |
34 | git diff --staging
35 | git diff --staging filename
36 |
37 |
38 | ## Removing files from staging / index
39 |
40 | You can remove a file you have put in staging (git add filename) using the git command reset
41 |
42 | git reset --soft HEAD^
43 |
44 |
45 | rolling back to the previous commit on the local repo
46 | git reset HEAD~1
47 |
48 |
49 | ## To remove a file from the index/staging
50 |
51 | git rm --cached filename.txt
52 |
53 |
54 |
55 | # Commit your changes
56 |
57 | Once you have staged files using the `git add` command, you can at any point make those files a commit (think a new version). The commit will contain all the files you added.
58 |
59 | git commit -m "useful message describing the details of your commit"
60 |
61 | The better commit messages you write the easier it is for others (and yourself) to understand what is going on in your project.
62 |
63 |
64 | # Working with commits - git log, git show
65 |
66 | Once you have done a commit and there are no more changes in your working directory or staging area, then *git status* no longer tells you anything. This is where *git log* comes in.
67 |
68 | ## git log
69 | Git log shows you the history of the commits you have already made.
70 |
71 | git log
72 |
73 | By default, git log has a very basic output and shows you the commit number, author, date and commit message. You can add options to the git log command to get a much nicer and more useful output, even showing which commits have been pushed to one or more remote repositories.
74 |
75 | git log --graph --oneline --decorate --date-relative
76 |
77 | You can add this to your git configuration as an alias so you dont have to type it all the time
78 |
79 | git config --global alias.lg 'log --graph --oneline --decorate --date-relative'
80 |
81 |
82 | ### Blogs on this subject
83 | * [Git basic tips and tricks](http://git-scm.com/book/en/Git-Basics-Tips-and-Tricks)
84 | * [Must have alias examples](http://durdn.com/blog/2012/11/22/must-have-git-aliases-advanced-examples/)
85 |
86 |
87 | ## git show
88 | Git show displays the contents of a commit (description, files, tags, blobs, etc). By default it shows the log message and textual diff of the text that was modified in the commit.
89 |
90 | For tags, it shows the tag message and the referenced objects.
91 |
92 | The command takes options applicable to the git diff-tree command to control how the changes the commit introduces are shown.
93 |
94 | [TODO] what are the options for git show
95 |
96 | git show
97 | git show HEAD
98 | git show 1234567
99 | git show tag-name
100 |
101 | Using git show without specifying a commit number or tag will show you the latest commit from the branch you are currently in. This is usually the same information in *git show HEAD* as HEAD is a special tag that always points to the latest commit.
102 |
103 | [Back to top...](#top) | [Next: Chapter 08: Conflict Resolution](chapter08-conflict-resolution.html) | [Workshop homepage](index.html)
104 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/local-git-workflow.md:
--------------------------------------------------------------------------------
1 | # The local git workflow
2 |
3 | To recap, we have our working copy of our files on our laptop. When we add those files using git, a copy is placed in what git calls Staging. This allows you to assemble several files for the commit.
4 |
5 | As we have a local repository right there on our laptop, we can commit all the files added to the staging area. If you can add a series of small commits and do this often, it gives you a more detaled version history and gives you more points to jump back in time. Regular commits helps to reduce merge conflicts when working in teams and using smaller commits gives other developers lots of details about how the project has evolved.
6 |
7 | In this visual representation you can see the different git stages in which commits can reside.
8 |
9 |
10 |
11 |
12 | ## Understanding git add and the staging area
13 |
14 |
15 |
16 | When you add a file, you are telling git that you want it to be part of the change you are going to commit.
17 |
18 | Lets say you create a new file with 10 lines of content and then use *git add filenname.ext* to add it to git. Then you continue to add another 5 lines the contents of that file. If you do a commit without adding that file to git again, only the first 10 lines of content will be in that commit.
19 |
20 | If you do a second *git add filenname.ext* before you commit, then all 15 lines of content will be included in the commit.
21 |
22 | Having to add changes in this way helps you control exactly what makes up your commit without restricting the files you are working on. Please note that it is advisable to either git add & git commit often so that your changes form part of a meaningful history.
23 |
24 |
25 | ## What has been added - What has changed (using diff)
26 |
27 | Once you have added files to the staging area with *git add*, you can compare any changes made to files in your workspace. Using git diff you can see all changes or specifying a file will show only the differences in that one file.
28 |
29 | git diff
30 | git diff filename
31 |
32 | You can also compare the files you have added to the staging area to those you have committed using the diff option *--staging*
33 |
34 | git diff --staging
35 | git diff --staging filename
36 |
37 |
38 | ## Removing files from staging / index
39 |
40 | You can remove a file you have put in staging (git add filename) using the git command reset
41 |
42 | git reset --soft HEAD^
43 |
44 |
45 | rolling back to the previous commit on the local repo
46 | git reset HEAD~1
47 |
48 |
49 | ## To remove a file from the index/staging
50 |
51 | git rm --cached filename.txt
52 |
53 |
54 |
55 | # Commit your changes
56 |
57 | Once you have staged files using the `git add` command, you can at any point make those files a commit (think a new version). The commit will contain all the files you added.
58 |
59 | git commit -m "useful message describing the details of your commit"
60 |
61 | The better commit messages you write the easier it is for others (and yourself) to understand what is going on in your project.
62 |
63 |
64 | # Working with commits - git log, git show
65 |
66 | Once you have done a commit and there are no more changes in your working directory or staging area, then *git status* no longer tells you anything. This is where *git log* comes in.
67 |
68 | ## git log
69 | Git log shows you the history of the commits you have already made.
70 |
71 | git log
72 |
73 | By default, git log has a very basic output and shows you the commit number, author, date and commit message. You can add options to the git log command to get a much nicer and more useful output, even showing which commits have been pushed to one or more remote repositories.
74 |
75 | git log --graph --oneline --decorate --date-relative
76 |
77 | You can add this to your git configuration as an alias so you dont have to type it all the time
78 |
79 | git config --global alias.lg 'log --graph --oneline --decorate --date-relative'
80 |
81 |
82 | ### Blogs on this subject
83 | * [Git basic tips and tricks](http://git-scm.com/book/en/Git-Basics-Tips-and-Tricks)
84 | * [Must have alias examples](http://durdn.com/blog/2012/11/22/must-have-git-aliases-advanced-examples/)
85 |
86 |
87 | ## git show
88 | Git show displays the contents of a commit (description, files, tags, blobs, etc). By default it shows the log message and textual diff of the text that was modified in the commit.
89 |
90 | For tags, it shows the tag message and the referenced objects.
91 |
92 | The command takes options applicable to the git diff-tree command to control how the changes the commit introduces are shown.
93 |
94 | [TODO] what are the options for git show
95 |
96 | git show
97 | git show HEAD
98 | git show 1234567
99 | git show tag-name
100 |
101 | Using git show without specifying a commit number or tag will show you the latest commit from the branch you are currently in. This is usually the same information in *git show HEAD* as HEAD is a special tag that always points to the latest commit.
102 |
103 | [Back to top...](#top) | [Next: Chapter 08: Conflict Resolution](chapter08-conflict-resolution.html) | [Workshop homepage](index.html)
104 |
--------------------------------------------------------------------------------
/docs/git/wip.md:
--------------------------------------------------------------------------------
1 |
2 | # Working with Staging
3 |
4 | ## Removing changes from Staging
5 | Sometimes you add things to staging that you change your minde about.
6 |
7 | If a file is untracked by git (its never been part of a commit) then you can remove it from staging using the command
8 |
9 | git rm --cached filename
10 |
11 | If the file has been tracked by git, then the above command will cause the file to be removed from the repository should a further commit take place.
12 |
13 | Therefore, for tracked file that you want to unstage, you should use the command
14 |
15 | git reset HEAD filename
16 |
17 |
18 |
19 | # creating branches
20 | ## commiting
21 | ## merging
22 | ## remote branches
23 | ## deleting remote branches
24 | ## deleting local branches
25 | ## git remote purge
26 |
27 |
28 | # Working with Tags
29 | ## creating Tags
30 | ## git push --tags
31 |
32 | # Commits
33 | ## discarding a local Commits
34 | ## discarding a remote commit and resetting your local working copy
35 | git reset --hard HEAD^
36 | git checkout master
37 |
38 |
39 |
40 | # Git Log - Updating details about Remotes
41 |
42 | (see git-live script)
43 |
44 | Use git fetch --all or git remote update to get details of all the changes from every remote repository attached to the local git repository you call the command from.
45 |
46 |
47 |
48 |
49 | # Testing branches
50 |
51 | Say you want to test out your branch you have been working on but your setup is only configured to work on master, then you can push a branch from one repository to the master (or any other branch) of another repository.
52 |
53 |
54 | For example, heroku only deploys from master. You can use git to deploy your *developing* branch to your *heroku-test* application using the following notation:
55 |
56 | git push repository local-branch:remote-branch
57 |
58 | git push heroku-test developing:master
59 |
60 | In this example we are pushing the local *developing* branch to the master branch of the heroku-test remote repository. This allows you to use heroku-test application to run some web application tests (eg. selinum).
61 |
62 | You dont need to merge your developing branch until after you are happy with oyour testing.
63 |
64 |
65 |
66 | # Rebase or not rebase, that is the question
67 |
68 | ## what is Rebasing
69 | Rebasing is a way to do merging without including specific commits that would otherwise appear due to a merge.
70 |
71 | Some teams decide that having extra commits just for merges polutes the history of the project and makes it harder to understand.
72 |
73 |
74 | ## Why would you do it
75 | If you are just starting with Git, then you probably dont want to do this yet. Make sure you are comfortable with branching and merging before starting to rebase.
76 |
77 | Rebasing can work well with short lived branches where merges would otherwise happen very often, leading to a high ratio of merge commits. For these shor lived branches, using rebase helps keep a clean history.
78 |
79 | If you want to keep a branch up to date from master and dont want to include lots of commits only there because of a merge, then rebase will tidily keep your branch up to date. This makes sence if the branch is going to be around for a little while or there is active development on the master that you need to keep up with.
80 |
81 | For branches that have been around for days or weeks, its more likey that you will benefit from a merge. With a merge you get the full history detail, so its easier to see where things come from if there is a problem merging.
82 |
83 | Use rebase with care as you are re-writing history and loosing some information about where changes have come from. Make sure you dont need to know the information you are ommitting with rebase.
84 |
85 |
86 | # Interactive Rebasing
87 |
88 |
89 | ## merging two commits together
90 |
91 | If you have done two commits that should really be one, then you can use rebase interactive to join those commits (squash them in git terms).
92 |
93 | ''''''
94 | # intractively rebase the last three commits
95 | git rebase -i HEAD~2
96 | ''''
97 |
98 | # an editor opens up and lets you edit the commits, in this case, the last commit will be merged into the one before it.
99 | pick 4b65a5a Add tests
100 | pick f239187 Implement poodles
101 | squash c3f863f Add title to poodle page
102 |
103 |
104 |
105 | # Git attributes file
106 | Tell git how to manage particular file types
107 |
108 | For example:
109 |
110 | * text=auto
111 | *.rb text
112 | *.js text
113 | *.bat text eol=crlf
114 | *.sh text eol=lf
115 |
116 | *.png binary
117 |
118 |
119 |
120 |
121 | # Submodules
122 |
123 |
124 | ## Avoid double pushing
125 | As we have seen, when you make changes to a submodule, as well as pushing the changes in that submodule you also need to push the parent repository. The parent has a reference to a SHA of what it knows as the latest commit for the submodule. If the parent is pushed without the submodule, then the new commit refered to by the parent is not present in everyone elses repository.
126 |
127 | Manage this automatically using the --recurse-submodules option on-demand
128 |
129 | git push --recurse-submodules=on-demand
130 |
131 |
132 |
133 | Create an alias for this option so that you dont have to type it all (or remember it all if you pick a meaningful alias)
134 |
135 | git config alias.pushall 'push --recurse-submodules=on-demand'
136 |
137 |
138 |
139 |
140 |
141 | additional topics
142 |
143 | Repositories
144 | Commits
145 | Viewing changes
146 | Alias
147 | Going forward to fix mistakes
148 | Tags
149 | Remotes
150 | Github
151 | Branching & merging - when to do it
152 | Stashing
153 | Rebasing is evil !!!
154 | Cherry picking
155 | Patches
156 | Bisect
157 | Rerere
158 | Blame
159 | Common workflows
160 | Continuous Integration with Travis
161 |
--------------------------------------------------------------------------------
/docs/git/to-review/git-basics/wip.md:
--------------------------------------------------------------------------------
1 |
2 | # Working with Staging
3 |
4 | ## Removing changes from Staging
5 | Sometimes you add things to staging that you change your minde about.
6 |
7 | If a file is untracked by git (its never been part of a commit) then you can remove it from staging using the command
8 |
9 | git rm --cached filename
10 |
11 | If the file has been tracked by git, then the above command will cause the file to be removed from the repository should a further commit take place.
12 |
13 | Therefore, for tracked file that you want to unstage, you should use the command
14 |
15 | git reset HEAD filename
16 |
17 |
18 |
19 | # creating branches
20 | ## commiting
21 | ## merging
22 | ## remote branches
23 | ## deleting remote branches
24 | ## deleting local branches
25 | ## git remote purge
26 |
27 |
28 | # Working with Tags
29 | ## creating Tags
30 | ## git push --tags
31 |
32 | # Commits
33 | ## discarding a local Commits
34 | ## discarding a remote commit and resetting your local working copy
35 | git reset --hard HEAD^
36 | git checkout master
37 |
38 |
39 |
40 | # Git Log - Updating details about Remotes
41 |
42 | (see git-live script)
43 |
44 | Use git fetch --all or git remote update to get details of all the changes from every remote repository attached to the local git repository you call the command from.
45 |
46 |
47 |
48 |
49 | # Testing branches
50 |
51 | Say you want to test out your branch you have been working on but your setup is only configured to work on master, then you can push a branch from one repository to the master (or any other branch) of another repository.
52 |
53 |
54 | For example, heroku only deploys from master. You can use git to deploy your *developing* branch to your *heroku-test* application using the following notation:
55 |
56 | git push repository local-branch:remote-branch
57 |
58 | git push heroku-test developing:master
59 |
60 | In this example we are pushing the local *developing* branch to the master branch of the heroku-test remote repository. This allows you to use heroku-test application to run some web application tests (eg. selinum).
61 |
62 | You dont need to merge your developing branch until after you are happy with oyour testing.
63 |
64 |
65 |
66 | # Rebase or not rebase, that is the question
67 |
68 | ## what is Rebasing
69 | Rebasing is a way to do merging without including specific commits that would otherwise appear due to a merge.
70 |
71 | Some teams decide that having extra commits just for merges polutes the history of the project and makes it harder to understand.
72 |
73 |
74 | ## Why would you do it
75 | If you are just starting with Git, then you probably dont want to do this yet. Make sure you are comfortable with branching and merging before starting to rebase.
76 |
77 | Rebasing can work well with short lived branches where merges would otherwise happen very often, leading to a high ratio of merge commits. For these shor lived branches, using rebase helps keep a clean history.
78 |
79 | If you want to keep a branch up to date from master and dont want to include lots of commits only there because of a merge, then rebase will tidily keep your branch up to date. This makes sence if the branch is going to be around for a little while or there is active development on the master that you need to keep up with.
80 |
81 | For branches that have been around for days or weeks, its more likey that you will benefit from a merge. With a merge you get the full history detail, so its easier to see where things come from if there is a problem merging.
82 |
83 | Use rebase with care as you are re-writing history and loosing some information about where changes have come from. Make sure you dont need to know the information you are ommitting with rebase.
84 |
85 |
86 | # Interactive Rebasing
87 |
88 |
89 | ## merging two commits together
90 |
91 | If you have done two commits that should really be one, then you can use rebase interactive to join those commits (squash them in git terms).
92 |
93 | ''''''
94 | # intractively rebase the last three commits
95 | git rebase -i HEAD~2
96 | ''''
97 |
98 | # an editor opens up and lets you edit the commits, in this case, the last commit will be merged into the one before it.
99 | pick 4b65a5a Add tests
100 | pick f239187 Implement poodles
101 | squash c3f863f Add title to poodle page
102 |
103 |
104 |
105 | # Git attributes file
106 | Tell git how to manage particular file types
107 |
108 | For example:
109 |
110 | * text=auto
111 | *.rb text
112 | *.js text
113 | *.bat text eol=crlf
114 | *.sh text eol=lf
115 |
116 | *.png binary
117 |
118 |
119 |
120 |
121 | # Submodules
122 |
123 |
124 | ## Avoid double pushing
125 | As we have seen, when you make changes to a submodule, as well as pushing the changes in that submodule you also need to push the parent repository. The parent has a reference to a SHA of what it knows as the latest commit for the submodule. If the parent is pushed without the submodule, then the new commit refered to by the parent is not present in everyone elses repository.
126 |
127 | Manage this automatically using the --recurse-submodules option on-demand
128 |
129 | git push --recurse-submodules=on-demand
130 |
131 |
132 |
133 | Create an alias for this option so that you dont have to type it all (or remember it all if you pick a meaningful alias)
134 |
135 | git config alias.pushall 'push --recurse-submodules=on-demand'
136 |
137 |
138 |
139 |
140 |
141 | additional topics
142 |
143 | Repositories
144 | Commits
145 | Viewing changes
146 | Alias
147 | Going forward to fix mistakes
148 | Tags
149 | Remotes
150 | Github
151 | Branching & merging - when to do it
152 | Stashing
153 | Rebasing is evil !!!
154 | Cherry picking
155 | Patches
156 | Bisect
157 | Rerere
158 | Blame
159 | Common workflows
160 | Continuous Integration with Travis
161 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Practicall GitOps
2 |
3 | ```none
4 | ██████╗ ██████╗ █████╗ ██████╗████████╗██╗ ██████╗ █████╗ ██╗ ██╗ ██╗
5 | ██╔══██╗██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██║██╔════╝██╔══██╗██║ ██║ ██║
6 | ██████╔╝██████╔╝███████║██║ ██║ ██║██║ ███████║██║ ██║ ██║
7 | ██╔═══╝ ██╔══██╗██╔══██║██║ ██║ ██║██║ ██╔══██║██║ ██║ ██║
8 | ██║ ██║ ██║██║ ██║╚██████╗ ██║ ██║╚██████╗██║ ██║███████╗███████╗██║
9 | ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚══════╝╚══════╝╚═╝
10 | ```
11 |
12 | ## Book status
13 |
14 | [](https://github.com/practicalli/gitops/actions/workflows/megalinter.yaml)[](https://github.com/practicalli/gitops/actions/workflows/publish-book.yaml)
15 | [](https://github.com/practicalli/gitops/actions/workflows/pages/pages-build-deployment)
16 |
17 | [](https://github.com/practicalli/clojure-practicalli-content/issues)
18 | [](https://github.com/practicalli/clojure-practicalli-content/pulls)
19 |
20 | 
21 | 
22 |
23 |
24 |
25 |
26 | ## Creative commons license
27 |
28 |
29 |
30 | This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images & stylesheets).
31 |
32 |
33 |
34 | ## Contributing
35 |
36 | Issues and pull requests are most welcome although it is the maintainers discression as to if they are applicable. Please detail issues as much as you can. Pull requests are simpler to work with when they are specific to a page or at most a section. The smaller the change the quicker it is to review and merge.
37 |
38 | Please read the [detailed Practicalli contributing page](https://practical.li/contributing/) before raising an issue or pull request to avoid disapointment.
39 |
40 | * [Current Issues](https://github.com/practicalli/gitops/issues)
41 | * [Current pull requests](https://github.com/practicalli/gitops/pulls)
42 |
43 | [Practicalli Clojure CLI Config](clojure/clojure-cli/practicalli-config.md) provides a user level configuration used in this guide and issues and pull requests can also be made there.
44 |
45 | By submitting content ideas and corrections you are agreeing they can be used in any work by Practicalli under the [Creative Commons Attribution ShareAlike 4.0 International license](https://creativecommons.org/licenses/by-sa/4.0/). Attribution will be detailed via [GitHub contributors](https://github.com/practicalli/clojure/graphs/contributors).
46 |
47 | ## Sponsor Practicalli
48 |
49 | [](https://github.com/sponsors/practicalli-johnny/)
50 |
51 | All sponsorship funds are used to support the continued development of [Practicalli series of books and videos](https://practical.li/), although most work is done at personal cost and time.
52 |
53 | Thanks to [Cognitect](https://www.cognitect.com/), [Nubank](https://nubank.com.br/) and a wide range of other [sponsors](https://github.com/sponsors/practicalli-johnny#sponsors) for your continued support
54 |
55 |
56 | ## Star History
57 |
58 | [](https://star-history.com/#practicalli/gitops&Date)
59 |
60 |
61 | ## GitHub Actions
62 |
63 | The megalinter GitHub actions will run when a pull request is created,checking basic markdown syntax.
64 |
65 | A review of the change will be carried out by the Practicalli team and the PR merged if the change is acceptable.
66 |
67 | The Publish Book GitHub action will run when PR's are merged into main (or the Practicalli team pushes changes to the default branch).
68 |
69 | Publish book workflow installs Material for MkDocs version 9
70 |
71 |
72 | ## Local development
73 |
74 | Install mkdocs version 9 using the Python pip package manager
75 |
76 | ```shell
77 | pip install mkdocs-material=="9.5"
78 | ```
79 |
80 | Install the plugins used by the Practicalli site using Pip (these are also installed in the GitHub Action workflow)
81 |
82 | ```shell
83 | pip3 install mkdocs-material mkdocs-callouts mkdocs-glightbox mkdocs-git-revision-date-localized-plugin mkdocs-redirects pillow cairosvg
84 | ```
85 |
86 | > pillow and cairosvg python packages are required for [Social Cards](https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/)
87 |
88 | Fork the GitHub repository and clone that fork to your computer,
89 |
90 | ```shell
91 | git clone https://github.com/
30 | This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images & stylesheets).
31 |