Skip to content
Snippets Groups Projects
Commit 405caea4 authored by Wigal, Jacob (CIV)'s avatar Wigal, Jacob (CIV) :sparkles:
Browse files

revised git tutorial

parent 8f434f94
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 499 additions and 1009 deletions
README.md
+ 4
− 4
View file @ 405caea4
...@@ -12,15 +12,15 @@ Follow along with [this guide](https://gitlab.nps.edu/CID/get-started/-/blob/mas ...@@ -12,15 +12,15 @@ Follow along with [this guide](https://gitlab.nps.edu/CID/get-started/-/blob/mas
Follow along with the online tutorials: Follow along with the online tutorials:
### 1. Read [why we are using git and GitLab](https://gitlab.nps.edu/CID/get-started/-/blob/master/git/git-1_why_we_use_git_and_gitlab.ipynb "why we are using git and GitLab") ### 1. Read [why we are using git and GitLab](https://gitlab.nps.edu/CID/get-started/-/blob/master/git/git-1_why_we_use_git_and_gitlab.rst "why we are using git and GitLab")
### 2. Learn [how to download git and clone (or copy) a repository to your computer](https://gitlab.nps.edu/CID/get-started/-/blob/master/git/git-2_clone.ipynb "this guide") ### 2. Learn [how to download git and clone (or copy) a repository to your computer](https://gitlab.nps.edu/CID/get-started/-/blob/master/git/git-2_clone.rst "this guide")
### 3. Learn [some basic commands and complete the git tutorial](https://gitlab.nps.edu/CID/get-started/-/blob/master/git/git-3_branch-commit-push.ipynb "this guide") ### 3. Learn [some basic commands and complete the git tutorial](https://gitlab.nps.edu/CID/get-started/-/blob/master/git/git-3_branch-commit-push.rst "this guide")
*** ***
#### Additional helpful [git commands](https://gitlab.nps.edu/CID/get-started/-/blob/master/git/git-essential_commands.ipynb "click here") #### Additional helpful [git commands](https://gitlab.nps.edu/CID/get-started/-/blob/master/git/git-essential_commands.rst "click here")
For a detailed explanation of how git works, and how it can be useful for other projects [click here](https://nvie.com/posts/a-successful-git-branching-model/ "click here") For a detailed explanation of how git works, and how it can be useful for other projects [click here](https://nvie.com/posts/a-successful-git-branching-model/ "click here")
......
git/end_of_git_tutorial.txt
+ 1
− 0
View file @ 405caea4
I know how to clone a repository, pull the latest file changes, create and work from a branch, commit my file changes, and push to GitLab: I know how to clone a repository, pull the latest file changes, create and work from a branch, commit my file changes, and push to GitLab:
Matthias Kuc
git/git-1_why_we_use_git_and_gitlab.ipynb deleted 100644 → 0
+ 0
− 213
View file @ 8f434f94
%% Cell type:markdown id: tags:
<h1>Why we use git and GitLab</h1>
%% Cell type:markdown id: tags:
<h2 align="left"> As a team, we need:</h2>
<ul>
<font size="3">
1. a way to store and share data and code;<br>
2. a collaborative space for testing new ideas; and, <br>
3. precise version control to avoid losing past data/code.<br>
</font>
</ul>
%% Cell type:markdown id: tags:
<font size="3">
<ul>
Using <b>git</b> and <b>GitLab</b> is one way to do these three things. Together, they can:<br>
1. store and share data and code;<br>
2. enable users to see, edit, and comment on each other's work without overwriting files; and,<br>
3. enable distributed version control and passoword protection of key files.<br>
<br>
<b>But first... some quick definitions:</b> [Git](https://git-scm.com/) is version control software (VCS) that enables people to use simple commands to keep track of files and file changes. When you edit a file, git helps you keep track of exactly what changed, who changed it, and why. [GitLab](https://about.gitlab.com/) is a deployment of git to a cloud server with a user interface for viewing files and tracked changes. GitLab also has many more features like password protection and wikis. ([GitHub](https://github.com/), which you may have heard of before, is another website and online platform similar to GitLab.)
</font>
%% Cell type:markdown id: tags:
<h2>Why we are using git</h2>
<font size="3">
We make changes to files all the time. Most changes we make (even mistakes) are not a big issue when a single person is in control of the file and its management. For example, when you write a report in Microsoft Word, you can pick up where you last saved the document. You can edit the file, save it, and if you see yourself make a mistake, you can "undo". You are fully aware of how your Word document has changed over time.
<br>
<br>
Moving to a file-sharing system with multiple users and organizations reveals some key problems with the familiar workflow presented above. In a distributed, simultaneous setting, there are a lot of different people who may want to edit your file. They may not know what edits you made in the past and they may make significant edits to your file that you may not notice or understand. It is also likely multiple people could work on the same file and make conflicting changes that do not work well together (e.g., simulataneous edits to the same sentence or paragraph in a report). In worst-case situations, one person may overwrite a file and lose important information without knowing and with no power to "undo".
<br>
<br>
<i>This</i> is where git comes in.
<br>
<br>
In general, git forces users to be deliberate about the file editing process by tracking all changes people make to files. Git tracks files by creating a snapshot of a file (or multiple files), called a <i>commit</i>, every time users write a specific command. With every commit, git also requires users to write a message about the change they are making called a <i>commit message</i>. Every commit and commit message helps explain what happened between each version of the same file. Everyone with access to the file can see every commit and commit message, as well as download or revert to old versions of the file at any time. Git also enables users to <i>pull</i> other people's changes into their files (i.e., update their files with newer versions).
<br>
<h3>Diffs</h3>
Git also automatically produces an output called a <i>diff</i> that shows the line-by-line edits made in each commit. Diffs pinpoint the exact differences between file versions and provide a powerful way to understand version details and commit messages left by users.
<br>
Below is an example of a diff showing changes someone made to a text file called index.md. This diff shows us the updating_the_geo_nodes.md line was <font color='red'> deleted </font> and the version_specific_updates.md line was <font color='green'> added </font>. Notice how this diff identifies only the exact part of the line that changed, as the "<b>ing</b>" stays the same between commits!
</font>
%% Cell type:markdown id: tags:
![Clone Repo GitLab](https://docs.gitlab.com/ee/user/project/merge_requests/img/merge_request_diff_v12_2.png "GitLab diff")
%% Cell type:markdown id: tags:
<font size="3">
Diffs are only visible with git for certain filetypes. Git was origially designed to deal with code for software development, so filetypes associated with most programming languages work great in git. For example, git will track commits and diffs for files like...<br>
<ul>
<li>Matlab files (.m)</li>
<li>R scripts (.r)</li>
<li>Text files (.txt)</li>
<li>Python programs (.py)</li>
<li>HTML files (.html)</li>
<li>Tabular data files (.csv)</li>
<li>Non-Tabular, text-based data (e.g., .json)</li>
<li>and many more... </li>
</ul>
</font>
%% Cell type:markdown id: tags:
<font size="3">
<h align="left"> Git works really well with those files because they are <i><b>flat, text-based</b></i> formats that git easily reads when someone makes a commit and can analyze when generating diffs. </h>
However, git <i><b>can't</b></i> read the contents of <i><b>non-text-based</b></i> files. In other words, when someone makes changes to files that are <i>not</i> text-based, git doesn't understand the diff. These filetypes include...
<ul>
<li>Rendered Documents (.pdf)</li>
<li>Binary images (.jpg)</li>
<li>Formatted word docs (.doc)</li>
<li>Tabular data with multiple sheets (.xlsx)</li>
<li>Binary data formats (e.g., .dbf)</li>
<li>and many more... </li>
</ul>
<i>If we make a commit with these files, we won't be able to see the diff!</i>
<br><br>
Below is an example of a diff generated after committing files associated with a binary datatype called a <i>shapefile</i>. Here, we made changes to three binary files associated with a shapefile &hyphen; the database file(.dbf), the the main file (.shp), and the index file (.shx). Each file can have commits made and the user can move freely through this commit history. However, <b>the diff cannot show what changed</b>. The user is stuck with figuring out the differences between the original file and this new version. The only information provided is the commit message, "Added point and changed date". For large files, this limited information may not be useful enough to track changes. It is often difficult to manage large, distributed projects without seeing the diffs.
</font>
%% Cell type:markdown id: tags:
![Clone Repo GitLab](https://elevationusvistttest.s3-us-west-1.amazonaws.com/shp+diff.png "GitLab diff shp")
%% Cell type:markdown id: tags:
<h2>What text-based filetypes should we use?</h2>
<h3>Storing and Sharing Code</h3>
<p>
<font size="3">
In general, <b>git will work with any computer code we write in any format.</b> Git was designed for software development, and works great with essentially any program we write from scratch. It doesn't matter if you write your program in python, C, C++, C#, java, javascript, r, matlab, or any other language. All programs are essentially text-based. For special files that may be required to run something, git has built-in functionality to help manage these issues.
</font>
</p>
<h3>Storing and Sharing Data</h3>
<p>
<font size="3">
The two biggest constraints when using git to manage data is: git requires limited file size and only text-based filetypes generate diffs.
<br>
<b>Data File Size:</b> When storing code and and data on GitLab, the files are stored in <i>repositories</i>. Because git and GitLab were designed for managing text-based code (which often has very small file size), git repositories tend to have limitations on their total storage. However, there is generally no limitation on the number of repositories one can have. So, this issue is usually circumvented by keeping each repository as small as possible. When using git, its important to know the maximum storage capacity on a repository, and try and segment projects and data into separate repositories when possible.
<br>
<b>Data Filetype:</b> While software development is done almost exclusively with flat, text-based files, data is often stored in non-flat, non-text-based files. A common example of a non-flat file would be an excel file with functions and data stored across multiple tabs. A common example of non-text-based data includes the binary shapefiles shown above.
<br>
<ul>
<b>To utilize git for data management, we have to use flat, text-based data filetypes whenever possible.</b> In general, this just means choosing an appropriate filetype for a particular kind of data and being deliberate about using that filetypes for all commits. To demonstrate what we mean, we will focus on an important type of data we want to share that comes in many filetypes &ndash; geospatial data.
</ul> </p>
%% Cell type:markdown id: tags:
<h2>Geospatial data</h2>
<p>Geospatial data describes the position of points, lines, polygons, and/or images on the earth as well as their coordinate-linked attributes. Geospatial data typically includes geometric features, coordinates of those features, the coordinate reference system and projection those coordinates should be read in, and lists of coordinate-linked data visible in an attributes table. <br><br>Geospatial data has text-based and non-text-based formats:
<table><font color="red"> <tr> <th>Text-based</th> <th>Non-text-based</th> </tr> <tr> <td><b>.geojson</b></td> <td>.shp</td> </tr> <tr> <td>.wkt</td> <td>.gpkg</td> </tr><tr> <td>.gml</td> <td>.kml/.kmz</td> </tr> </font> </table>
<br>
<p>
Notice that there binary filetypes like shapefiles, geopackages, and kml/kmz <i>and</i> flat, text-based filetypes like geojson, wkt, and gml. When we use git, if we commit and share geospatial data as on of these text-based filetypes, we will get useful diffs. We highlight GeoJSON, because this is the flat, text-based filetype we chose from this list to use. We chose GeoJSON for a number of reasons.
</p>
<h3>GeoJSON</h3>
<font size="3">
The GeoJSON format is the standard for text-based geospatial data formats. GeoJSON files are just text, so we can visibly see any edits made to the files in GitLab as they are made. It is an open format, meaning it will work on all operating systems and with most GIS software. It is built on top of the already well-established JSON format, and has a number of helpful supporting packages that can be employed in programming languages such as Python and R.<br>
<br>
An important distinction between the GeoJSON format and other geospatial data formats, is that the coordinate reference system (CRS) of every GeoJSON is WGS 84 EPSG:4326. This means any file you convert to GeoJSON will have its CRS automatically converted to EPSG:4326, which is perfect for analysis. The above are some of the reasons we ask that any geospatial data you have be converted to GeoJSON before pushing it to GitLab. It is easy to convert geospatial data through either QGIS or the CID utility [GeoConvert](https://gitlab.nps.edu/CID/gis-utilities/geoconvert).
</font>
%% Cell type:markdown id: tags:
<h3>Helpful Links:</h3>
<h4>Git desktop client</h4>
Free: https://www.sourcetreeapp.com
Free for students: https://www.git-tower.com
<br>
<br>
<h4>GeoJSON Web Visualization</h4>
Github has native visualization: https://github.com/paultag/dc/blob/master/coffee.geojson
Github Gists (shareable links): https://gist.github.com/cageyjames/2dc545127f04b93858bd
Editor/Visualizer: http://geojson.io/
git/git-1_why_we_use_git_and_gitlab.rst 0 → 100644
+ 109
− 0
View file @ 405caea4
Why we use git and GitLab
==============================================
As a team, we need:
----------------------------------------------
1. a way to store and share data and code;
2. a collaborative space for testing new ideas; and,
3. precise version control to avoid losing past data/code.
Using git and GitLab is one way to do these three things. Together, they can:
1. store and share data and code;
2. enable users to see, edit, and comment on each other’s work without overwriting files; and,
3. enable distributed version control and passoword protection of key files.
But first… some quick definitions: `Git <https://git-scm.com/>`__ is version control software (VCS) that enables people to use simple commands to keep track of files and file changes. When you edit a file, git helps you keep track of exactly what changed, who changed it, and why. `GitLab <https://about.gitlab.com/>`__ is a deployment of git to a cloud server with a user interface for viewing files and tracked
changes. GitLab also has many more features like password protection and wikis. (`GitHub <https://github.com/>`__, which you may have heard of
before, is another website and online platform similar to GitLab.)
Why we are using git
----------------------------------------------
We make changes to files all the time. Most changes we make (even mistakes) are not a big issue when a single person is in control of the file and its management. For example, when you write a report in Microsoft Word, you can pick up where you last saved the document. You can edit the file, save it, and if you see yourself make a mistake, you can “undo”. You are fully aware of how your Word document has changed over time. Moving to a file-sharing system with multiple users and organizations reveals some key problems with the familiar workflow presented above. In a distributed, simultaneous setting, there are a lot of different people who may want to edit your file. They may not know what edits you made in the past and they may make significant edits to your file that you may not notice or understand. It is also likely multiple people could work on the same file and make conflicting changes that do not work well together (e.g., simultaneous edits to the same sentence or paragraph in a report). In worst-case situations, one person may overwrite a file and lose important information without knowing and with no power to “undo”. This is where git comes in. In general, git forces users to be deliberate about the file editing process by tracking all changes people make to files. Git tracks files by creating a snapshot of a file (or multiple files), called a commit, every time users write a specific command. With every commit, git also requires users to write a message about the change they are making called a commit message. Every commit and commit message helps explain what happened between each version of the same file. Everyone with access to the file can see every commit and commit message, as well as download or revert to old versions of the file at any time. Git also enables users to pull other people’s changes into their files (i.e., update their files with newer versions).
Diffs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Git also automatically produces an output called a diff that shows the line-by-line edits made in each commit. Diffs pinpoint the exact differences between file versions and provide a powerful way to understand version details and commit messages left by users. Below is an example of a diff showing changes someone made to a text file called index.md. This diff shows us the updating_the_geo_nodes.md line was deleted and the version_specific_updates.md line was added . Notice how
this diff identifies only the exact part of the line that changed, as the “ing” stays the same between commits!
.. figure:: https://docs.gitlab.com/ee/user/project/merge_requests/img/merge_request_diff_v12_2.png
:alt: GitLab diff
Diffs are only visible with git for certain filetypes. Git was origially designed to deal with code for software development, so filetypes associated with most programming languages work great in git. For example, git will track commits and diffs for files like…
- Matlab files (.m)
- R scripts (.r)
- Text files (.txt)
- Python programs (.py)
- HTML files (.html)
- Tabular data files (.csv)
- Non-Tabular, text-based data (e.g., .json)
- and many more…
Git works really well with those files because they are flat, text-based formats that git easily reads when someone makes a commit and can analyze when generating diffs. However, git can’t read the contents of non-text-based files. In other words, when someone makes changes to files that are not text-based, git doesn’t understand the diff. These filetypes include…
- Rendered Documents (.pdf)
- Binary images (.jpg)
- Formatted word docs (.doc)
- Tabular data with multiple sheets (.xlsx)
- Binary data formats (e.g., .dbf)
- and many more…
If we make a commit with these files, we won’t be able to see the diff! Below is an example of a diff generated after committing files associated with a binary datatype called a shapefile. Here, we made changes to three binary files associated with a shapefile ‐ the database file(.dbf), the the main file (.shp), and the index file (.shx). Each file can have commits made and the user can move freely through this
commit history. However, the diff cannot show what changed. The user is stuck with figuring out the differences between the original file and
this new version. The only information provided is the commit message, “Added point and changed date”. For large files, this limited information may not be useful enough to track changes. It is often difficult to manage large, distributed projects without seeing the diffs.
.. figure:: https://elevationusvistttest.s3-us-west-1.amazonaws.com/shp+diff.png
:alt: GitLab diff shp
What text-based filetypes should we use?
----------------------------------------------
Storing and Sharing Code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In general, git will work with any computer code we write in any format. Git was designed for software development, and works great with essentially any program we write from scratch. It doesn’t matter if you write your program in python, C, C++, C#, java, javascript, r, matlab, or any other language. All programs are essentially text-based. For special files that may be required to run something, git has built-in functionality to help manage these issues.
Storing and Sharing Data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The two biggest constraints when using git to manage data is: git requires limited file size and only text-based filetypes generate diffs.
Data File Size: When storing code and and data on GitLab, the files are stored in repositories. Because git and GitLab were designed for managing text-based code (which often has very small file size), git repositories tend to have limitations on their total storage. However, there is generally no limitation on the number of repositories one can have. So, this issue is usually circumvented by keeping each repository as small as possible. When using git, its important to know the maximum storage capacity on a repository, and try and segment projects and data into separate repositories when possible.
Data Filetype: While software development is done almost exclusively with flat, text-based files, data is often stored in non-flat, non-text-based files. A common example of a non-flat file would be an excel file with functions and data stored across multiple tabs. A common example of non-text-based data includes the binary shapefiles shown above.
To utilize git for data management, we have to use flat, text-based data filetypes whenever possible. In general, this just means choosing an appropriate filetype for a particular kind of data and being deliberate about using that filetypes for all commits. To demonstrate what we mean, we will focus on an important type of data we want to share that comes in many filetypes – geospatial data.
Geospatial data
----------------------------------------------
Geospatial data describes the position of points, lines, polygons, and/or images on the earth as well as their coordinate-linked attributes. Geospatial data typically includes geometric features, coordinates of those features, the coordinate reference system and
projection those coordinates should be read in, and lists of coordinate-linked data visible in an attributes table. Geospatial data has text-based and non-text-based formats:
============== ==================
**Text-based** **Non-text-based**
-------------- ------------------
.geojson .shp
.wkt .gpkg
.gml .kml/.kmz
============== ==================
Notice that there binary filetypes like shapefiles, geopackages, and kml/kmz and flat, text-based filetypes like geojson, wkt, and gml. When we use git, if we commit and share geospatial data as on of these
text-based filetypes, we will get useful diffs. We highlight GeoJSON, because this is the flat, text-based filetype we chose from this list to use. We chose GeoJSON for a number of reasons.
GeoJSON
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The GeoJSON format is the standard for text-based geospatial data formats. GeoJSON files are just text, so we can visibly see any edits made to the files in GitLab as they are made. It is an open format, meaning it will work on all operating systems and with most GIS software. It is built on top of the already well-established JSON format, and has a number of helpful supporting packages that can be employed in programming languages such as Python and R. An important distinction between the GeoJSON format and other geospatial data formats, is that the coordinate reference system (CRS) of every GeoJSON is WGS 84 EPSG:4326. This means any file you convert to GeoJSON will have its CRS automatically converted to EPSG:4326, which is perfect for analysis. The above are some of the reasons we ask that any geospatial data you have be converted to GeoJSON before pushing it to GitLab. It is easy to convert geospatial data through either QGIS or the CID utility `GeoConvert <https://gitlab.nps.edu/CID/gis-utilities/geoconvert>`__.
\ No newline at end of file
git/git-2_clone.ipynb deleted 100644 → 0
+ 0
− 189
View file @ 8f434f94
%% Cell type:markdown id: tags:
### About
This notebook is for the following functions:
- create a local repository with files copied from a remote repository
- set a username and email to be associated with your future file edits
%% Cell type:markdown id: tags:
<h2> Before we begin </h2>
You will need to have "git" installed.
<a href="https://www.atlassian.com/git/tutorials/install-git">Follow the guide located here</a> then read below.
%% Cell type:markdown id: tags:
<section>
<style type="text/css">p { margin:0}
</style>
<div style="float: left; width: 50%; line-height: 120%;">
Mac Users:
<p>You may enter git commands in the "Terminal" application already on your computer.</p>
</div>
<div style="float: right; width: 50%; line-height: 120%;">
Windows/PC Users:
<p>You may enter git commands in "Anaconda Prompt".</p>
</div>
</section>
%% Cell type:markdown id: tags:
# Get Started
Run the following commands in a command-line interface (e.g. Anaconda Prompt, Terminal) to download a remote repository and create a local repository to use in conjunction.
%% Cell type:markdown id: tags:
<h4>Step 1</h4> Choose a location for your local repository. The end of the command in the cell below should be replaced with your desired filepath for your local repository.<br><br>
<b>For your first time, just copy the filepath of your desktop. </b><br>
<br>
<b>Mac Users:</b> this filepath will look something like..."/Users/username/Desktop" <br>
<b>Windows Users:</b> this filepath will look something like..."C:\Users\username\Desktop"
%% Cell type:code id: tags:
``` python
cd /Users/username/Desktop
```
%% Cell type:markdown id: tags:
<h4>Step 2</h4>
Clone the remote repository to your new local repository. (syntax: git clone https//repositoryurlcom/repo.git) The repository URL of any repository can be found by going to our GitLab repository, selecting clone, and copying what shows up under https. Once cloned, you will have the contents of that repository inside a new folder within your chosen file directory. <b>Note:</b> This new folder will be your git repository.
![Clone Repo GitLab](https://docs.gitlab.com/ee/user/admin_area/settings/img/clone_panel_v12_4.png "Clone Repo GitLab")
%% Cell type:code id: tags:
``` python
git clone https://gitlab.nps.edu/CID/get-started.git
```
%% Cell type:markdown id: tags:
You can now cd to your newly created git repository on your desktop. Note that in the future you will always need to cd to your git repository before using git commands.
%% Cell type:code id: tags:
``` python
cd /Users/username/Desktop/get-started
```
%% Cell type:markdown id: tags:
<h4>Step 3</h4>
Set a username and email to be associated with your future file edits. (Replace name and email within quotes. Note: You are not creating a log-in. You are only telling git your name and email so it can tell others who has made edits once you have started working.) You only have to do this <b>once</b>.
%% Cell type:code id: tags:
``` python
git config --global user.name "Firstname Lastname"
git config --global user.email "firstname.lastname@nps.edu"
```
%% Cell type:markdown id: tags:
# Check Status
If the above was done correctly, you should see something similar to the following output: "On branch master, nothing to commit, working tree clean"
%% Cell type:code id: tags:
``` python
git status
```
%% Output
On branch master
nothing to commit, working tree clean
%% Cell type:markdown id: tags:
# That's it!
Congratulations! If you have made it this far that means you have successfully installed git, and used git commands to get files. We will explore how to work with files and push them up to GitLab in the next guide.
git/git-2_clone.rst 0 → 100644
+ 108
− 0
View file @ 405caea4
**This tutorial is for the following functions:**
- create a local repository with files copied from a remote repository
- set a username and email to be associated with your future file edits
Before we begin
---------------------
You will need to have “git” installed.
Follow the guide located `here <https://www.atlassian.com/git/tutorials/install-git>`_ then read below.
**Mac Users:**
You may enter git commands in the “Terminal” application already on your
computer.
**Windows/PC Users:**
You may enter git commands in “Anaconda Prompt”.
Get Started
---------------------
Run the following commands in a command-line interface (e.g. Anaconda Prompt, Terminal) to download a remote repository and create a local repository to use in conjunction.
Step 1
^^^^^^^^^^
Choose a location for your local repository. The end of the command in the cell below should be replaced with your desired filepath for your local repository. For your first time, just copy the filepath of your desktop.
Mac Users: this filepath will look something like…“/Users/username/Desktop”
Windows Users: this filepath will look something like…“C:\Users\username\Desktop"
.. code:: ipython3
cd /Users/username/Desktop
Step 2
^^^^^^^^^^
Clone the remote repository to your new local repository. (syntax: git
clone https//repositoryurlcom/repo.git) The repository URL of any
repository can be found by going to `our GitLab repository <https://gitlab.nps.edu/CID/get-started>`_, selecting
clone, and copying what shows up under "https". Once cloned, you will have
the contents of that repository inside a new folder within your chosen
file directory. Note: This new folder will be your git repository.
.. figure:: https://docs.gitlab.com/ee/user/admin_area/settings/img/clone_panel_v12_4.png
:alt: Clone Repo GitLab
.. code:: ipython3
git clone https://gitlab.nps.edu/CID/get-started.git
You can now cd to your newly created git repository on your desktop.
Note that in the future you will always need to cd to your git
repository before using git commands.
.. code:: ipython3
cd /Users/username/Desktop/get-started
Step 3
^^^^^^^^^^
Set a username and email to be associated with your future file edits.
(Replace name and email within quotes. Note: You are not creating a
log-in. You are only telling git your name and email so it can tell
others who has made edits once you have started working.) You only have
to do this once.
.. code:: ipython3
git config --global user.name "Firstname Lastname"
git config --global user.email "firstname.lastname@nps.edu"
Check Status
============
If the above was done correctly, you should see something similar to the
following output: “On branch master, nothing to commit, working tree
clean”
.. code:: ipython3
git status
That’s it!
==========
Congratulations! If you have made it this far that means you have
successfully installed git, and used git commands to get files. We will explore how to work with files and push them up to GitLab in the next guide.
\ No newline at end of file
git/git-3_branch-commit-push.ipynb deleted 100644 → 0
+ 0
− 282
View file @ 8f434f94
%% Cell type:markdown id: tags:
### About
This notebook is for the following functions:
- creating and switching branches
- pulling the latest files
- making a commit
- pushing changed files and/or new files from your computer to GitLab
%% Cell type:markdown id: tags:
# Startup git
Replace /filepath/filename with the filepath of your git repository.
%% Cell type:code id: tags:
``` python
cd /example/filepath/get-started
```
%% Cell type:markdown id: tags:
# What are branches?
%% Cell type:markdown id: tags:
Now, if you type `git status` you should see, once again, that you are "On branch master". What does that mean? <br>
<br>
First it is important to understand how git tracks versions. Each time someone changes a file and makes a "commit" (which we will get to in just a minute),
git creates a snapshot of that file. This is great for keeping a record of file versions. But sometimes you may want to test something out (make changes to multiple files and maybe delete them later), or track changes you are making to your files without changing any of the files someone else is working from. These types of situations are why we create branches. In most repositories, the master branch is rarely changed. On this repository, the master branch is a "protected" branch, meaning almost no one can make changes to it, even if they wanted to. If you want to make changes to the repository, you will just have to create a new branch, and/or push to a branch that is not the master. <br>
<br>
The below image shows a visualization of a repository's commit history. In the center is each commit's unique identifier or "hash" generated by git. A branch points to a specific moment in this timeline. In this case, someone created a new branch called "testing" which at this point is an exact copy of the master. The "HEAD" box in this image signifies that the user is currently working from the testing branch and not the master. <br>
<br>
%% Cell type:markdown id: tags:
![](https://git-scm.com/book/en/v2/images/head-to-testing.png)
%% Cell type:markdown id: tags:
Borrowing from git's documentation, "A branch in Git is simply a lightweight movable pointer to one of these commits. The default branch name in Git is master. As you start making commits, you're given a master branch that points to the last commit you made." But you can create as many branches as you want. You can read more about branches [here](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell). <br>
<br>
#### Before we create a branch of our own we need to do one more thing:
%% Cell type:markdown id: tags:
# Pull
This command gives us the most up to date version of a branch from GitLab. Always pull before working on files to ensure you have the most up-to-date version of your branch. (syntax: git pull origin branch_name)
%% Cell type:code id: tags:
``` python
git pull origin master
```
%% Cell type:markdown id: tags:
# Create a new branch
Let's make a new branch called "develop". (syntax: git branch new_branch_name)
%% Cell type:code id: tags:
``` python
git branch develop
```
%% Cell type:markdown id: tags:
Great! We just created a new branch now let's check what branch we are on...
%% Cell type:code id: tags:
``` python
git branch
```
%% Cell type:markdown id: tags:
# Switch branches
Notice how we are still on master. Use this command to switch branches. (syntax: git checkout branch_name)
%% Cell type:code id: tags:
``` python
git checkout develop
```
%% Cell type:markdown id: tags:
(In the future you can use this command to create a new branch and switch to it at the same time! `git checkout -b new_branch_name`)
%% Cell type:markdown id: tags:
There was already a "develop" branch on GitLab when we created the develop branch on our machine, so we need to pull one more time to update our personal develop branch. <br>
<br>
(It is also important to consider that creating a branch on your machine does not automatically create one on GitLab. Branches new to GitLab need to be "pushed" before they show up on GitLab. We will talk more about pushing at the end of this tutorial.) <br>
%% Cell type:code id: tags:
``` python
git pull origin develop
```
%% Cell type:markdown id: tags:
# Make a Commit
Use this to finalize a file edit or addition and provide a reason.
%% Cell type:markdown id: tags:
<h4>Step 1</h4>
Make a change to your file, or place a new file to be pushed somewhere in your local git folder structure. For this tutorial, open up end_of_git_tutorial.txt in the tutorial_files folder inside your get-started repostory and add your first and last name to the first empty line you see.
%% Cell type:markdown id: tags:
<h4>Step 2</h4>
Choose file(s) to commit. Replace the filepath at the end of the cell below with the filepath of the file(s) you would like to commit. (Note: If you would like to commit multiple files at once with the same commit message, you can do so by adding the parent folder of all edited files.) <br>
<br>
For this example we can add the filepath of our tutorial_files folder or the filepath of our end_of_git_tutorial.txt file.
%% Cell type:code id: tags:
``` python
git add Users/username/Desktop/get-started/git/end_of_git_tutorial.txt
```
%% Cell type:markdown id: tags:
<h4>Step 3</h4>
Place your reason for the commit inside quotes. If this is a new file to the repository, simply put "Initial commit". For this example, write anything you think will communicate to others why you are changing this file, or what you are changing about it.
%% Cell type:code id: tags:
``` python
git commit -m "Adding my name..."
```
%% Cell type:markdown id: tags:
# Push
Use this to update files in the remote repository with your committed files. Only try to push to branches with the same name as the one on your machine. (e.g. if you want to push a branch named "my_cool_branch", you should type "git push origin my_cool_branch"). <br>
<br>
There is already a "develop" branch on GitLab, so by pushing we will update the develop branch on GitLab, replacing it with an exact copy of the develop branch on our machine!
%% Cell type:markdown id: tags:
(syntax: git push origin branch_name)
%% Cell type:code id: tags:
``` python
git push origin develop
```
%% Cell type:markdown id: tags:
# That's it!
You should now see the updated end_of_tutorial.txt file with your name on GitLab on the develop branch!
The process we just followed is visualized below. You can follow this each time you work on a file.
%% Cell type:markdown id: tags:
<img src="https://elevationusvistttest.s3-us-west-1.amazonaws.com/gitcheatsheet.png" alt="git workflow" width=50%/>
git/git-3_branch-commit-push.rst 0 → 100644
+ 122
− 0
View file @ 405caea4
**This tutorial is for the following functions:**
- creating and switching branches
- pulling the latest files
- making a commit
- pushing changed files and/or new files from your computer to GitLab
Startup git
===========
Replace /filepath/filename with the filepath of your git repository.
.. code:: ipython3
cd /example/filepath/get-started
What are branches?
==================
Now, if you type ``git status`` you should see, once again, that you are “On branch master”. What does that mean? First it is important to understand how git tracks versions. Each time someone changes a file and makes a “commit” (which we will get to in just a minute), git creates a snapshot of that file. This is great for keeping a record of file versions. But sometimes you may want to test something out (make changes to multiple files and maybe delete them later), or track changes you are making to your files without changing any of the files someone else is working from. These types of situations are why we create branches. In most repositories, the master branch is rarely changed. On this repository, the master branch is a “protected” branch, meaning almost no one can make changes to it, even if they wanted to. If you want to make changes to the repository, you will just have to create a new branch, and/or push to a branch that is not the master. The below image shows a visualization of a repository’s commit history. In the center is each commit’s unique identifier or “hash” generated by git. A branch points to a specific moment in this timeline. In this case, someone created a new branch called “testing” which at this point is an exact copy of the master. The “HEAD” box in this image signifies that the user is currently working from the testing branch and not the master.
|image0|
.. |image0| image:: https://git-scm.com/book/en/v2/images/head-to-testing.png
Borrowing from git’s documentation, “A branch in Git is simply a lightweight movable pointer to one of these commits. The default branch name in Git is master. As you start making commits, you’re given a master branch that points to the last commit you made.” But you can create as many branches as you want. You can read more about branches `here <https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell>`__.
**Before we create a branch of our own we need to do one more thing..**
Pull
====
This command gives us the most up to date version of a branch from GitLab. Always pull before working on files to ensure you have the most up-to-date version of your branch. (syntax: git pull origin branch_name)
.. code:: ipython3
git pull origin master
Create a new branch
===================
Let’s make a new branch called “develop”. (syntax: git branch new_branch_name)
.. code:: ipython3
git branch develop
Great! We just created a new branch now let’s check what branch we are on…
.. code:: ipython3
git branch
Switch branches
===============
Notice how we are still on master. Use this command to switch branches.
(syntax: git checkout branch_name)
.. code:: ipython3
git checkout develop
(In the future you can use this command to create a new branch and
switch to it at the same time! ``git checkout -b new_branch_name``)
There was already a “develop” branch on GitLab when we created the
develop branch on our machine, so we need to pull one more time to
update our personal develop branch. (It is also important to consider that creating a branch on your machine does not automatically create one on GitLab. Branches new to GitLab need to be “pushed” before they show up on GitLab. We will talk more about pushing at the end of this tutorial.)
.. code:: ipython3
git pull origin develop
Make a Commit
=============
Use this to finalize a file edit or addition and provide a reason.
Step 1
^^^^^^^^
Make a change to your file, or place a new file to be pushed somewhere in your local git folder structure. For this tutorial, open up end_of_git_tutorial.txt in the tutorial_files folder inside your get-started repostory and add your first and last name to the first empty line you see.
Step 2
^^^^^^^^
Choose file(s) to commit. Replace the filepath at the end of the cell below with the filepath of the file(s) you would like to commit. (Note: If you would like to commit multiple files at once with the same commit message, you can do so by adding the parent folder of all edited files.) For this example we can add the filepath of our tutorial_files folder or the filepath of our end_of_git_tutorial.txt file.
.. code:: ipython3
git add Users/username/Desktop/get-started/git/end_of_git_tutorial.txt
Step 3
^^^^^^^^
Place your reason for the commit inside quotes. If this is a new file to the repository, simply put “Initial commit”. For this example, write anything you think will communicate to others why you are changing this file, or what you are changing about it.
.. code:: ipython3
git commit -m "Adding my name..."
Push
====
Use this to update files in the remote repository with your committed files. Only try to push to branches with the same name as the one on your machine. (e.g. if you want to push a branch named “my_cool_branch”, you should type “git push origin my_cool_branch”). There is already a “develop” branch on GitLab, so by pushing we will update the develop branch on GitLab, replacing it with an exact copy of the develop branch on our machine!
(syntax: git push origin branch_name)
.. code:: ipython3
git push origin develop
That’s it!
==========
You should now see the updated end_of_tutorial.txt file with your name on GitLab on the develop branch!
The process we just followed is visualized in this `cheat sheet <https://elevationusvistttest.s3-us-west-1.amazonaws.com/gitcheatsheet.png>`__. You can follow this each time you work on a file.
\ No newline at end of file
git/git-essential_commands.ipynb deleted 100644 → 0
+ 0
− 321
View file @ 8f434f94
%% Cell type:markdown id: tags:
### About
This notebook is for the following functions:
- creating, switching, merging, and deleting branches
- pulling latest changes from remote repository
- making a commit
- pushing changes to remote repository
%% Cell type:markdown id: tags:
# Startup git
Replace /Users/filepath/etc with the filepath of the local git directory you wish to work on.
%% Cell type:code id: tags:
``` python
cd /Users/filepath/etc
```
%% Cell type:markdown id: tags:
# Create a new branch
This command creates a new branch AND switches to it. Replace branch_name with your desired name.
%% Cell type:code id: tags:
``` python
git checkout -b branch_name
```
%% Cell type:markdown id: tags:
# Switch Branches
See what branch you are on
%% Cell type:code id: tags:
``` python
git branch
```
%% Cell type:markdown id: tags:
Switch branches (syntax: git checkout branch_name)
%% Cell type:code id: tags:
``` python
git checkout develop
```
%% Cell type:code id: tags:
``` python
git checkout master
```
%% Cell type:markdown id: tags:
# Merge
Use this to add changes from one branch to another.
This will make both branches identical!
%% Cell type:markdown id: tags:
Use git checkout command to make sure you are on the branch you want to merge your changes with.
%% Cell type:code id: tags:
``` python
git checkout develop
```
%% Cell type:markdown id: tags:
Then tell git the other branch you made the changes on that you are bringing into your aforementioned branch.
%% Cell type:code id: tags:
``` python
git merge branch_name
```
%% Cell type:markdown id: tags:
# Delete a branch
Sometimes you will want to delete locally created branches, such as after you have merged your changes to another branch. (Note: If you are purposefully deleting a branch without committing your changes, git may ask you to confirm this by making you rerun the following command with a capital "D".)
%% Cell type:code id: tags:
``` python
git branch -d branch_name
```
%% Cell type:markdown id: tags:
# Pull
Use this to replace files in your local repository with the latest versions from the remote repository.
%% Cell type:markdown id: tags:
Checkout the local branch you would like to pull changes to.
%% Cell type:code id: tags:
``` python
git checkout develop
```
%% Cell type:markdown id: tags:
Select which remote branch you would like to pull changes from and pull. (syntax: git pull remote_name branch_name)
%% Cell type:code id: tags:
``` python
git pull origin develop
```
%% Cell type:markdown id: tags:
# Make a Commit
Use this to finalize a file edit or addition and provide a reason.
%% Cell type:markdown id: tags:
<h4>Step 1</h4>
Make a change to your file (and/or drag a new file into your git repository).
%% Cell type:markdown id: tags:
<h4>Step 2</h4>
Choose file(s) to commit. Replace the filepath at the end of the cell below with the filepath of the file(s) you would like to commit. (Note: If you would like to commit multiple files at once with the same commit message, you can do so by adding the parent folder of all edited files.)
%% Cell type:code id: tags:
``` python
git add /example/filepath/User/Documents/git/file.txt
```
%% Cell type:markdown id: tags:
<h4>Step 3</h4>
Place your reason for the commit inside quotes. If the file(s) are new to the repository, simply put "Initial commit".
%% Cell type:code id: tags:
``` python
git commit -m "Initial commit"
```
%% Cell type:markdown id: tags:
# Push
Use this to update files in the remote repository with your committed files. Note: You may run into errors if the local branch you are pushing does not have the same name as the remote branch you are pushing to (e.g. trying to push from a local branch named "testing" to a branch in the GitLab repository named "develop"). It is recommended you push from a branch with the same name as the remote branch you are trying to push to.
%% Cell type:markdown id: tags:
See a list of all files you have made commits to since your last push.
%% Cell type:code id: tags:
``` python
git status
```
%% Output
On branch develop
nothing to commit, working tree clean
%% Cell type:markdown id: tags:
(syntax: git push remote_name branch_name)
%% Cell type:code id: tags:
``` python
git push origin develop
```
%% Output
Everything up-to-date
git/git-essential_commands.rst 0 → 100644
+ 155
− 0
View file @ 405caea4
**This tutorial is for the following functions:**
- creating, switching, merging, and deleting branches
- pulling latest changes from remote repository
- making a commit
- pushing changes to remote repository
Startup git
===========
Replace /Users/filepath/etc with the filepath of the local git directory
you wish to work on.
.. code:: ipython3
cd /Users/filepath/etc
Create a new branch
===================
This command creates a new branch AND switches to it. Replace
branch_name with your desired name.
.. code:: ipython3
git checkout -b branch_name
Switch Branches
===============
See what branch you are on
.. code:: ipython3
git branch
Switch branches (syntax: git checkout branch_name)
.. code:: ipython3
git checkout develop
.. code:: ipython3
git checkout master
Merge
=====
Use this to add changes from one branch to another. This will make both
branches identical!
Use git checkout command to make sure you are on the branch you want to
merge your changes with.
.. code:: ipython3
git checkout develop
Then tell git the other branch you made the changes on that you are
bringing into your aforementioned branch.
.. code:: ipython3
git merge branch_name
Delete a branch
===============
Sometimes you will want to delete locally created branches, such as
after you have merged your changes to another branch. (Note: If you are
purposefully deleting a branch without committing your changes, git may
ask you to confirm this by making you rerun the following command with a
capital “D”.)
.. code:: ipython3
git branch -d branch_name
Pull
====
Use this to replace files in your local repository with the latest
versions from the remote repository.
Checkout the local branch you would like to pull changes to.
.. code:: ipython3
git checkout develop
Select which remote branch you would like to pull changes from and pull.
(syntax: git pull remote_name branch_name)
.. code:: ipython3
git pull origin develop
Make a Commit
=============
Use this to finalize a file edit or addition and provide a reason.
Step 1
^^^^^^^^
Make a change to your file (and/or drag a new file into your git
repository).
Step 2
^^^^^^^^
Choose file(s) to commit. Replace the filepath at the end of the cell
below with the filepath of the file(s) you would like to commit. (Note:
If you would like to commit multiple files at once with the same commit
message, you can do so by adding the parent folder of all edited files.)
.. code:: ipython3
git add /example/filepath/User/Documents/git/file.txt
Step 3
^^^^^^^^
Place your reason for the commit inside quotes. If the file(s) are new
to the repository, simply put “Initial commit”.
.. code:: ipython3
git commit -m "Initial commit"
Push
====
Use this to update files in the remote repository with your committed
files. Note: You may run into errors if the local branch you are pushing
does not have the same name as the remote branch you are pushing to
(e.g. trying to push from a local branch named “testing” to a branch in
the GitLab repository named “develop”). It is recommended you push from
a branch with the same name as the remote branch you are trying to push
to.
See a list of all files you have made commits to since your last push.
.. code:: ipython3
git status
(syntax: git push remote_name branch_name)
.. code:: ipython3
git push origin develop
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment