GEMSTONE: Add 5 new git and gh gemstones

docs/gemstones/git/feature_branch_workflow.md

@@ -0,0 +1,86 @@
+---
+title: Feature Branch Workflow in Git
+author: Wale Soyinka
+contributors: 
+tags:
+  - git
+  - Feature Branch Workflow
+  - GitHub
+  - gh
+  - git fetch
+  - git add
+  - git pull
+  - git checkout
+  - 
+---
+
+## Feature Branch Workflow
+
+This popular git workflow involves creating new branches for every new feature or fix directly in the main repository. 
+It’s usually employed in projects where contributors have direct push access to the repository.
+
+This Gemstone outlines the process of setting up a local repository to work on and contribute to the `rocky-linux/documentation` project using the Git Feature Branch Workflow. 
+
+The user "rockstar" has forked this repository, and we will use `https://github.com/rockstar/documentation` as the origin.
+
+## Prerequisites 
+
+- A GitHub account and a fork of the project (e.g., `https://github.com/rockstar/documentation`).
+- `git` and `GitHub CLI (gh)` installed.
+
+## Procedure
+
+1. If not already done, clone your fork:
+   ```bash
+   git clone https://github.com/rockstar/documentation.git
+   cd documentation
+   ```
+2. Add the upstream remote:
+   ```bash
+   git remote add upstream https://github.com/rocky-linux/documentation.git
+   ```
+3. Fetch Upstream changes:
+   ```bash
+   git fetch upstream
+   ```
+4. Create a New Feature Branch:
+   ```bash
+   git checkout -b feature-branch-name
+   ```
+5. Make changes, add new files and commit them:
+
+     ```bash
+     git add .
+     git commit -m "Implementing feature X"
+     ```
+6. Keep Your Branch Updated. Regularly merge changes from upstream to avoid conflicts:
+     ```bash
+     git pull upstream main --rebase
+     ```
+7. Push to your fork, type:
+   ```bash
+   git push origin feature-branch-name
+   ```
+8. Create a Pull Request:
+   ```bash
+   gh pr create --base main --head rockstar:feature-branch-name --title "New Feature X" --body "Long Description of the feature"
+   ```
+
+## Conclusion
+
+The Feature Branch workflow is a common collaboration technique, allowing teams to work concurrently on various aspects of a project while maintaining a stable main codebase. 
+
+The high-level steps involved are:
+
+1. Clone the Main Repository: Directly clone the main project repository to your local machine.
+2. Create a Feature Branch: For every new task, create a new branch off the main branch with a descriptive name.
+3. Commit Changes: Work on the feature or fix in your branch and commit changes.
+4. Keep Branch Updated: Regularly merge or rebase with the main branch to stay updated with its changes.
+5. Open a Pull Request: Once your feature is ready, push the branch to the main repository and open a PR for review.
+6. Code Review and Merge: After review and approval, the branch is merged into the main branch.
+
+*Benefits*:
+
+- Streamlines contributions for regular contributors with direct repository access.
+- Ensures each feature is reviewed before being integrated into the main codebase.
+- Helps maintain a clean and linear project history.

docs/gemstones/git/fork_and_branch_workflow.md

@@ -0,0 +1,97 @@
+---
+title: Fork and Branch Git workflow
+author: Wale Soyinka
+contributors:
+tags:
+  - GitHub
+  - git
+  - gh
+  - git fetch
+  - git add
+  - git pull
+  - git checkout
+  - gh repo
+  - 
+---
+
+## Fork and Branch Workflow
+
+In this workflow type, contributors fork the main repository to their own GitHub account, create feature branches for their work, and then submit contributions via pull requests from these branches.
+
+This Gemstone walks-through how to set up a local repository for contributing to a GitHub project. It starts with the initial project forking, local and remote repositpry setup, commiting changes and finally creating a pull request (PR) to submit your contributions.
+
+## Prerequisites 
+
+- A GitHub account.
+- `git` and `GitHub CLI (gh)` installed on your system.
+- A personal fork of the project on GitHub.
+
+## Procedure 
+
+1. If it doesn't already exist, create a fork of the project using the gh utility. Type:
+   ```
+   gh repo fork rocky-linux/documentation --clone=true --remote=true
+   ```
+   The options used in this *gh repo fork* command are:
+   - `--clone=true`: Clones the forked repository to your local machine.
+   - `--remote=true`: Adds the original repository as a remote, allowing you to sync future updates.
+2. Navigate to the local repository directory. Type:
+   ```
+   cd documentation
+   ```
+3. Verify that all the relevant remote repos have been properly configured in your local repo, type:
+   ```
+   git remote -vv
+   ```
+4. Fetch latest changes from upstream remote:
+   ```
+   git fetch upstream
+   ```
+5. Create and checkout a new feature branch named your-feature-branch:
+   ```
+   git checkout -b your-feature-branch
+   ```
+6. Make changes, add new files and commit your changes to your local repo:
+   ```
+   git add .
+   git commit -m "Your commit message"
+   ```
+7. Sync with the main branch of the remote repo named `upstream`:
+   ```
+   git pull upstream main
+   ```
+8. Push changes to your Fork**:
+   ```
+   git push origin your-feature-branch
+   ```
+9. Finally, create a Pull Request (PR) using the `gh` CLI application:
+   ```
+   gh pr create --base main --head your-feature-branch --title "Your PR Title" --body "Description of your changes"
+   ```
+   The options used in this *gh pr create* command are:
+
+   `--base` main: Specifies the base branch in the upstream repository where the changes are to be merged.
+   `--head` your-feature-branch: Indicates the head branch from your fork that contains the changes.
+   `--title` "Your PR Title": Sets the title for the pull request.
+   `--body` "Description of your changes": Provides a detailed description of the changes in the pull request.
+
+
+## Conclusion
+
+The Fork and Branch workflow is another common collaboration technique.
+The high-level steps involved are:
+
+1. Fork the Repository: Create a personal copy of the project's repository on your GitHub account.
+2. Clone the Fork: Clone your fork to your local machine for development work.
+3. Set Upstream Remote: Add the original project repository as an 'upstream' remote to stay updated with its changes.
+4. Create a Feature Branch: For each new feature or fix, create a new branch from the updated main branch. Branch names should be descriptive of the feature or fix.
+5. Commit Changes: Make your changes and commit them with clear and concise commit messages.
+6. Sync with Upstream: Regularly sync your fork and feature branch with the upstream main branch to incorporate any new changes and reduce merge conflicts.
+7. Create a Pull Request (PR): Push your feature branch to your fork on GitHub and open a PR against the main project. Your PR should clearly describe the changes and link to any relevant issues.
+8. Respond to Feedback: Collaborate on review feedback until the PR is either merged or closed.
+
+Benefits:
+
+- Isolates development work to specific branches, keeping the main branch clean.
+- Makes it easier to review and integrate changes.
+- Reduces the risk of conflicts with the main project’s evolving codebase.

docs/gemstones/git/git_pull_vs_git_fetch.md

@@ -0,0 +1,62 @@
+---
+title: Using git pull and git fetch
+author: Wale Soyinka
+contributors: 
+tags:
+  - Git
+  - git pull
+  - git fetch
+---
+
+## Introduction 
+
+This Gemstone explains the differences between `git pull` and `git fetch` commands. It also outlines when to appropriately use each command.
+
+## Git Fetch vs Git Pull 
+
+### Git Fetch
+
+git fetch downloads changes from a remote repository, but doesn't integrate them into your local branch.
+
+It is especially useful for seeing what others have committed without merging those changes into your local branch.
+
+1. List the currently checked out branch
+     ```
+     git branch
+     ```
+2. Fetch changes from the main branch of a remote repo named origin. Type:
+     ```
+     git fetch origin main
+     ```
+3. Compare the changes beween the HEAD of your local repo and remote origin/main repo. 
+     ```
+     git log HEAD..origin/main
+     ```
+
+### Git Pull
+
+Git Pull downloads changes and merges them into your current branch.
+Useful for quickly updating your local branch with changes from the remote repository.
+
+1. Pull and Merge Changes**:
+     ```
+     git pull origin main
+     ```
+2. Review merged changes**:
+     ```
+     git log
+     ```
+
+## Additional Notes
+
+- **Use `git fetch`**:
+-- When you need to review changes before merging.
+-- To avoid unwanted changes or conflicts in your local branch.
+
+- **Use `git pull`**:
+-- When you want to update your local branch with the latest commits.
+-- For quick, straightforward updates without needing to review changes first.
+
+## Conclusion
+
+Understanding the distinctions between `git fetch` and `git pull` is vital for effective Git workflow management. It is important to choose the right command based on your requirements when working or colloborating via version control systems like github, git, gitlab, gitea and so on.

docs/gemstones/git/git_remote_add.md

@@ -0,0 +1,71 @@
+---
+title: Adding a remote repository using git CLI
+author: Wale Soyinka
+contributors:
+tags:
+  - GitHub
+  - git
+  - git remote
+  - git fetch
+---
+
+## Introduction 
+
+This Gemstone illustrates how to add a specific remote repository, to an existing local clone of a FOSS project using the Git command-line interface. 
+We'll use the repository of the Rocky Linux documentation project as our example FOSS project - `https://github.com/rocky-linux/documentation.git`
+
+## Prerequisites 
+
+- A GitHub account.
+- `git` installed on your system.
+- A local clone of a FOSS project repository.
+
+## Procedure
+
+1. Open a terminal and change your working directory to the folder containing your 
+  local clone of the project. 
+  For example if you cloned the github repo to  ~/path/to/your/rl-documentation-clone, type
+     ```bash
+     cd ~/path/to/your/rl-documentation-clone
+     ```
+2. Before making any changes, list the remotes that you currently have configured. Type:
+   ```bash
+   git remote -vv
+   ```
+   If this is a freshly cloned repo, you will likely see a lone remote named `origin` in your output.
+3. Add the Rocky Linux Documentation Repository 
+  (`https://github.com/rocky-linux/documentation.git`) as a new remote to your local repository. Here we'll assign upstream as the name for this particular remote. Type:
+
+     ```bash
+     git remote add upstream https://github.com/rocky-linux/documentation.git
+     ```
+4. To further emphasis that the names assigned to remote repositories are arbitrary,
+  create another remote named rocky-docs that points to the same repo, by running:
+   ```bash
+   git remote add rocky-docs https://github.com/rocky-linux/documentation.git
+   ```
+5. Confirm that the new remote repository has been added successfully:
+     ```bash
+     git remote -v
+     ```
+     You should see `upstream` listed along with its URL.
+6. Optionally, before you start making any changes to your local repo, you can fetch 
+   data from the Newly Added Remote.
+  Fetch branches and commits from the newly added remote by running:
+     ```bash
+     git fetch upstream
+     ```
+
+## Additional Notes
+
+- *Origin*: This is the default name Git gives to the remote repository from which you
+   cloned. It's like a nickname for the repository URL. When you clone a repository, this remote repository is automatically set as "origin" in your local Git configuration. The name is arbitrary but conventional.
+
+- *Upstream*: This often refers to the original repository when you've forked a project.
+   In open-source projects, if you fork a repository to make changes, the forked repository is your "origin", and the original repository is typically referred to as "upstream". The name is arbitrary but conventional.
+
+   This subtle distinction between the uses/assignment of origin and remote is crucial for contributing back to the original project through pull requests.
+
+## Conclusion
+
+Using a descriptive name and adding a specific remote repository to a local clone of a FOSS project is easy with the git CLI utility. This allows you to sync with and contribute to various repositories effectively.

docs/gemstones/git/tracking_and_nontracking_branch.md

@@ -0,0 +1,60 @@
+---
+title: Tracking vs Non-Tracking Branch in Git
+author: Wale Soyinka
+contributors:
+tags:
+  - git
+  - git branch
+  - Tracking Branch
+  - Non-Tracking Branch
+---
+
+## Introduction 
+
+This Gemstone delves into tracking and non-tracking branches in Git. It also includes steps to verify and convert between the branch types. 
+
+## Tracking Branch
+
+A tracking branch is a branch that is linked to a remote branch.
+
+1. Create a new branch named my-local-branch. Make the new local branch track the main branch of the remote repository named origin. Type:  
+  ```bash
+  git checkout -b my-local-branch origin/main
+  ```
+2. Use the `git branch -vv` command to verify that the branch is a tracking branch. Type: 
+  ```bash
+  git branch -vv
+  ```
+  Look for branches with `[origin/main]` indicating they are tracking `origin/main`.
+
+## Non-Tracking Branch
+
+A non-tracking branch is a branch that operates independently from remote branches.
+
+1. Create a new non-tracking local branch named my-feature-branch. Type:
+  ```bash
+  git checkout -b my-feature-branch
+  ```
+2. Non-tracking branches won’t show a remote branch next to them in the git branch -vv output. Check if my-feature-branch is a non-tracking branch. 
+
+## Converting Non-Tracking to Tracking
+
+1. Optionally, first make sure the latest changes from the main branch are merged into the target branch. Type:
+     ```bash
+     git checkout my-feature-branch
+     git merge main
+     ```
+2. Set up tracking to a remote branch:
+     ```bash
+     git branch --set-upstream-to=origin/main my-feature-branch
+     ```
+     Output: `Branch 'my-feature-branch' set up to track remote branch 'main' from 'origin'.`
+3. Verify the change. Type:
+     ```bash
+     git branch -vv
+     ```
+     Now, `my-feature-branch` should show `[origin/main]` indicating it's tracking.
+
+## Conclusion
+
+Understanding the nuances between tracking and non-tracking branches is vital in Git. This Gemstone clarifies these concepts and also demonstrates how to identify and convert between these branch types for optimal git workflow management.