From: Anil Belur Date: Thu, 27 Sep 2018 14:18:55 +0000 (+0530) Subject: Add Git quick start guide X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=7d9138d15ad1c036cf70a2822c970a134bc0d27f;p=releng%2Fdocs.git Add Git quick start guide The Git guide serves as a quick start guide for anyone new to Git. Jira: RELENG-875 Change-Id: I67e8b2f3c6044ec5d212209f0b8f2f4934375f73 Signed-off-by: Anil Belur --- diff --git a/docs/git.rst b/docs/git.rst new file mode 100644 index 0000000..e4e81a3 --- /dev/null +++ b/docs/git.rst @@ -0,0 +1,259 @@ +.. _lfreleng-docs-git: + +######### +Git Guide +######### + +Git is the most commonly used distributed version control system for anyone +working with a code repository. Git allows the user to create a local copy +of the remote repository and sync changes onto the server. + +Git is available as a set of CLI tools on different platforms to perform +operations such as initialize, add, commit, pull and push on +the repository and more advanced operations such as branch, merge and rebase. +Git works with GitHub, GitLab and Gerrit workflows. + +.. note:: + + `What is Git? `_ + + `Pro Git book on git-scm.com `_ + + +Prerequisites +------------- + +#. Install Git. + + For Debian based systems: + + .. code-block:: bash + + sudo apt-get install git -y + + + For rpm based systems: + + .. code-block:: bash + + sudo dnf install git -y + + + For MacOS systems, install `homebrew `_ and install Git + + .. code-block:: bash + + brew install git + +Setup Git config +================ + +To change the author name or email used to sign off a commit use the command. + +.. code-block:: bash + + git config --local user.name "Your Name" + git config --local user.email yourname@example.com + +To change the Git commit editor to vim run the command. + +.. code-block:: bash + + git config --global core.editor "vim" + +To always sign a commit by default. + +.. code-block:: bash + + git config --global gpg.gpgsign true + +To set the default gpg2 program: + +.. code-block:: bash + + git config --global gpg.program $(which gpg2) + +Sample .gitconfig +================= + +Sample ``$HOME/.gitconfig`` with other useful settings. + +.. code-block:: none + + [user] + name = + email = user@example.com + signingkey = XXXXXXXXXXXXXXXXX + [core] + editor = vim + pager = less -R + [credential] + helper = cache --timeout=3600 + [gitreview] + username = askb + [color] + ui = auto + [rerere] + enabled = true + [commit] + gpgsign = true + [gpg] + program = /usr/bin/gpg2 + [push] + sign = if-asked + [status] + submoduleSummary = false + [alias] + co = checkout + +Clone a repository +================== + +To clone a Git repository. + +.. code-block:: bash + + git clone ssh://@git.example.org:29418/.git + +.. note:: + + Use the ``--recursive-submodule`` option if repository has Git submodules. + +Auto Generate Change IDs +======================== + +To generate change-id's automatically. + +.. literalinclude:: _static/commit-hook.example + :language: bash + + +Pull Down New Source +==================== + +To pull updates from the remote repository and rebase changes on your local +branch. + +.. code-block:: bash + + git pull --rebase + +Repository status +================= + +To check the status of the repository. + +.. code-block:: bash + + git status + +Create a branch +=============== + +To create a local branch from master. + +.. code-block:: bash + + git branch -b origin/master + +Switching between branches +========================== + +To switch between a branch and the master within your repository. + +.. code-block:: bash + + git checkout + git checkout master + +Add a file +========== + +To stage a file modified in your local repository. + +.. code-block:: bash + + git add + +Commit a change +=============== + +To commit a change to your local repository. + +.. code-block:: bash + + git add + git commit --signoff --gpg-sign + +.. note:: + + The --signoff (or -s) adds a "Signed-off-by" line in the commit footer. + The --gpg-sign (or -S) signs the commit with the GPG key. + +Amend a change +============== + +To amend a change in your local repository. + +.. code-block:: bash + + git add + git commit --amend + +.. note:: + + The --signoff (or -s) adds a "Signed-off-by" line in the commit footer. + The --gpg-sign (or -S) signs the commit with the GPG key. + +Discard a change +================ + +To discard changes introduced in the last commit. + +.. code-block:: bash + + git reset --hard HEAD~1 + +Cherry-pick a commit +==================== + +To copy a commit from between branches use the ``git cherry-pick`` command. + +.. code-block:: bash + + git checkout + git log # note from the output + git checkout + git cherry-pick # use the noted earlier + +Stash changes +============= + +To stash your work temporarily and move between branches. + +.. code-block:: bash + + git stash # stash the modified files temporarily + git checkout + git stash pop # pop the modified changes + +Log of recent changes +===================== + +To view a log of the recent changes. + +.. code-block:: bash + + git log + +To revert change partially in a commit +====================================== + +To revert changes to one or more files in a commit. + +.. code-block:: bash + + git log # note the + git show -- | git apply -R # Revert the in + git add + git commit --signoff --gpg-sign --amend diff --git a/docs/index.rst b/docs/index.rst index 912139e..545df60 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ Guides: environment-overview best-practices ansible + git gerrit gpg jenkins