\label{doc_Git_md_md_doc_Git}%
\Hypertarget{doc_Git_md_md_doc_Git}%
 \hypertarget{doc_Git_md_autotoc_md2693}{}\doxysection{Cheat Sheet\+: Basic Git Commands}\label{doc_Git_md_autotoc_md2693}

\begin{DoxyCode}{0}
\DoxyCodeLine{git add readme.md   \# adds the changes of the file `readme.md` to the staging area}
\DoxyCodeLine{git add .           \# adds all changes of files in the current directory (recursively) to the staging area}
\DoxyCodeLine{git add -\/-\/all       \# adds all changes of files in the repository to the staging area}
\DoxyCodeLine{git commit -\/a       \# executes a commit that automatically stages all changed and deleted files before}
\DoxyCodeLine{git checkout -\/b     \# Create a new local branch based on the current branch}
\DoxyCodeLine{git pull            \# Pull changes from the current remote branch}
\DoxyCodeLine{git push            \# Push changes to the current remote branch}
\DoxyCodeLine{git stash           \# Puts all changes in an dirty wirkling directory aside}
\DoxyCodeLine{git stash apply     \# Reapplies stashed changes on the current branch}

\end{DoxyCode}
\hypertarget{doc_Git_md_autotoc_md2694}{}\doxysection{Installation}\label{doc_Git_md_autotoc_md2694}

\begin{DoxyItemize}
\item \href{https://git-scm.com/download/win}{\texttt{ Windows}}
\item \href{https://git-scm.com/download/mac}{\texttt{ mac\+OS}}
\item \href{https://git-scm.com/download/linux}{\texttt{ Linux}}
\end{DoxyItemize}

If you are uncomfortable with command line interfaces, there are also \href{https://git-scm.com/downloads/guis}{\texttt{ plenty of GUI options available}}.\hypertarget{doc_Git_md_autotoc_md2695}{}\doxysection{Basic Configuration}\label{doc_Git_md_autotoc_md2695}
To configure git, you can use the {\ttfamily git config} command. You can configure each project individually, just by running {\ttfamily git config $<$setting$>$ $<$value$>$} anywhere within a checked out repository, or for all projects for a user on the local machine using {\ttfamily git config -\/-\/global $<$setting$>$ $<$value$>$}. We recommend you set the following configuration options, when using git\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git config merge.ff false \# Git will always create a commit, when trying to merge}
\DoxyCodeLine{git config pull.rebase true \# Automatically rebase when pulling}

\end{DoxyCode}


Also ensure that you have your username and e-\/mail configured, so your work can be attributed to you\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git config -\/-\/global user.name "{}Your Name"{}}
\DoxyCodeLine{git config -\/-\/global user.email "{}yourname@yourdomain.com"{}}

\end{DoxyCode}
\hypertarget{doc_Git_md_autotoc_md2696}{}\doxysection{The Commit Message}\label{doc_Git_md_autotoc_md2696}
A commit message should have the following syntax\+: {\ttfamily component\+: short change description}

For a clean and meaningful log the commit message should fulfill the following\+:


\begin{DoxyItemize}
\item use imperative in the subject line
\item the subject line should not be longer than 50 characters
\item start the subject line with the module name (e.\+g. resolver\+:, cpp bindings\+:)
\item separate subject from body with a blank line
\item in the body describe in detail what you did, and possibly why
\item metadata like \char`\"{}\+Fixes \#123\char`\"{} should be kept at the bottom of the commit message and definitely not in the title
\end{DoxyItemize}

Most commits should have a longer description in the body.\hypertarget{doc_Git_md_autotoc_md2697}{}\doxysubsection{Git\+Hub\+: Attributing Co-\/\+Authors}\label{doc_Git_md_autotoc_md2697}
If multiple people worked on a commit, Git\+Hub, supports a nice way to represent this. You can attribute them by leaving two blank lines at the end and then add a single line of {\ttfamily Co-\/authored-\/by\+: NAME $<$NAME@EXAMPLE.\+COM$>$} for every other person that worked on it. \href{https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors}{\texttt{ More Details here}}\hypertarget{doc_Git_md_autotoc_md2698}{}\doxysection{Remote Branches}\label{doc_Git_md_autotoc_md2698}
To list all remote branches use\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git branch -\/a}

\end{DoxyCode}


To checkout a remote branch initially use\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git checkout -\/b <branchname> origin/<branchname>}

\end{DoxyCode}


Once you have done this, it will be a local branch, too. Following remote branches should exist\+: \begin{DoxyVerb}master
\end{DoxyVerb}
 This is the development branch. Please try to not work directly on it, but instead you should use feature branches. So the only commits on master should be non-\/fastforward merges from features branches. Commits on master should always compile, and all test cases should pass successfully. (see config option above)\hypertarget{doc_Git_md_autotoc_md2699}{}\doxysubsection{Communication Methods}\label{doc_Git_md_autotoc_md2699}
To communicate with remote branches, Git supports the file protocol (acessible through the local file system), http and ssh. We generally recommend ssh, as it is encrypted and authentication with ssh-\/keys is simple and secure.\hypertarget{doc_Git_md_autotoc_md2700}{}\doxysubsubsection{Git\+Hub\+: Adding/creating an SSH Key}\label{doc_Git_md_autotoc_md2700}
Git\+Hub supports both HTTP and SSH for communication. Using SSH, you can remove the annoyance of having to enter your password every time. To learn how to add an SSH-\/\+Key follow \href{https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account}{\texttt{ this guide provided by Git\+Hub}}.\hypertarget{doc_Git_md_autotoc_md2701}{}\doxysection{Local Branches}\label{doc_Git_md_autotoc_md2701}
You should always make your own feature branch with\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git checkout -\/b <feature-\/branch-\/name>}

\end{DoxyCode}


On this branch it is not so important that every commit compiles or all test cases run.

To merge a branch use (no-\/fastforward)\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git merge -\/-\/no-\/ff <branchname>}

\end{DoxyCode}


If you already did some commits, but want them in a branch, you can do\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git branch foo}
\DoxyCodeLine{git reset HEAD\string^\string^  \# for 2 commits back}
\DoxyCodeLine{git reset origin/master}
\DoxyCodeLine{}
\DoxyCodeLine{git-\/ref-\/log \# recover}

\end{DoxyCode}
\hypertarget{doc_Git_md_autotoc_md2702}{}\doxysection{Working with forks}\label{doc_Git_md_autotoc_md2702}
We recommend you use your own fork of the main {\ttfamily libelektra} repository, if you want to contribute. For more information on creating a fork, please take a look at \href{https://docs.github.com/en/github/getting-started-with-github/fork-a-repo}{\texttt{ Git\+Hub\textquotesingle{}s tutorial}}.

Once you have set up and cloned your fork, you need to keep it in sync with the main repository. To do that, we recommend you never directly commit anything to your fork\textquotesingle{}s {\ttfamily master} branch. You also need to add a remote for the main repository\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\# We assume the remote for your fork is called `origin` (the default).}
\DoxyCodeLine{git remote add upstream https://github.com/ElektraInitiative/libelektra.git}

\end{DoxyCode}


When you want to sync changes from the main repository into your fork, you can use these commands\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{git fetch upstream master:master}
\DoxyCodeLine{git push orign master:master}

\end{DoxyCode}


\begin{quote}
{\bfseries{Note}}\+: These commands work with any branch checked out. You don\textquotesingle{}t need to switch to the {\ttfamily master} branch first. However, this only works, if you have not modified your {\ttfamily master} branch, i.\+e. the latest commit in your forked {\ttfamily master} branch was once the latest commit in the main {\ttfamily master} branch. \end{quote}
\hypertarget{doc_Git_md_autotoc_md2703}{}\doxysection{Rebasing branches}\label{doc_Git_md_autotoc_md2703}
When you work on a local feature branch, it might happen that a change occurs within the master branch, that introduces merge conflicts. I.\+e. if you create a pull request, it cannot be merged into master automatically anymore. In these cases, we expect you to rebase your feature branch, so it can be merged automatically once again.

To achieve this, make sure you have your master branch synced up. Then switch to the feature branch you want to update using {\ttfamily git checkout $<$feature-\/branch-\/name$>$} and then type {\ttfamily git rebase master}. Sometimes, this will result in a merge conflict.

If you already have pushed changes from your feature branch to a remote branch, you\textquotesingle{}ll need to either overwrite it using {\ttfamily git push -\/-\/force} or push to a new remote branch.\hypertarget{doc_Git_md_autotoc_md2704}{}\doxysubsection{Resolving merge conflicts}\label{doc_Git_md_autotoc_md2704}
To resolve merge conflicts, edit the files that need to be merged manually. You can check which files need to be merged using {\ttfamily git status}. After you are done merging a file manually, you can use {\ttfamily git add $<$path-\/to-\/file$>$} and when you have merged all files, continue with {\ttfamily git rebase -\/-\/continue}.

\begin{quote}
{\bfseries{Note}}\+: Keep in mind that manual merges within a rebase are potentially destructive. If you accidentally remove changes you\textquotesingle{}ve done in your feature branch, you might be able to recover them using \href{https://git-scm.com/docs/git-reflog/2.39.0}{\texttt{ git-\/reflog}}, but they could also be deleted by the \href{https://git-scm.com/docs/git-gc}{\texttt{ git-\/gc}}. If you\textquotesingle{}re new to manually merging files, consider creating a new branch from your feature branch using {\ttfamily git checkout -\/b $<$new-\/branch-\/name$>$} on which you can perform the merge without risk. When you\textquotesingle{}re stuck on a manual merge, you can also always abort the rebase using {\ttfamily git rebase -\/-\/abort} \end{quote}
\hypertarget{doc_Git_md_autotoc_md2705}{}\doxysection{Further resources}\label{doc_Git_md_autotoc_md2705}

\begin{DoxyItemize}
\item \href{https://git-scm.com/book/en/v2}{\texttt{ Git Book}}
\item \href{https://docs.github.com/en}{\texttt{ Git\+Hub Docs}} 
\end{DoxyItemize}