From Documentation
Jump to: navigation, search
(Blanked the page)
Line 1: Line 1:
Git was created by Linus Torvald to manage the Linux Kernel code after BitKeeper withdrew permission for the kernel developers to use their proprietary system free of charge.
Linus specifically designed git to not be like CVS (which he hated from his time at Transmeta), to support a distributed workflow, provide very strong safeguards against accidental or malicious corruption, and to have very high performance.  There later features have resulted in it becoming very popular in the open source world.
Further general information can be found on the git [ wikipedia page].
'''NOTE:''' The commands in this section should be done '''before''' doing any commits.  If the ''--global'' option is used they only need to be done once, otherwise they need to be done for each repository initialized or cloned.
==Name and email address==
When you perform commits in Git, Git will record your name and email address with the log entry for that commit. For this reason, it is important that you tell Git your correct name and email address so others know (including you) who did a particular commit.
If you only use one Git repository, or, if you have a "main" Git repository and want default settings, set your name and email address globally using (substitute your first and last name and your email address):
<nowiki>git config --global 'FirstName LastName'
git config --global ''</nowiki>
If you don't want to set this globally, then you can omit the --global setting to save it in the current Git repository:
<nowiki>git config 'FirstName LastName'
git config ''</nowiki>
If you don't do this, then Git will commit information using whatever
user name information is available on the system you are on --which may or may not be correct.
These effects are very noticeable when one looks at the logs for Git (e.g., git log) and incorrect settings can make it difficult to know who committed changes and/or for others to give you proper credit.  Another reason to do is that it is very hard (if not impossible) to change logged Git information later.
==Cache login and password information==
Every time the git command is used and it has to access the remote repository you will be asked to type in your login and password.  Constantly re-entering this information can quickly become annoying.  Fortunately, it is easy to tell git to cache your login and password information.  For example to tell Git to cache your information for 7200 seconds run:
<nowiki>git config --global credential.helper 'cache --timeout=7200'</nowiki>
==Use more colour==
If you like colour-coded output, tell Git to use such when possible by running:
<nowiki>git config --global color.branch 'auto'
git config --global color.diff 'auto'
git config --global color.grep 'auto'
git config --global color.interactive 'auto'
git config --global color.showbranch 'auto'
git config --global color.status 'auto'
git config --global color.ui 'auto'</nowiki>
==Different text editor==
When you commit a text editor is run. If you prefer to use another text editor than the default one, run the following command specifying the text editor you prefer:
<nowiki>git config --global core.editor 'vim'</nowiki>
'''NOTE:''' You must use quotes around the editor command if it contains spaces.
==Different pager==
If output is too big to fit on one screen, git will use (if such is installed) a pager program such as "more" or "less".  The default is "less" but sometimes one might want to use another program, or, one might want to specify options to the page program.  For example, to have git run less with its -r option, run:
<nowiki>git config --global core.pager 'less -r'</nowiki>
=Basic workflow=
The following diagram from our [ youtube talk] depicts the basic git workflow and associated commands.
As seen in the diagram, there a four main components when working with git.
* ''folder/directory/working tree'' - the files that are in the current directory
* ''staging/index'' - a stored snapshot of the files that is to become the next version
* ''object database/store'' - the git database where the current and previous versions are stored
* ''remotes'' - peer git object stores located elsewhere
Although not strictly required, it can be useful to understand the structure of the object store.  The object store is just a collection of objects, that is, chunks of data, identified by part of their SHA1 hashes.  The types of objects are
* ''blobs'' - a non-specific object (e.g., the contents of a file),
* ''tree'' - a collection of blobs and tree references (i.e., a directory),
* ''commit'' - information about a specific revision, including a commit message, references to parent commits, and an associated tree reference, and
* ''tag'' - a reference object with a tag message.
The various branches are references to commit objects, which chain together in a directed acyclic graph to produce a history.  The index is a tree object.  Committing the index creates a new commit object that records the commit message, the current index tree, and current commit object as the parent.  The current branch reference is then updated to reference the new commit object.
Working locally with git consists of repetitively working with the files in the working tree, adding them to the index at some point, and then committing the index to the active branch at some further point.  Possibly it is easiest to think of the index as the staging area.  Changes/updates are accumulated in it (<tt>git add <filename></tt>) until some reasonable state of development is reached, and then they are committed to the current development branch (<tt>git commit</tt>).
At any point in time, it is possible to fork off an new branch (<tt>git branch <commit></tt> to create it or <tt>git checkout -b <commit></tt> to create it and switch to it) or switch to an entirely different development branch (<tt>git checkout <commit></tt>), the later of which will update the index and the working tree appropriately.  Much of the power of git comes from being able to simultaneously work with several different active lines of development at once.
Different branches can be brought back together in various ways.  It is possible to take the changes from a single commit from anywhere and apply it to the current branch (<tt>git cherry-pick <commit></tt>).  It is also possible to apply the changes made in another branch to the current branch.  This can be done by applying them on top of the current work (<tt>git merge <commit></tt>) or underneath it (<tt>git rebase <commit></tt>).
Detailed information about all the changes made is available via the logs (<tt>git log <commit></tt>).
Git is different than revision control software such as SVN in that it does not revolve around a central server.  Each git repository is entirely self contained and technically equivalent to all other git repositories.  Distributed work relies on a sharing model of swapping changes (commits) back and forth.
While this can be done entirely by email (<tt>git format-patch <revision range></tt> to export and <tt>git am <message></tt> to import), this is usually only the case for people submitting patches to large open source projects.  In a fully trusted situation, it is usually easier to directly import (<tt>git fetch <remote></tt> or <tt>git pull <remote></tt> to fetch and merge) and exported (<tt>git push <remote></tt>) changes to other repositories.
Although all git repositories are technically equal, it is common for one to be chosen as a stable  reference repository, with developers choosing to only export complete and tested changes to it from their personal repositories.
=Local work=
The following provides some bare basic commands to get you going.  It is strongly recommended to look these commands up in their man pages (<tt>man git-<command></tt> or <tt>git <command> --help</tt>) as there is a host of useful options and alternative ways they can be run.
==Creating a new project==
To create a new git project, simply do
<nowiki>mkdir <directory>
cd <directory>
git init</nowiki>
The ''--shared'' option can also be specified to setup repository for sharing with other SHARCNET users.  See [[#Cluster Repositories|further down]] for more details.
==Viewing changes==
For summary information about what has changed (that is differences that exist between the current branch, the index, and the working tree), run
<nowiki>git status</nowiki>
For more detailed information about what has changed in a particular file run
<nowiki>git diff <filename></nowiki>
The history of changes can be viewed by
<nowiki>git log</nowiki>
A useful alias for a fancy version of this last command is
<nowiki>git config --global 'log --graph --decorate --pretty=oneline --abbrev-commit'</nowiki>
==Saving changes==
First add the changes to the index via
<nowiki>git add <filename></nowiki>
The commit the changes by running
<nowiki>git commit</nowiki>
Files can be deleted and moved by <tt>git rm</tt> and <tt>git mv</tt>.
=Remote work=
The following provides some bare basic commands to get you going.  It is strongly recommended to look these commands up in their man pages (<tt>man git-<command></tt> or <tt>git <command> --help</tt>) as there is a host of useful options and alternative ways they can be run.
This list of remote repositories git knows about can be obtained via
<nowiki>git remote -a -v</nowiki>
==Duplicating an existing project==
To make a personal copy of an existing repository do
<nowiki>git clone <url>
cd <path>
git config remote.origin.push refs/heads/master:refs/heads/master</nowiki>
This adds a default remote ''origin'' for pulling future changes from.  The last two commands set the system up so <tt>git push origin</tt> will default to sending any changes made to the local master branch to the remote master branch.
==Adding remotes to an existing project==
Remotes can be added to an existing repository by running
<nowiki>git remote add <remote> <url>
git config remote.<remote>.push refs/heads/master:refs/heads/master
git config branch.master.remote <remote>
git config branch.master.merge refs/heads/master</nowiki>
The second line sets the system up so <tt>git push <remote></tt> will default to sending any changes made to the local master branch to the remote master branch.  The third line sets the default remote to the created remote.  The fourth line sets master as the default branch that <tt>git pull</tt> will merge into the local master branch.
==Pushing and pulling==
Assuming the default refspec has been setup, commits can be sent to the remote by running
<nowiki>git push <remote></nowiki>
Similarly, commits can be brought down from the remote by running
<nowiki>git pull <remote></nowiki>
Before attempting to send the local changes with the former command, it is usually a good idea to the later command with the ''--rebase'' option to incorporate any existing changes present in the remote repository under and the local changes (resolving any issues that arise).
It is also possible to just bring the remote changes into the remote tracking branch (run <tt>git branch -a -v</tt> to see these) without merging for inspection via
<nowiki>git fetch <remote></nowiki>
All of these commands use refsepcs, which correspond to directories under ''.git'', to specify the movement between local and remote branches.  At some point, it is recommend to read the information about this in the ''git-push'', ''git-fetch'', or ''git-pull'' man pages in order to  understanding the ''+'' option and fast forwarding.
=Sharing repositories=
All users with a common sponsor belong to the same sponsor group.  This gives them read only access to each others directories by default, which makes it possible to for each of them to pull changes from the others.  For example,
<nowiki>git remote add <remote> /home/<other user>/<git dir>
git fetch <remote></nowiki>
will add ''other user'''s git repo as a remote repository to the local one and fetch it.  For access off of SHARCNET's clusters, just make the remote a ssh directory
<nowiki>git remote add <remote> <user>@<cluster>:/home/<other user>/<git dir></nowiki>
where ''user'' is your SHARCNET username and ''cluster'' is any of the SHARCNET clusters.
==Cluster repositories==
The ''--shared=<umask>'' option can be used with ''git init'' to override the default permissions, where ''umask'' is a standard UNIX ''0xxx'' umask specifications or the keywords ''group'' (group writable) or ''all'' (world readable).
This can be used to create a master repository that all members of the group can write to is an effective way to create a master repository.  For example, the supervisor can do
<nowiki>git init --bare --shared=group</nowiki>
in some ''master dir'' under their ''home'' directory (so it is backed up), where the ''--bare'' option just specified that a working tree is not required.  An existing repository can then be pushed into it via
<nowiki>git remote add master /home/<supervisor>/<master dir>
git push master</nowiki>
New members to the group can then get their own copy to work with by just doing
<nowiki>git clone /home/<supervisor>/<master dir></nowiki>
For access off of SHARCNET clusters, ''/home/<supervisor>/<master dir>'' would have to be replaced with ''<user>@<cluster>/home/<supervisor>/<master dir>'' as before.
Sponsor group equivalent access can also be given to other specific groups and/or users by using FACLs.
<nowiki>setfacl -R -n -m default:user:<user>:rwx -m user:<user>:rwx  /home/<supervisor>/<master dir>
setfacl -R -n -m default:group:<group>:rwx -m group:<group>:rwx /home/<supervisor>/<master dir></nowiki>
The above does not grant full permissions.  Because specified user and group permissions are always masked by the mask permissions (what non-facl aware programs call the group permissions), it just means that the named ''user'' or ''group'' gets up to equivalent access to the sponsored group (i.e., what was specified with ''--shared=<umask>'').
Permissions to the sponsored group can also be revoked so just the named groups and users have access
<nowiki>setfacl -R -n -m default:group::- -m group::- /home/<supervisor>/<master dir></nowiki>
==Web repositories==
SHARCNET has a local (run on our severs) [ GitLab] webserver available to all our users at [].  You login using your SHARCNET credentials.
<nowiki>git clone<username>/<project>.git</nowiki>
The very popular [ github] site also provide very comprehensive web front ends (including wikis, etc.) for free for public repositories.  Private repositories require paying a small fee.
=Getting help=
Git comes with extensive documentation.  Run <tt>git <command> --help</tt> or <tt>man git-<command></tt>.  A simple [ google search] will turn up a wealth of online tutorials in addition to the below reference links.
o Git and SHARCNET (video tutorial):
* [ Part I]
* [ Part II]
o Github Help Using Git (cheat sheets, tutorials)<br>
o GIT Online Documentation<br>
o GIT Cheat Sheet - Extended Edition<br>
o Download Guis<br>
o Central Repo Howto<br>
o Website Howto<br>

Latest revision as of 12:43, 3 September 2021