Skip to content

Commit ae5fbdb

Browse files
actions-useractions-user
committed
source commit: 2c5591f 
0 parents  commit ae5fbdb

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+9414
-0
lines changed

‎01-basics.md

+127
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Automated Version Control
3+
teaching: 5
4+
exercises: 0
5+
---
6+
7+
::::::::::::::::::::::::::::::::::::::: objectives
8+
9+
- Understand the benefits of an automated version control system.
10+
- Understand the basics of how automated version control systems work.
11+
12+
::::::::::::::::::::::::::::::::::::::::::::::::::
13+
14+
:::::::::::::::::::::::::::::::::::::::: questions
15+
16+
- What is version control and why should I use it?
17+
18+
::::::::::::::::::::::::::::::::::::::::::::::::::
19+
20+
We'll start by exploring how version control can be used
21+
to keep track of what one person did and when.
22+
Even if you aren't collaborating with other people,
23+
automated version control is much better than this situation:
24+
25+
!["notFinal.doc" by Jorge Cham, <https://www.phdcomics.com>](fig/phd101212s.png){alt='Comic: a PhD student sends "FINAL.doc" to their supervisor, but after several increasingly intense and frustrating rounds of comments and revisions they end up with a file named "FINAL_rev.22.comments49.corrections.10.#@$%WHYDIDCOMETOGRADSCHOOL????.doc"'}
26+
27+
We've all been in this situation before: it seems unnecessary to have
28+
multiple nearly-identical versions of the same document. Some word
29+
processors let us deal with this a little better, such as Microsoft
30+
Word's
31+
[Track Changes](https://support.office.com/en-us/article/Track-changes-in-Word-197ba630-0f5f-4a8e-9a77-3712475e806a),
32+
Google Docs' [version history](https://support.google.com/docs/answer/190843?hl=en), or
33+
LibreOffice's [Recording and Displaying Changes](https://help.libreoffice.org/Common/Recording_and_Displaying_Changes).
34+
35+
Version control systems start with a base version of the document and
36+
then record changes you make each step of the way. You can
37+
think of it as a recording of your progress: you can rewind to start at the base
38+
document and play back each change you made, eventually arriving at your
39+
more recent version.
40+
41+
![](fig/play-changes.svg){alt='A diagram demonstrating how a single document grows as the result of sequential changes'}
42+
43+
Once you think of changes as separate from the document itself, you
44+
can then think about "playing back" different sets of changes on the base document, ultimately
45+
resulting in different versions of that document. For example, two users can make independent
46+
sets of changes on the same document.
47+
48+
![](fig/versions.svg){alt='A diagram with one source document that has been modified in two different ways to produce two different versions of the document'}
49+
50+
Unless multiple users make changes to the same section of the document - a
51+
[conflict](../learners/reference.md#conflict) - you can
52+
incorporate two sets of changes into the same base document.
53+
54+
![](fig/merge.svg){alt='A diagram that shows the merging of two different document versions into one document that contains all of the changes from both versions'}
55+
56+
A version control system is a tool that keeps track of these changes for us,
57+
effectively creating different versions of our files. It allows us to decide
58+
which changes will be made to the next version (each record of these changes is
59+
called a [commit](../learners/reference.md#commit)), and keeps useful metadata
60+
about them. The complete history of commits for a particular project and their
61+
metadata make up a [repository](../learners/reference.md#repository).
62+
Repositories can be kept in sync across different computers, facilitating
63+
collaboration among different people.
64+
65+
::::::::::::::::::::::::::::::::::::::::: callout
66+
67+
## The Long History of Version Control Systems
68+
69+
Automated version control systems are nothing new.
70+
Tools like [RCS](https://en.wikipedia.org/wiki/Revision_Control_System), [CVS](https://en.wikipedia.org/wiki/Concurrent_Versions_System), or [Subversion](https://en.wikipedia.org/wiki/Apache_Subversion) have been around since the early 1980s and are used by
71+
many large companies.
72+
However, many of these are now considered legacy systems (i.e., outdated) due to various
73+
limitations in their capabilities.
74+
More modern systems, such as Git and [Mercurial](https://swcarpentry.github.io/hg-novice/),
75+
are *distributed*, meaning that they do not need a centralized server to host the repository.
76+
These modern systems also include powerful merging tools that make it possible for
77+
multiple authors to work on
78+
the same files concurrently.
79+
80+
81+
::::::::::::::::::::::::::::::::::::::::::::::::::
82+
83+
::::::::::::::::::::::::::::::::::::::: challenge
84+
85+
## Paper Writing
86+
87+
- Imagine you drafted an excellent paragraph for a paper you are writing, but later ruin
88+
it. How would you retrieve the *excellent* version of your conclusion? Is it even possible?
89+
90+
- Imagine you have 5 co-authors. How would you manage the changes and comments
91+
they make to your paper? If you use LibreOffice Writer or Microsoft Word, what happens if
92+
you accept changes made using the `Track Changes` option? Do you have a
93+
history of those changes?
94+
95+
::::::::::::::: solution
96+
97+
## Solution
98+
99+
- Recovering the excellent version is only possible if you created a copy
100+
of the old version of the paper. The danger of losing good versions
101+
often leads to the problematic workflow illustrated in the PhD Comics
102+
cartoon at the top of this page.
103+
104+
- Collaborative writing with traditional word processors is cumbersome.
105+
Either every collaborator has to work on a document sequentially
106+
(slowing down the process of writing), or you have to send out a
107+
version to all collaborators and manually merge their comments into
108+
your document. The 'track changes' or 'record changes' option can
109+
highlight changes for you and simplifies merging, but as soon as you
110+
accept changes you will lose their history. You will then no longer
111+
know who suggested that change, why it was suggested, or when it was
112+
merged into the rest of the document. Even online word processors like
113+
Google Docs or Microsoft Office Online do not fully resolve these
114+
problems.
115+
116+
117+
118+
:::::::::::::::::::::::::
119+
120+
::::::::::::::::::::::::::::::::::::::::::::::::::
121+
122+
:::::::::::::::::::::::::::::::::::::::: keypoints
123+
124+
- Version control is like an unlimited 'undo'.
125+
- Version control also allows many people to work in parallel.
126+
127+
::::::::::::::::::::::::::::::::::::::::::::::::::

‎02-setup.md

+225
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
---
2+
title: Setting Up Git
3+
teaching: 5
4+
exercises: 0
5+
---
6+
7+
::::::::::::::::::::::::::::::::::::::: objectives
8+
9+
- Configure `git` the first time it is used on a computer.
10+
- Understand the meaning of the `--global` configuration flag.
11+
12+
::::::::::::::::::::::::::::::::::::::::::::::::::
13+
14+
:::::::::::::::::::::::::::::::::::::::: questions
15+
16+
- How do I get set up to use Git?
17+
18+
::::::::::::::::::::::::::::::::::::::::::::::::::
19+
20+
When we use Git on a new computer for the first time,
21+
we need to configure a few things. Below are a few examples
22+
of configurations we will set as we get started with Git:
23+
24+
- our name and email address,
25+
- what our preferred text editor is,
26+
- and that we want to use these settings globally (i.e. for every project).
27+
28+
On a command line, Git commands are written as `git verb options`,
29+
where `verb` is what we actually want to do and `options` is additional optional information which may be needed for the `verb`. So here is how
30+
Alfredo sets up his new laptop:
31+
32+
```bash
33+
$ git config --global user.name "Alfredo Linguini"
34+
$ git config --global user.email "[email protected]"
35+
```
36+
37+
Please use your own name and email address instead of Alfredo's. This user name and email will be associated with your subsequent Git activity,
38+
which means that any changes pushed to
39+
[GitHub](https://github.com/),
40+
[BitBucket](https://bitbucket.org/),
41+
[GitLab](https://gitlab.com/) or
42+
another Git host server
43+
after this lesson will include this information.
44+
45+
For this lesson, we will be interacting with [GitHub](https://github.com/) and so the email address used should be the same as the one used when setting up your GitHub account. If you are concerned about privacy, please review [GitHub's instructions for keeping your email address private][git-privacy].
46+
47+
::::::::::::::::::::::::::::::::::::::::: callout
48+
49+
## Keeping your email private
50+
51+
If you elect to use a private email address with GitHub, then use GitHub's no-reply email address for the `user.email` value. It looks like `[email protected]`. You can look up your own address in your GitHub [email settings](https://github.com/settings/emails).
52+
53+
54+
::::::::::::::::::::::::::::::::::::::::::::::::::
55+
56+
::::::::::::::::::::::::::::::::::::::::: callout
57+
58+
## Line Endings
59+
60+
As with other keys, when you press <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd> on your keyboard,
61+
your computer encodes this input as a character.
62+
Different operating systems use different character(s) to represent the end of a line.
63+
(You may also hear these referred to as newlines or line breaks.)
64+
Because Git uses these characters to compare files,
65+
it may cause unexpected issues when editing a file on different machines.
66+
Though it is beyond the scope of this lesson, you can read more about this issue
67+
[in the Pro Git book](https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_core_autocrlf).
68+
69+
You can change the way Git recognizes and encodes line endings
70+
using the `core.autocrlf` command to `git config`.
71+
The following settings are recommended:
72+
73+
On macOS and Linux:
74+
75+
```bash
76+
$ git config --global core.autocrlf input
77+
```
78+
79+
And on Windows:
80+
81+
```bash
82+
$ git config --global core.autocrlf true
83+
```
84+
85+
::::::::::::::::::::::::::::::::::::::::::::::::::
86+
87+
Alfredo also has to set his favorite text editor, following this table:
88+
89+
| Editor | Configuration command |
90+
| :----------- | :------------------------------ |
91+
| Atom | `$ git config --global core.editor "atom --wait"` |
92+
| nano | `$ git config --global core.editor "nano -w"` |
93+
| BBEdit (Mac, with command line tools) | `$ git config --global core.editor "bbedit -w"` |
94+
| Sublime Text (Mac) | `$ git config --global core.editor "/Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl -n -w"` |
95+
| Sublime Text (Win, 32-bit install) | `$ git config --global core.editor "'c:/program files (x86)/sublime text 3/sublime_text.exe' -w"` |
96+
| Sublime Text (Win, 64-bit install) | `$ git config --global core.editor "'c:/program files/sublime text 3/sublime_text.exe' -w"` |
97+
| Notepad (Win) | `$ git config --global core.editor "c:/Windows/System32/notepad.exe"` |
98+
| Notepad++ (Win, 32-bit install) | `$ git config --global core.editor "'c:/program files (x86)/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"` |
99+
| Notepad++ (Win, 64-bit install) | `$ git config --global core.editor "'c:/program files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"` |
100+
| Kate (Linux) | `$ git config --global core.editor "kate"` |
101+
| Gedit (Linux) | `$ git config --global core.editor "gedit --wait --new-window"` |
102+
| Scratch (Linux) | `$ git config --global core.editor "scratch-text-editor"` |
103+
| Emacs | `$ git config --global core.editor "emacs"` |
104+
| Vim | `$ git config --global core.editor "vim"` |
105+
| VS Code | `$ git config --global core.editor "code --wait"` |
106+
107+
It is possible to reconfigure the text editor for Git whenever you want to change it.
108+
109+
::::::::::::::::::::::::::::::::::::::::: callout
110+
111+
## Exiting Vim
112+
113+
Note that Vim is the default editor for many programs. If you haven't used Vim before and wish to exit a session without saving
114+
your changes, press <kbd>Esc</kbd> then type `:q!` and press <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd>.
115+
If you want to save your changes and quit, press <kbd>Esc</kbd> then type `:wq` and press <kbd>Enter</kbd> or <kbd>↵</kbd> or on Macs, <kbd>Return</kbd>.
116+
117+
118+
::::::::::::::::::::::::::::::::::::::::::::::::::
119+
120+
Git (2.28+) allows configuration of the name of the branch created when you
121+
initialize any new repository. Alfredo decides to use that feature to set it to `main` so
122+
it matches the cloud service he will eventually use.
123+
124+
```bash
125+
$ git config --global init.defaultBranch main
126+
```
127+
128+
::::::::::::::::::::::::::::::::::::::::: callout
129+
130+
## Default Git branch naming
131+
132+
Source file changes are associated with a "branch."
133+
For new learners in this lesson, it's enough to know that branches exist, and this lesson uses one branch.
134+
By default, Git will create a branch called `master`
135+
when you create a new repository with `git init` (as explained in the next Episode). This term evokes
136+
the racist practice of human slavery and the
137+
[software development community](https://github.com/github/renaming) has moved to adopt
138+
more inclusive language.
139+
140+
In 2020, most Git code hosting services transitioned to using `main` as the default
141+
branch. As an example, any new repository that is opened in GitHub and GitLab default
142+
to `main`. However, Git has not yet made the same change. As a result, local repositories
143+
must be manually configured have the same main branch name as most cloud services.
144+
145+
For versions of Git prior to 2.28, the change can be made on an individual repository level. The
146+
command for this is in the next episode. Note that if this value is unset in your local Git
147+
configuration, the `init.defaultBranch` value defaults to `master`.
148+
149+
::::::::::::::::::::::::::::::::::::::::::::::::::
150+
151+
The five commands we just ran above only need to be run once: the flag `--global` tells Git
152+
to use the settings for every project, in your user account, on this computer.
153+
154+
Let's review those settings and test our `core.editor` right away:
155+
156+
```bash
157+
$ git config --global --edit
158+
```
159+
160+
Let's close the file without making any additional changes. Remember, since typos in the config file will cause
161+
issues, it's safer to view the configuration with:
162+
163+
```bash
164+
$ git config --list
165+
```
166+
167+
And if necessary, change your configuration using the
168+
same commands to choose another editor or update your email address.
169+
This can be done as many times as you want.
170+
171+
::::::::::::::::::::::::::::::::::::::::: callout
172+
173+
## Proxy
174+
175+
In some networks you need to use a
176+
[proxy](https://en.wikipedia.org/wiki/Proxy_server). If this is the case, you
177+
may also need to tell Git about the proxy:
178+
179+
```bash
180+
$ git config --global http.proxy proxy-url
181+
$ git config --global https.proxy proxy-url
182+
```
183+
184+
To disable the proxy, use
185+
186+
```bash
187+
$ git config --global --unset http.proxy
188+
$ git config --global --unset https.proxy
189+
```
190+
191+
::::::::::::::::::::::::::::::::::::::::::::::::::
192+
193+
::::::::::::::::::::::::::::::::::::::::: callout
194+
195+
## Git Help and Manual
196+
197+
Always remember that if you forget the subcommands or options of a `git` command, you can access the
198+
relevant list of options typing `git <command> -h` or access the corresponding Git manual by typing
199+
`git <command> --help`, e.g.:
200+
201+
```bash
202+
$ git config -h
203+
$ git config --help
204+
```
205+
206+
While viewing the manual, remember the `:` is a prompt waiting for commands and you can press <kbd>Q</kbd> to exit the manual.
207+
208+
More generally, you can get the list of available `git` commands and further resources of the Git manual typing:
209+
210+
```bash
211+
$ git help
212+
```
213+
214+
::::::::::::::::::::::::::::::::::::::::::::::::::
215+
216+
[git-privacy]: https://help.github.com/articles/keeping-your-email-address-private/
217+
218+
219+
:::::::::::::::::::::::::::::::::::::::: keypoints
220+
221+
- Use `git config` with the `--global` option to configure a user name, email address, editor, and other preferences once per machine.
222+
223+
::::::::::::::::::::::::::::::::::::::::::::::::::
224+
225+

0 commit comments

Comments
 (0)