From b8e205bb07ccacf7c66c8bb49b19e344dfb7ac2b Mon Sep 17 00:00:00 2001 From: Purple Clay Date: Fri, 10 Mar 2023 05:09:57 +0000 Subject: [PATCH] docs: write documentation for release 0.2.0 (#45) --- .github/workflows/docs.yml | 6 +-- docs/git/checks.md | 2 +- docs/git/clone.md | 27 ++++++++++++++ docs/git/log.md | 76 +++++++++++++++++++++++++++++++++++++- docs/git/stage.md | 57 +++++++++++++++++++--------- docs/stylesheets/extra.css | 15 ++++++++ docs/testing/git-test.md | 26 +++++++++++++ log.go | 4 +- mkdocs.yml | 12 +++++- 9 files changed, 199 insertions(+), 26 deletions(-) create mode 100644 docs/git/clone.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index dd90fc6..45ece6e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -53,10 +53,10 @@ jobs: username: ${{ github.repository_owner }} password: ${{ secrets.GH_GHCR }} - - run: docker pull ghcr.io/purpleclay/mkdocs-material-insiders + - run: docker pull ghcr.io/purpleclay/mkdocs-material-insiders:9.0.13-insiders-4.32.0 - name: Build - run: docker run --rm -i -v ${PWD}:/docs ghcr.io/purpleclay/mkdocs-material-insiders build + run: docker run --rm -i -v ${PWD}:/docs ghcr.io/purpleclay/mkdocs-material-insiders:9.0.13-insiders-4.32.0 build - name: HTML Test uses: wjdp/htmltest-action@master @@ -84,4 +84,4 @@ jobs: - name: Deploy documentation if: ${{ startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch') }} - run: docker run --rm -i -v ${PWD}:/docs ghcr.io/purpleclay/mkdocs-material-insiders gh-deploy --force + run: docker run --rm -i -v ${PWD}:/docs ghcr.io/purpleclay/mkdocs-material-insiders:9.0.13-insiders-4.32.0 gh-deploy --force diff --git a/docs/git/checks.md b/docs/git/checks.md index 84f7dd9..f2120a0 100644 --- a/docs/git/checks.md +++ b/docs/git/checks.md @@ -24,7 +24,7 @@ func main() { } ``` -## Checking the Integrity of a Repository +## Checking the integrity of a Repository :material-new-box:{.new-feature title="Feature added on the 10th March 2023"} Check the integrity of a repository by running a series of tests and capturing the results for inspection. diff --git a/docs/git/clone.md b/docs/git/clone.md new file mode 100644 index 0000000..5d2a57e --- /dev/null +++ b/docs/git/clone.md @@ -0,0 +1,27 @@ +--- +icon: material/sheep +status: new +--- + +# Cloning a Repository + +[:simple-git:{ .git-icon } Git Documentation](https://git-scm.com/docs/git-clone) + +Clone a repository by its provided URL into a newly created directory and check out an initial branch forked from the cloned repository’s default branch. + +## Clone everything :material-new-box:{.new-feature title="Feature added on the 10th March 2023"} + +Calling `Clone` will result in a repository containing all remote-tracking branches, tags, and a complete history. + +```{ .go .select linenums="1" } +package main + +func main() { + client, _ := git.NewClient() + + _, err := client.Clone("https://github.com/purpleclay/gitz") + if err != nil { + log.Fatal("failed to clone repository") + } +} +``` diff --git a/docs/git/log.md b/docs/git/log.md index 73e404d..50da807 100644 --- a/docs/git/log.md +++ b/docs/git/log.md @@ -1,5 +1,6 @@ --- icon: material/list-box-outline +status: new --- # Inspecting the Commit Log of a Repository @@ -66,7 +67,7 @@ Printing the `Commits` property should now be an empty slice: ## View the log from a point in time -The `WithRef` option provides a starting point other than HEAD (_most recent commit_) when retrieving the log history. A reference can be a `Commit Hash`, `Branch Name`, or `Tag`. Output from this option will be a shorter, fine-tuned log. +When retrieving the log history, the `WithRef` option provides a starting point other than HEAD (_most recent commit_). A reference can be a `Commit Hash`, `Branch Name`, or `Tag`. Output from this option will be a shorter, fine-tuned log. ```{ .go .select linenums="1" } package main @@ -136,3 +137,76 @@ Printing the `Raw` output from this command: d611a22c1a009bd74bc2c691b331b9df38828dae fix: typos in file content 9b342465255d1a8ec4f5517eef6049e5bcc8fb45 feat: a brand new feature ``` + +## Cherry-picking a section of the log :material-new-box:{.new-feature title="Feature added on the 10th March 2023"} + +Cherry-pick a section of the log by skipping and taking a set number of entries using the respective `WithSkip` and `WithTake` options. If combined, skipping has a higher order of precedence: + +```{ .go .select linenums="1" } +package main + +func main() { + client, _ := git.NewClient() + + // assuming the repository has the current history: + // ~ docs: document fix + // ~ fix: filtering on unsupported prefixes + // ~ docs: create docs using material mkdocs + // ~ feat: add new support for filtering based on prefixes + // ~ initialized the repository + + log, err := client.Log(git.WithSkip(1), git.WithTake(2)) + if err != nil { + log.Fatal("failed to retrieve log using custom paths") + } + + fmt.Println(log.Raw) +} +``` + +Printing the `Raw` output from this command: + +```text +9967e3c6196422a6a97afa4b6fca9f609bb5490b fix: filtering on unsupported prefixes +1b1f4a725cfe44d5c9bd992be59f1130ed9d9911 docs: create docs using material mkdocs +``` + +## Filtering the log with pattern matching :material-new-box:{.new-feature title="Feature added on the 10th March 2023"} + +Filter the commit log to only contain entries that match any set of patterns (_regular expressions_) using the `WithGrep` option: + +```{ .go .select linenums="1" } +package main + +func main() { + client, _ := git.NewClient() + + // assuming the repository has the current history: + // ~ fix: forgot to trim whitespace from patterns + // ~ docs: document pattern matching option + // ~ feat: filter log with pattern matching + // ~ initialized the repository + + log, err := client.Log(git.WithGrep("^docs", "matching$")) + if err != nil { + log.Fatal("failed to retrieve log with pattern matching") + } + + fmt.Println(log.Raw) +} +``` + +Printing the `Raw` output from this command, with matches highlighted for reference only: + +```text +2d68a506fe7d5148db0a10ea143752991a65c26d {==docs==}: document pattern matching option +5bfd532328ed2e9ea6d3062eb3a331f42468a7e3 feat: filter log with pattern {==matching==} +``` + +### Filter entries that do not match + +Combining the `WithInvertGrep` and `WithGrep` options will inverse pattern matching and filter on log entries that do not contain any of the provided patterns. + +### Filter entries that match all patterns + +Pattern matching uses `or` semantics by default, matching on log entries that satisfy any of the defined patterns. You can change this behavior to match against all patterns using `and` semantics with the `WithMatchAll` option. diff --git a/docs/git/stage.md b/docs/git/stage.md index 20a1ecb..a4f47eb 100644 --- a/docs/git/stage.md +++ b/docs/git/stage.md @@ -1,5 +1,6 @@ --- icon: material/archive-lock-open-outline +status: new --- # Staging changes within a Repository @@ -8,9 +9,39 @@ icon: material/archive-lock-open-outline Stage changes to a particular file or folder within the current repository for inclusion within the next commit. Staging is a prerequisite to committing and pushing changes back to the repository remote. -## Staging a File or Folder +## Staging all changes :material-new-box:{.new-feature title="Feature added on the 10th March 2023"} -Calling `Stage` with a relative path to an individual file or folder will stage any changes: +By default, all files (`tracked` and `untracked`) within the current repository are staged automatically unless explicitly ignored through a `.gitignore` file: + +```{ .go .select linenums="1" } +package main + +func main() { + client, _ := git.NewClient() + + // create multiple files within the following hierarchy: + // > a.txt + // > b.txt + + _, err := client.Stage() + if err != nil { + log.Fatal("failed to stage all files") + } +} +``` + +And to verify the staged changes: + +```sh +$ git status --porcelain + +A a.txt +A b.txt +``` + +## Staging a file or folder + +Cherry-picking the staging of files and folders is accomplished using the `WithPathSpecs` option: ```{ .go .select linenums="1" } package main @@ -24,14 +55,9 @@ func main() { // > a.txt // > b.txt - _, err := client.Stage("root.txt") - if err != nil { - log.Fatal("failed to stage file root.txt") - } - - _, err := client.Stage("folder/") + _, err := client.Stage(git.WithPathSpecs("root.txt", "folder/a.txt")) if err != nil { - log.Fatal("failed to stage all changes within directory folder/") + log.Fatal("failed to stage files") } } ``` @@ -39,14 +65,9 @@ func main() { And to verify the staged changes: ```sh -$ git status - -On branch main -Your branch is up to date with 'origin/main'. +$ git status --porcelain -Changes to be committed: - (use "git restore --staged ..." to unstage) - new file: folder/a.txt - new file: folder/b.txt - new file: root.txt +A folder/a.txt +?? folder/b.txt +A root.txt ``` diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 27f1827..356df32 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -20,4 +20,19 @@ .md-typeset a:hover>span * { filter: brightness(85%); +} + +@keyframes new-feature { + 0%, 100% { + transform: scale(1) rotate(0deg); + } + + 50% { + transform: scale(1.15) rotate(10deg); + } +} + +.new-feature { + color: #006C39; + animation: new-feature 2000ms infinite; } \ No newline at end of file diff --git a/docs/testing/git-test.md b/docs/testing/git-test.md index f21cddf..a631746 100644 --- a/docs/testing/git-test.md +++ b/docs/testing/git-test.md @@ -1,5 +1,6 @@ --- icon: material/test-tube +status: new --- # Testing your Interactions with Git @@ -121,11 +122,36 @@ func TestGreatFeature(t *testing.T) { } ``` +### With clone depth :material-new-box:{.new-feature title="Feature added on the 10th March 2023"} + +Shallow clone a repository by truncating its history to a set depth. + +```{ .go .select linenums="1" } +func TestGreatFeature(t *testing.T) { + log := `(tag: 0.1.0) feat: this is a brand new feature +docs: write amazing material mkdocs documentation +ci: include github release workflow` + gittest.InitRepository(t, + gittest.WithLog(log), gittest.WithCloneDepth(1)) + + // test logic and assertions to follow ... +} +``` + +Querying the repository log: + +```text +$ git log --pretty=oneline --no-decorate --no-color + +e03726d3c24bbbab106bd1ac6231c030e1296eb9 feat: this is a brand new feature +``` + ### Option initialization order You can use any combination of options during repository initialization, but a strict order is applied. 1. `WithLog`: log history imported, both local and remote are in sync. +1. `WithCloneDepth`: shallow clone at the required depth. 1. `WithRemoteLog`: remote log history imported, creating a delta between local and remote. 1. `WithLocalCommits`: local commits created and not pushed back to remote. 1. `WithFiles` and `WithStagedFiles`: files generated and staged if needed. diff --git a/log.go b/log.go index 7d086e5..3c3e137 100644 --- a/log.go +++ b/log.go @@ -115,8 +115,8 @@ func WithRawOnly() LogOption { // WithSkip skips any number of most recent commits from within the log // history. A positive number (greater than zero) is expected. Skipping // more commits than exists, will result in no history being retrieved. -// Skipping zero commits, will retrieve the entire log. The option can -// has a higher order of precedence than [git.WithTake] +// Skipping zero commits, will retrieve the entire log. This option has +// a higher order of precedence than [git.WithTake] func WithSkip(n int) LogOption { return func(opts *logOptions) { opts.SkipCount = n diff --git a/mkdocs.yml b/mkdocs.yml index cac017c..34889c2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,6 +27,7 @@ theme: - search.highlight - search.share - search.suggest + - toc.follow icon: repo: fontawesome/brands/github font: @@ -40,6 +41,7 @@ nav: - Home: index.md - Getting Started: - Git Checks: git/checks.md + - Git Clone: git/clone.md - Git Pull: git/pull.md - Git Push: git/push.md - Git Stage: git/stage.md @@ -71,7 +73,7 @@ extra: link: https://pkg.go.dev/github.com/purpleclay/gitz name: Gitz GoDocs status: - new: New Feature + new: New Features Added deprecated: No Longer Supported plugins: @@ -85,12 +87,18 @@ plugins: minify_html: true - search - social + - typeset markdown_extensions: + - abbr - admonition - attr_list - def_list - footnotes + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic - pymdownx.details - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji @@ -100,10 +108,12 @@ markdown_extensions: line_spans: __span pygments_lang_class: true - pymdownx.inlinehilite + - pymdownx.mark - pymdownx.snippets - pymdownx.superfences - pymdownx.tabbed: alternate_style: true + - pymdownx.tilde - md_in_html - meta - toc: