View source for Git/Basic Components

Git is split up into multiple different subcommands. Here are a few essential ones to understand to use git.

== Initialisation ==

This is not entirely necessary, however it helps to understand what is happening when you clone a repository and the fact that a folder can be initialised with git without being reliant on a remote repository.

When creating a new project locally, you can make the repository be version-controlled by running

<syntaxhighlight lang="sh">git init</syntaxhighlight>
If you then run <code>git status</code> you will see something like:

<pre class="txt">On branch main
nothing to commit, working tree clean</pre>

[[File:git-git_init.gif|gif showing what is explained in this section of initialising a git repo]]

=== Adding a remote ===

Adding a remote repository is not necessary unless you want to be pushing to one as some sort of backup or if you just want to share your code.

To add one (you can also have multiple), you simply run:

<syntaxhighlight lang="sh">git remote add origin <url></syntaxhighlight>

{{Note|text=
Here we are creating a remote called <code>origin</code>, you can change this name if you have multiple. The default name is <code>origin</code> and is what we will be using later on.
}}

[[File:git-git_remote_add.gif|gif showing the process of adding a remote repo and pulling from it]]

== Cloning ==

Cloning basically does everything we explained above automatically for you and then pulls the latest commits to your folder.

The command to clone a repository is:

<syntaxhighlight lang="sh">git clone <url></syntaxhighlight>
This clones the repo into the folder with the same name as the project. E.g. if I were to clone <code>git@gitlab.bath.ac.uk:cs/wiki</code>, it would create a folder called <code>wiki</code>.

If you want a custom folder name, you just simply add another parameter e.g:

<syntaxhighlight lang="sh">git clone git@gitlab.bath.ac.uk:cs/wiki bathcs_wiki</syntaxhighlight>

[[File:git-git_clone.gif|gif showing the process of cloning a repository]]

== Staging and Committing ==

Staging and committing are essential parts of git. The process goes:

* You make some changes
* You stage those changes (basically saying “yes I want these changes to be in the next commit”)
* You commit those changes

By commit, we mean creating a group of changes which gets given an identifier and a summary. We can then use this ID to revert or do something else with those changes later on.

The summary or description just helps you understand what the changes are doing, so you can easily find a commit later on.

=== Staging ===

To stage something you can:

<syntaxhighlight lang="sh">git add file/to/add # To stage one file at a time
git add .           # To stage all changes in current directory</syntaxhighlight>
You can then run:

<syntaxhighlight lang="sh">git status</syntaxhighlight>
To see the current unstaged and staged changes.

If you were wanting to unstage all the changes, you can simply go:

<syntaxhighlight lang="sh">git reset                 # to unstage all staged changes
git reset file/to/unstage # to unstage a particular file</syntaxhighlight>
{{Note|text=
Unstaging does not delete the changes, it just removes it from the “staged” list (which is used when you run <code>commit</code>)
}}

=== Committing ===

Once you have staged the changes you want in the next commit, you can run:

<syntaxhighlight lang="sh">git commit -m "Add setup to README.md"</syntaxhighlight>
Which will commit the staged changes with the message “Add setup to README.md”. If you don’t specify a message, git will open your preferred text editor where you will be forced to add one.

{{Note|text=
All commit summaries should be written in '''the present tense''' and should explain what the changes do.
}}

Options:

* Specify <code>-a</code> to include all unstaged changes as well (except for new files)
* If you add a new line after the summary, you can add a more in-depth description.


[[File:git-git_stage.gif|gif showing the process of adding a file and then staging and committing it]]

=== Amending a commit ===

This is more of an advanced command, but it can be helpful. You probably shouldn’t use this, because it will break things if other people have cloned the repository. If you want to add some changes to your previous commit, there is an <code>--amend</code> option which will add all staged changes to the previous commit. It will also give you a chance to edit the commit message.

<syntaxhighlight lang="sh">git commit --amend
git commit --amend --no-edit # If you want to keep the same commit message</syntaxhighlight>
As this changes the commit itself, if you have previously pushed that commit, you must then run <code>git push --force</code> (warning: this is a dangerous command).

{{Note|text=
Generally, you should create a new commit rather than amending an existing one.

Amending is only acceptable when you are working on your own personal branch, or if you have not yet pushed to the remote.
}}

== History ==

If you were wanting to get the id of a commit or just see the history of changes, you can look at the log via going:

<syntaxhighlight lang="sh">git log --oneline</syntaxhighlight>
{{Note|text=
If <code>--oneline</code> is not specified, it will show all the information about each commit on multiple lines (which is normally a lot harder to read)
}}

This will show you the start of the commit hash (or id) and the summary next to it, including what branch is at each commit.

[[File:git-git_log.gif|gif showing the output of running git log]]

== Branching ==

Branching is another key mechanic in git. Allowing multiple people to work on multiple different new features without getting in each others’ way.

It basically creates a parallel copy of the codebase: a “branch”. You can then add commits to this copy without affecting the original branch. Once you are happy with the changes you can create a [[#merge-or-pull-request|merge or pull request]] to then merge it back into the original branch.

Therefore the process for adding a feature on production is:

* Create a branch from <code>main</code> (normally named something like <code>&lt;username&gt;/&lt;description&gt;</code> in <code>kebab-case</code>)
* Add commits to fix the bug or add a feature
* Create a MR (or PR)
* Merge the branch back into <code>main</code>

{{Note|text=
Only maintainers can merge a branch back into <code>main</code> for security reasons and so you normally get one to “review” your MR.
}}

=== Commands ===

By default the initial branch should be <code>main</code> (you may see <code>master</code> being used which is another option for the default name). This branch normally stores the stable release of the project.

<syntaxhighlight lang="sh">git branch                  # List all local branch names
git branch branch-name      # Create a new branch from the current
git switch branch-name    # Switch to the branch "branch-name"
git switch -c branch-name # Create and switch to the branch "branch-name"</syntaxhighlight>

[[File:git-switch_branch.gif|gif showing the process of creating and switching to a new branch]]

== Pushing &amp; Pulling ==

If you have setup a remote repo, you will probably want to push and pull to it. Meaning: get (“pull”) the latest commits from it and send (“push”) your local commits to it.

To push it is as simple as:

<syntaxhighlight lang="sh">git push</syntaxhighlight>
However, when pushing a branch for the first time (after its creation not cloning) you must set its upstream:

<syntaxhighlight lang="sh">git push --set-upstream origin branch-name
# Or the shorthand:
git push -u origin branch-name</syntaxhighlight>

[[File:git-git_push.gif|gif showing the process of pushing the new branch to the remote repo]]

This tells git that when running <code>git push</code> you want to push to the remote named <code>origin</code> by default.

For pulling, its even simpler, just:

<syntaxhighlight lang="sh">git pull</syntaxhighlight>

== Merge or Pull Request ==

“Merge Requests” is what GitLab calls it and “Pull Requests” is what GitHub calls it.

These are just items or “requests” where a user wants their changes merged into the <code>main</code> branch (or any branch for that matter).

These are usually created and managed via GitHub or GitLab and allow another person to review your changes and merge them (if it is what they want).

To see how to create an MR in GitLab see [[Git/GitLab#Merge Requests|the instructions here]].