EllieClifford: Redirected page to Git and GitHub

2021-04-23T21:14:38Z

← Older revision		Revision as of 21:14, 23 April 2021
Line 1:		Line 1:
	[[~~Category:Deleted~~]]		#REDIRECT [[Git_and_GitHub]]

EllieClifford: "Fix broken links"

2021-04-23T21:11:32Z

"Fix broken links"

Show changes

EllieClifford: "Add page on Git"

2021-04-23T20:43:48Z

"Add page on Git"

New page

= Git and GitHub =

Git is a distributed version control system used for most software projects
worldwide. Here at CUSF, we plan to use Git for CAD as well.

GitHub is one of many providers of Git remotes, i.e. a centralized place to
store Git repositories. It is used by CUSF, you can find our organisation on
GitHub [https://github.com/cuspaceflight here]

== Installation ==

=== Linux ===

If you’re using Linux you probably know what you’re doing. If not, just… use
your package manager…?

=== Windows ===

You may also be interested in downloading the ''Windows Terminal'' from the
Microsoft Store for a slightly nicer experience.

==== via Git Bash ====

The simplest solution is to use Git Bash, which you can get from
[https://git-scm.com/download the official download page]. The default options
are fine. The main drawback is that Git bash does not give you access to the
Git man pages (manuals).

==== via MSYS2 ====

A more extensible solution is to use [https://www.msys2.org/ MSYS2], which
gives you access to a native UNIX-like environment. You can then install Git
(and the man pages, which is highly recommended) from an MSYS2 terminal via:

<syntaxhighlight lang="bash"g>
pacman -S git man-db man-pages-posix
</syntaxhighlight>

==== via Windows Subsystem for Linux ====

This is not recommended right now, as it is not yet compatible with [[Charon]]

=== MacOS ===

''Adapted from docs written by [https://weixuanz.github.io/ Weixuan Zhang]''

Typically on macOS the package manager to use is [https://brew.sh Homebrew],
which you can install from a terminal with

<syntaxhighlight lang="bash"g>
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
</syntaxhighlight>

Then you can install packages via:

<syntaxhighlight lang="bash"g>
brew install git
</syntaxhighlight>

<blockquote>
If you encounter a permission error, be cautious when you copy and
paste solutions from StackOverflow. Make sure you don’t mistakenly give root
privileges to all files in <code>/usr/local/</code>.
</blockquote>

== Usage ==

This is not comprehensive, only a quick reference for basic usage. Your first
port of call if you want to know more should be the man pages (manuals), which
are accessible via:

<syntaxhighlight lang="bash"g>
git clone https://github.com/username/project
</syntaxhighlight>

If in doubt, type <code>git status</code> into the terminal. It will give you
some informative output of what is currently going on.

=== UNIX-like terminals ===

'''BEWARE: files deleted on a terminal will not usually go to the recycle bin'''

Refer to
[https://docs.srcf.net/learn/tutorials/more-terminal.html#more-terminal these]
docs from the SRCF for a good intro to UNIX-like terminals (i.e. the kind of
terminal you should be using Git from, see [[Installation]]. Some understanding
of these terminals is required to use Git. There are graphical clients for Git,
but usually they should be avoided, as they obscure what's going on (and won't
work with [[Charon]]).

=== Repositories ===

Repositories are usually self contained projects. They correspond to a
folder on your computer, and are usually synced to a remote (e.g. GitHub).

To 'clone' an existing repository, i.e. copy the latest version from GitHub:

<syntaxhighlight lang="bash"g>
git clone https://github.com/username/project
</syntaxhighlight>

This will create a local directory <code>project</code> containing the
repository.

If you want to create a repository to use with GitHub, it's probably easiest to
click the plus button on the GitHub website in the top right and let it tell
you what to do.

If you are creating a repository just locally, the following command will turn
the current directory into a repository:

<syntaxhighlight lang="bash"g>
git init
</syntaxhighlight>

=== Commits ===

To 'commit' is to make a record of your changes. Except in some special
circumstances, commits will always exist in the history of the repository, so
that changes in the project can be tracked and rolled back if necessary.

In order to make a commit, you first need to 'add' changes to Git, which means
making Git aware of the changes. Having to do this can be useful if you only
want to commit some of the changes that you have made.

Note that you can use <code>git status</code> to see what changes have been
added

To add just the file <code>file</code>:

<syntaxhighlight lang="bash"g>
git add file
</syntaxhighlight>

To add all files in the current directory:

<syntaxhighlight lang="bash"g>
git add .
</syntaxhighlight>

To commit the changes that have been added:

<syntaxhighlight lang="bash"g>
git commit -m "Commit message"
</syntaxhighlight>

"Commit message" should be a short description of what you have changed.
(Include the quotes)

=== Pushing and Pulling ===

In order to sync your local changes with the remote (e.g. GitHub), you must
push and pull: pushing uploads your changes to the remote, and pulling gets the
changes from the remote.

To pull:

<syntaxhighlight lang="bash"g>
git pull
</syntaxhighlight>

To push:

<syntaxhighlight lang="bash"g>
git push
</syntaxhighlight>

The first time that you push, Git does not know which
[[Git:Usage:Branches|branch]] on the remote to push to, so you instead need to
use

<syntaxhighlight lang="bash"g>
git push --set-upstream origin master
</syntaxhighlight>

you can substitute <code>master</code> with any other branch that you want to
push to.

=== Branches ===

N.B: Would be nice to add a `git branch --oneline --graph` from something
complex.

Branches are chains of commits. In a repository, any two branches will have a
common ancestor, which makes them akin to the branches of a tree.

There is one branch which is the canonical state of the project, usually called
'master', although alternatives are often used. (In this page, 'master' is
the name used)

Typically different people will add changes to different branches, and then
they will be merged together. See [[Git:Pull Requests]]

To create a new branch based on the current branch:

<syntaxhighlight lang="bash"g>
git checkout -b branch-name
</syntaxhighlight>

To switch branches:

Try to keep the working tree clean when doing this or it will get complicated.
(i.e. don't have changes which aren't yet part of a commit)

<syntaxhighlight lang="bash"g>
git switch branch-name
</syntaxhighlight>

To push a branch:

<syntaxhighlight lang="bash"g>
git push origin branch-name
</syntaxhighlight>

=== Pull Requests ===

Pull Requests are a request to include the changes that you have made to your
branch in the master branch. They are specific to GitHub, alternatives have
their own way of doing things (which is often very similar).

The easiest way to create a pull request is to go to github.com, navigate to
the page for your repository, open the branch you want to merge, and click the
icon to open a pull request.

=== Submodules ===

Submodules are Git repositories inside Git repositories. They can be useful for
a few reasons:

* Reusing a project in multiple places
* Using someone else's project as a dependency
* Segmenting projects into subprojects.

When a submodule exists within a project, it's just a link to another
repository. Cloning a repository which has submodules will not (by default)
clone the project's submodules.

To initialise submodules (after cloning the repo):

<syntaxhighlight lang="bash"g>
git submodule update --init
</syntaxhighlight>

To add a submodule (<code>location</code> is optional, it will go to
<code>repo-name</code> by default).

<syntaxhighlight lang="bash"g>
git submodule add https://github.com/IDP-L211/repo-name <location>
</syntaxhighlight>

To update all submodules to the latest commit in their repository

<syntaxhighlight lang="bash"g>
git submodule update --remote
</syntaxhighlight>

To completely remove a submodule (yes it is this annoying)

<syntaxhighlight lang="bash"g>
git submodule deinit repo-name
# now delete the relevant lines in .gitmodules
rm -rf .git/modules/repo-name
</syntaxhighlight>

== Troubleshooting ==

As the old adage goes… RTFM. <code>man git</code> should be your best friend.
Run it on any terminal where you use Git. It’s much better than any online
tutorial you will ever find (including this one). There are also manpages for
each of the Git commands, try <code>man git-add</code>, <code>man
git-commit</code>, and so on.

The manpages should come first, but do ask someone knowledgeable if you still
can’t figure it out (or if they’re nice and willing to help).

=== Exiting vim ===

Occasionally Git commands will open vim. Tim's advice is to learn vim, it's
worth the effort. If you really want to just exit, the following will work
every time. (there are simpler ways when you know what you’re doing).

Type <ESC>:qa!<Enter>, where <ESC> and <Enter> are the
escape and enter keys respectively. (You'd be surprised how much clarification
this usually needs

Git - Revision history

EllieClifford: Redirected page to Git and GitHub

EllieClifford: "Fix broken links"

EllieClifford: "Add page on Git"