From d751c09fab66392163e25c8ebb0659214e769f44 Mon Sep 17 00:00:00 2001
From: John Practicalli <250870+practicalli-john@users.noreply.github.com>
Date: Fri, 11 Mar 2022 06:54:23 +0000
Subject: [PATCH] [git] document configuration of Magit Forge and Git identity
 (#15388)

Add documentatation to the Spacemacs Git layer describing how to configure basic git identity and more importantly how to configure Magit Forge to access GitHub / GitLab using a machine configuration and an encrypted file to hold the personal access token.
---
 CHANGELOG.develop                     |  2 +
 layers/+source-control/git/README.org | 65 ++++++++++++++++++++++++++-
 2 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.develop b/CHANGELOG.develop
index 821fa5428..2d4c3f723 100644
--- a/CHANGELOG.develop
+++ b/CHANGELOG.develop
@@ -2173,6 +2173,8 @@ Other:
   - Restore magit transient args between sessions (thanks to duianto)
 - Improvements:
   - Added orgit-forge (thanks to Ag Ibragimov)
+  - Add Magit Forge configuration documentation & basic git configuration
+    (thanks to practicalli-john)
 **** Gnus
 - Key bindings:
   - Added ~g r~ for =gnus-group-get-new-news= (thanks to Matthew Leach)
diff --git a/layers/+source-control/git/README.org b/layers/+source-control/git/README.org
index d80b6c729..b6d565ea3 100644
--- a/layers/+source-control/git/README.org
+++ b/layers/+source-control/git/README.org
@@ -10,6 +10,8 @@
 - [[#install][Install]]
   - [[#layer][Layer]]
   - [[#git][Git]]
+    - [[#basic-git-configuration][Basic Git configuration]]
+    - [[#using-ssh-urls-for-remote-repositories][Using SSH URLs for remote repositories]]
   - [[#magit-status-fullscreen][Magit status fullscreen]]
   - [[#magit-auto-complete][Magit auto-complete]]
   - [[#magit-plugins][Magit Plugins]]
@@ -19,6 +21,8 @@
     - [[#magit-todos][magit-todos]]
   - [[#global-git-commit-mode][Global git commit mode]]
   - [[#forge][Forge]]
+    - [[#magit-forge-configuration][Magit Forge configuration]]
+    - [[#ms-windows-support][MS Windows support]]
   - [[#org-integration][Org integration]]
 - [[#working-with-git][Working with Git]]
   - [[#magit][Magit]]
@@ -47,7 +51,8 @@ This layers adds extensive support for [[http://git-scm.com/][git]] to Spacemacs
 - git grep with [[https://github.com/yasuyk/helm-git-grep][helm-git-grep]]
 - org integration with magit via [[https://github.com/magit/orgit][orgit]]
 
-New to Magit? Checkout the [[https://magit.vc/about/][official intro]].
+New to Magit? Checkout the [[https://magit.vc/about/][official intro]] and [[https://practical.li/spacemacs/source-control/][Practicalli Spacemacs]]
+guide to configuring and using the Git and version control layers.
 
 * Install
 ** Layer
@@ -59,6 +64,24 @@ file.
 Of course if your OS does not ship with git (!) you'll have to install it
 on your machine. You can download it from the [[http://git-scm.com/downloads][download page]].
 
+*** Basic Git configuration
+Define a git identity using the =git= commands in a terminal window
+replacing =username= and =name@domain.tld= with your own values
+
+#+begin_src shell
+  git config --global user.name "username"
+  git config --global user.email "name@domain.tld"
+#+end_src
+
+*** Using SSH URLs for remote repositories
+[[https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key][Generate an SSH key]] to use SSH URLs to access remote repositories.
+Add the SSH key to your account on the remote service managing repository access.
+An SSH key removes the need to provide login details for each request from Magit
+to the remote repository service.
+
+- [[https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account][GitHub SSH key documentation]]
+- [[https://docs.gitlab.com/ee/ssh/#add-an-ssh-key-to-your-gitlab-account][GitLab SSH key documentation]]
+
 ** Magit status fullscreen
 To display the =magit status= buffer in fullscreen set the variable
 =git-magit-status-fullscreen= to =t= in your =dotspacemacs/user-init= function.
@@ -136,6 +159,46 @@ To enable it you have to add the following lines to your
 #+END_SRC
 
 ** Forge
+Magit Forge can view and create issues & pull requests with forges
+(e.g. GitHub, GitLab)
+
+Magit Forge requires a username for the respective forge and will prompt for a
+username if not found, writing it to  =~/.gitconfig=
+
+Explicitly define a forge identity using the `git` command.
+
+For GitHub:
+
+#+begin_src shell
+  git config --global github.user "username"
+#+end_src
+
+For GitLab:
+
+#+begin_src shell
+  git config --global gitlab.user "username"
+#+end_src
+
+See the official [[https://magit.vc/manual/forge/Getting-Started.html#Getting-Started][Magit Forge]] and [[https://magit.vc/manual/ghub/Getting-Started.html][GHub Getting Started]] for general guides or follow
+a community written [[https://practical.li/spacemacs/source-control/forge-configuration.html][Spacemacs specific guide to configuring Magit Forge]].
+
+*** Magit Forge configuration
+For each forge (e.g. GitHub, GitLab), add a machine configuration to the
+PGP encrypted =~/.authinfo.gpg= file.
+Detailed instructions to [[https://practical.li/spacemacs/source-control/forge-configuration.html#create-an-encrypted-authinfogpg-file][create an encrypted .authinfo.gpg file with Spacemacs]]
+
+The machine configuration should use your forge username and personal access token
+GitHub token permissions: =repo=, =user= and =read:org=
+GitLab token permissions: =api=
+
+- [[https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token][GitHub personal access token documentation]]
+- [[https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token][GitLab personal access token documentation]]
+
+#+BEGIN_SRC sh
+  machine api.github.com login forge-username^forge password 01personal02access03token
+#+END_SRC
+
+*** MS Windows support
 The =forge= package uses =emacsql= which requires a C compiler to be available
 on MS Windows, see issue [[https://github.com/skeeto/emacsql/issues/46]].