swcarpentry / git-novice Goto Github PK
View Code? Open in Web Editor NEWVersion Control with Git
Home Page: http://swcarpentry.github.io/git-novice/
License: Other
Version Control with Git
Home Page: http://swcarpentry.github.io/git-novice/
License: Other
I added some figures I'd drawn for past workshops in #74. What do you all think?
The word "backup" is used twice (inclusive of the heading) in the prose. Why does this lesson contain backup in the filename and headings? I feel that this is confusing and, or associating git with backing up is dangerous.
This blog post talks about the problem participants often have using git on older Mac laptops. It offers this site as a solution, which is an archive of older versions git. I'm thinking we need a short guidance document to provide some instructions on how to use that repository of old Git versions. For instance, which versions match up with which releases of Mac OS X? What do you do with one of the files once you've download it?
https://guides.github.com/activities/citable-code/ should be mentioned in our lessons.
More info in this thread:
discussion.md
was added in #36, but doesn't comply with the lesson template completely. From https://raw.githubusercontent.com/swcarpentry/lesson-template/gh-pages/tools/check.py:
03-conflicts.md
@delbauer started a thread in this mail message about how to motivate use of licenses. It looks like there's lots to talk about, so let's move the discussion here and hope that it turns into a PR.
At some images part of the text is outside of the box.
This is bugging me for a long time.
First I thought that this is a font problem but I check the font and I didn't get any warning. Because of it I report a bug to LibreOffice developers, https://bugs.documentfoundation.org/show_bug.cgi?id=90414, and will be grateful if someone with more experience using LibreOffice than me could help solving this.
I recently watched my co-instructor teach the first part of the git lesson and I now understand why @gvwilson feels git is very inappropriate for beginners. I feel that git checkout
is very confusing for learners and could probably be skipped.
I drafted a post-workshop blog post, available there http://home.heeere.com/teach-swc-cern-201507.html
(see the section named The “git checkout” Mess-Understanding).
I'd like to see what people feel about git checkout
.
Here are the main arguments against it: confusing, dangerous (detached head mess), not-so-useful, replaceable.
Lately I've taken time after lunch for students to work on a github project for them to practice all the commands. I type the instructions on the screen with the diagram for reference. The instructions are below:
Pair up, into person A and person B
Part I
1. person-A fork person-B's repository
2. person-A clone the forked repository to your local computer
3. person-A make a change to the repository
4. person-A push the change to your github account
5. person-A create a pull request to person-B
5.1. collaborate
6. person-B accept the change
Part II
1. person-B make a new change after your pull request
2. person-A add person-B's repository as a new remote (upstream)
`git remote add upstream GIT_URL`
3. person-A get the new changes from person-B
4. person-A update your github fork so it is the same as Person-B
part III
1. switch roles.
Would we be able to add this to the git lesson?
When reviewing 06-collaborating.md
, I noticed that it has two different parts. The first deals on how to set up a remote repo in Github for your local repo, and the second on how to add collaborators and have them cloning your repo. I'd like to split it in two shorter topics.
An advantage of this is that i t would be decouple the two parts, so we have several alternatives for the collaboration section (as is, doing PRs, role-play between instructors.)
If people is in favor of that, I could split it for 5.3 and we'll consider alternative collaboration sections for future releases.
What do you think?
After the git workshop I taught, I think it was confusing for students to pull a classmate's repo that was named planets
but was different from their own planets
repo.
This may be fixed if we have students name their repos something unique... i.e., planets-username
or something like that. It would involve fixing references to planets
throughout the lesson, including some of the images. If others think this would help I can edit all the text and images I can work on this... just don't want to start unless there is consensus that this would work.
I am not able to build a local version of the site using make preview
. I am running Anaconda (Python 3.4) on Linux, and have installed dependencies in requirements.txt
via pip.
$ make preview
pandoc -s -t html \
--template=_layouts/page \
--filter=tools/filters/blockquote2div.py \
--filter=tools/filters/id4glossary.py \
-Vheader="$(cat _includes/header.html)" -Vbanner="$(cat _includes/banner.html)" -Vfooter="$(cat _includes/footer.html)" -Vjavascript="$(cat _includes/javascript.html)" \
-o 01-backup.html 01-backup.md
pandoc: Error running filter tools/filters/blockquote2div.py
tools/filters/blockquote2div.py not found in path
make: *** [01-backup.html] Error 83
From https://raw.githubusercontent.com/swcarpentry/lesson-template/gh-pages/tools/check.py:
Related with #98.
What about replace
$ mkdir new-repo
$ cd new-repo
$ git init
with
$ git init new-repo
$ cd new-repo
currently say To reference Software Carpentry in publications, please cite both of the following:
at the bottom, but only 1 reference is listed
Please use this issue for discussion of changes we should make by mid-August 2015.
The automated version control lesson hints fairly strongly at a mental model were version control systems storing things as a series of changes. For example, quoting from the page
Version control systems start with a base version of the document and then save just the changes you made at each step of the way. You can think of it as a tape: if you rewind the tape and start at the base document, then you can play back each change and end up with your latest version.
Git does not do this. It stores the complete tree with every commit. Due to the way the storage system works (data is stored under the hash of its content), only new data (changed files and tree structures) get added with each commit. Files and tree structures matching existing files and tree structures windup just pointing to the existing copies already stored from prior commits. This is reasonably efficient space-wise so long as your workflow isn't a lot of minor edits to very large files.
The reason I suggest the "series of patches" mental model should not be put into people's heads is I found having this mental model to be the single biggest mental block I had to wrapping my head around multi-way merges. It was not until I realized that a commit was just a link to the current tree and all parent trees (i.e., no patches) that I really began to understand things.
I will attempt to come up with a pull request with an alternative as part of my teaching certification.
In the teaching notes in instructors.md
, we mention the problem of end of line characters for learners using Windows. I think this could be solved during the configuration in 01-setup.md
by setting:
git config --global core.autocrlf input
for Mac OS and Linux, and,
git config --global core.autocrlf true
for Windows, as recommended by Github.
Shouldn't that fix all end-of-line issues for everyone? It's just one more line and a little bit harder to explain than the rest, but may be worthy.
$ git log -- data/
commit e0b6f49ecd70bccca0c090ec004401a185151241
Author: Trevor Bekolay <[email protected]>
Date: Tue Oct 21 11:59:14 2014 -0400
Implementation of Greg Wilson's template
This is up for discussion, but at the moment is the
minimal set of files needed to be a Software Carpentry lesson.
Coming from a novice perspective and from the irritation of having to copy and paste code blocks with $
in them, do we really need these markers? I know novices get confused by them (it has come up a few times I have helped with workshops) and I myself got confused when I first started using the shell.
So my question is: Is this age-old tradition necessary in our current teaching environment and (in general) our non-computer science-background audience? It seems to be a hindrance that lacks any practical purpose besides tradition. I mean, we have code blocks for a reason, to separate code text from normal text (which I assume is what $
did before there were code blocks).
I recommend we remove them.
In workshops teaching R through RStudio, it's becoming a more common pattern to teach this git command line lesson, then follow it with a short lesson demonstrating the git GUI interface in RStudio. It would be useful to have this "transition" lesson written up with screenshots. While RStudio isn't quite a full-featured git GUI it is the environment many students will use.
This could also live in the r-novice repositories.
Here are some lessons designed for teaching git only through RStudio which could be adapted:
There are a couple of technical issues for this:
-u
flag, e.g. git push -u origin master
.The section on Gedit in the instructors' guide seems out of place - it should be moved into discussion of other editors.
The following figures need to be update to have the same look of the others figures.
fig/git-when-revisions-updated.svg
fig/git-freshly-made-github-repo.svg
fig/github-repo-after-first-push.svg
I'll add one once a pending PR to this file in lesson-template is merged.
Just an observation that from the first paragraph users may not realize that version control can be useful for working alone as well as with a team. Though it is essentially mentioned later in the first bullet point:
Nothing that is committed to version control is ever lost. This means it can be used like the "undo" feature in an editor, and since all old versions of files are saved it's always possible to go back in time to see exactly who wrote what on a particular day, or what version of a program was used to generate a particular set of results.
It is also mentioned in chapter 1, but may have a place in the introduction. Some examples that may motivate the usefulness of version control beyond collaborating:
This tutorial almost perfect for my target audience. The only thing missing, I think, is to show how to properly delete and move files around. Should be fairly straightforward to add something like that to the "change" section.
From https://raw.githubusercontent.com/swcarpentry/lesson-template/gh-pages/tools/check.py:
Based on swcarpentry/DEPRECATED-lesson-template#139:
02-collab.md
, 03-conflict.md
, and 04-open.md
need estimates for the lesson duration.
Anybody has good numbers for that?
What is the GitHub Timestamp challenge in 06_collab
trying to show?
It reads:
Create a repository on GitHub, clone it, add a file, push those changes to GitHub, and then look at the timestamp of the change on GitHub. How does GitHub record times, and why?
The "How does GitHub record times, and why?" implies to me that the learners will find that timestamps appear in UTC. Perhaps that was once the case, and internally in git and on GitHub it undoubtedly still is, but on GitHub I see times expressed as <interval> ago
or a date for older commits, and when I hover over that I see a datetime expressed in my computer's local timezone.
Am I missing something, or has this question been eclipsed by UX improvements?
I set up gedit to be the default editor with the -s option, but it is not working
This is what I get when I do gedit --version
:
gedit - Version 2.28.4
I'll take a lot tomorrow, but I think we accidentally removed/reverted some merged commits.
In our Glossary, we have different entries for "revision" and "commit". "Commit" is defined as a verb, and "revision" as a noun. The problem is that even in the very definition of "commit", we use it as a noun.
This is not a big deal, but in the lesson (see e.g. 04-changes.md) we use sometimes "commit" and sometimes "revision" to mean a recorded set of changes in the repo. There's also instances of "version" and "set of changes". This could be confusing for a novice, specially if reading the lesson alone.
I would like to have just one word (which is better "commit" or "revision"?) for the recorded set of changes in the repo, and leave "version" for a snapshot of the files not necessary related to the repo ("the new version of your thesis was trashed by your advisor").
From https://raw.githubusercontent.com/swcarpentry/lesson-template/gh-pages/tools/check.py:
In the git lesson, in the Remotes in GitHub section, there are some references to sections that don't exist (perhaps they did in earlier versions of the curriculum? or am I missing something?)
Most programmers use hosting services like GitHub, BitBucket or GitLab to hold those master copies; we’ll explore the pros and cons of this in the final section of this lesson.
This comparison isn't actually in the final section of this lesson.
You may see a -u option used with git push in some documentation. It is related to concepts we cover in our intermediate lesson, and can safely be ignored for now.
Is there an intermediate lesson? If not can we just say it's an intermediate concept that can be safely ignored for now?
If others agree I can make these changes.
There are some FIXME
at instructors.md
.
See #135.
Currently, we don't explain much on how to write a commit message: what the contents should be, how long it should be, or what's the point of it. I think that, without going into much details, a good explanatory sentence in the part of the lesson where the first commit is created would be nice.
An entry for "commit message" could be also added to the lesson glossary in reference.md
.
See also the discussion in #70.
We should use {.bash} because will make easy if we want to add the prompt by CSS.
{.input} was used in bc.
Originally swcarpentry/DEPRECATED-bc#600: we should have instructions somewhere explaining how to configure commonly-used editors to work with Git on all three platforms.
From https://raw.githubusercontent.com/swcarpentry/lesson-template/gh-pages/tools/check.py:
From https://raw.githubusercontent.com/swcarpentry/lesson-template/gh-pages/tools/check.py:
I'm wondering if there has been feedback from workshops on the last challenge of a git repo inside a git repo. While I like the challenge question of why it is a bad idea, I think that the steps are confusing for someone learning git. New learners of git (especially if they are learning bash too) are easily confused about where they are in the filesystem tree.
Recommendation: Remove the steps in this challenge and keep the question for students to ponder. Add a challenge that has the student moving through the history of the log using HEAD~1 would be a better exercise.
The SVN version of this lesson included pictures of Wolfman and Dracula. It would be nice to have this pictures made relevant for git and added into the lesson.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.