coderefinery / git-intro

Introduction to version control with Git - Why we want to track versions and how to go back in time to a working version

Introduction to version control with Git

Why we want to track versions and how to go back in time to a working version

git-intro's Issues

Improve the introduction part in git basics

The first two questions:
What is Git?
What is a repository?

Are not really answered upfront. Give it a shot to see whether this can be explained before "git init". If I succeed may be basics are well set in before hands on.

Notes from Espoo

This is running notes for this lesson.

• Option to set default editor to nano: git config core.editor nano
• Add nano to installation requirements (?)
• Remind people more often about postit notes

Add list of common aliases for people to copy

Some may like them, some may not. At least lack of good aliases is a common git problem and we can make it easier.

I have a large example file from somewhere I can give.

Simplify the Git intro by minimizing new concepts directly not relevent for git

1. Change the python example to a simple text file or a shell script (e.g just echo "sabryr added this line" ) and compare with the comments. Then emphasize the importance of the comments when the changes are not trivial.
   Reason:
   A. This is a git intro and remove the mentioning of Python
   B. Diff is easier to comprehend when it is just text, or simple script

*This is a suggestion and if someone has a good counter argument I will take it as it is.

shorten and refine text

particularly in Basics, make it less verbose and more bullet-point based. Also correct a few typos

Please rephrase "something something"

https://coderefinery.github.io/git-intro/01-basics/#what-is-version-control @Sabryr

add git command cheat sheet somewhere at the end

we should compile all commands that we use (and maybe some others) in git-intro, git-collab and git-archeology and make a cheat-sheet lesson. not sure if git-intro is the right place to put it, but it then has the advantage that learners see it and can go back to it during the git-collab and git-archeology sessions

Demonstrate the use of a visual diff tool

Would be nice but not incredibly important before tomorrow if the time is tight.

add more about git diff, git show

git show is hardly mentioned. More features of git diff should be demonstrated and exercised

There is not enough focus on reverting the changes

We talk a lot about progression, but the focus on undoing things is not enough. In fact I do not see anywhere this is explicitly addressed. The way it is lessons are simple. But the reality is it has to be exposed at some point.

Motivate better

Motivate better, include selling points, why before how

Git checkout branch is discussed before branches are introduced

This was done to show the different semantics between "undo" and "switch branches" but it is now placed before branches are introduced.

Comments on git-intro

While going through the git-intro, I felt that mentioning few additional things may be important. Perhaps, @Jyrsa has already thought about them and is planning to discuss while lecturing.

• Something about why sharing software and data is getting more popular in research context and github being a popular platform for sharing software
• Why Git over other VCS? Difference between Distributed VCS and centralized VCS? Radovan is talking about Distributed VCS in the advanced session, but in my opinion it may be helpful to briefly mention about distributed VCS in the introduction session.
• Mentioning difference between master and Head? I noticed that people often confuse about master and head.

Typos:

Have you ever had to start working software written by others? --> Have you ever had to start working on software written by others?

You can avoid using one one by always passing messages on the command line, but that limits you in the long run --> You can avoid using one by always passing messages on the command line, but that limits you in the long run.

Undoing section is perhaps confusing and too early?

Perhaps we don't need to show how to undo stuff? Perhaps it is too early and we should show more "doing" and show "undoing" later? My feeling was that throwing all the resets and checkouts at people can confuse them and the important part is to record work IMO.

Improve git staging part of the git intro

Radovan
Sabry: what I meant is that the git staging part of the git intro lesson does not work well currently, too confusing so if I needed to change one thing in the lesson, that would be it: more pictures, better example - of course no problem to change more than the staging but that is the part that I am most unhappy with

don't use word "developer"

use "researcher" instead. "Developer" can sound a bit intimidating or irrelevant, many researchers don't identify with the term

Move break to ideally 10:30

Suggestions: Basics

• First section can probably be shorter, should have been motivated before. Basic mention of .git and that it doesn't do anything unless you want. Also multiple interfaces
• "mental model of git" - 3 headings can be made much shorter (#69, #70). Some basic intro of the snapshotting, and making a basic git graph would be good. Staging is maybe useful. Other things can mostly be removed. Some conceptual stuff good.
• For maximum simplification, remove "git add" during normal commits and use "git commit" only. But this is probably not worth it.
• Agree, undoing things come too early.
• Introduce "git graph" alias earlier - this is good because the output matches what we are showing on the board and on the diagrams. Show the output of this all the time.
• Undoing section too early (#72). But some certain parts of that are OK. Actually maybe it's not too early - just focus it a bit more.
• revert vs checkout is confusing, even to me. Consider this in the undoing section.
• different meanings of checkout comes too early. Do note it's confusing and we will come back to it later.
• Best practices: these are good, but maybe to another module? Or inlining more. I don't really know how to change, probably just leave it.

Rearrange the git undo part

Rearrange the git undo part after exercises so the diagram reflects the current state

Provide dependacy check for Jekyll instaltion

If the proper dependencies are not met Jekyll installation could waste a lot of time. So include list of dependencies. Sabry will do this for Ubuntu 17.04

Consider removing the --amend example

Modifying commits can be problematic. Also the example of adding the author name is strange for me since Git knows the author of the commit.

explain better git checkout

now git checkout is only used with branches. should demonstrate how to checkout commits as well (after all, one question addresses detached HEAD)

Difftool example needs a screenshot

Remember to create a release for Aarhus

Explanation of snapshotting (git add, git commit) arrives too early

We discuss advantages of two-steps snapshotting before we even started to git init and record anything. I think we should start using it and clarify later.

Perhaps avoid git show-branch

The output is scary and not intuitive. I recommend that we present the situation rather graphically.

Restructure motivation points

“Fast” and “powerful” can be dropped in git motivation

add picture showing the difference between committed, modified and staged

in the Basics episode. The image on this page is good: https://git-scm.com/book/en/v2/Getting-Started-Git-Basics

Customise 04-branches for aarhus workshop

I wanted to avoid the story telling part. We can bring it back after Aarhus.

Suggestion for bigger restructuring

While this material is good, I think it could be made even better by a restructuring. There are two audiences which I think aren't served well (everything in this issue, I have said before but I don't think is written anywhere):

• Those who already have sort of used git (we start with stuff they already know, git init, git add, and so on)
• Those who know nothing about version control. Very soon, they go off to git init, git add, and so on and probably don't have a big picture.

I've given some git intros to academic courses, and the usual problem is some people know a lot already, and can easily teach others if others became interested.

Once I tried to write a better plan, where the why and social design are front-loaded, and then the "how" is later. It went something like:

• Why code becomes a disaster without (lots of examples here, throw in some of the famous comics about it)
• Use github web interface to see an existing project: explore the history, see contributors. Give some exercises like "this line has a bug: who did it and when?", "how many contributors", "find version on this date".
• Ideally, use browser to make a commit on existing project, maybe even a merge request (it's easy in browser, and shows cool stuff). So, bring in some of the "git in the browser" stuff, but less structured, just to show people nice things.
• Ideally something from git branch design. Now the details, but there are good stories there and when I saw this, it felt like good motivation finally came.
• Then switch to "git init" and so on...

All the intro parts is relatively non-technical so could be done in an hour maybe. I'm sure it would save at least an hour later.

Additional ideas:

• have people contribute to existing project first. I guess this is a fairly common case and many people probably would start here first anyway (just for the web browser part)

If not used here, I would adapt these to either git-in-the-browser or some "git for normal people" type talk.

Please avoid "stupid program", "stupid feature", and "foo"

Instead use simple but real examples.

Pause and emphasize different meanings of checkout

With the same command we can do very different actions: switch branches or undo changes.

Update abort a conflicting merge example

Instead of git reset --hard, show git merge --abort.

Emphasis on decorated git log instead if showbranch

The out put of
git log --graph --decorate --oneline --abbrev-commit
is easier to comprehend than showbranch

So define an alias for this and use it more.

E.g.
git config --global alias.graph "log --graph --decorate --oneline --abbrev-commit"

Change, remotes and GitHub

The Remotes and GitHub section focuses more on Bare repositories on a local collaboration. I do not think we use these in real life anymore.
I would like to use a gitbub based example I have, where I add the participants as collaborators (not the fork/pull cycle). User can use a username/password login (ssh key setup not a must). I believe this will be more realistic. If there is not objection, I will port my power-point to this document.

consider using `commit -v` as good practice

less-salt/experiment example demonstrates how to merge one feature into another

But later in the course we discuss that we should not do this but rather keep feature branches "pure". Consider changing the example to reflect this.

Streamline examples

Refine examples and streamline (not use random examples from different directions)

In the image rename "Master" to "master"

To avoid confusion.

Add a "time -->" arrow to the commit graphs

It's obvious to us, but make it clear which direction time flows. These graphs are the best way to make the abstract ideas concrete, and they need all they help they can get - at every instance.

Also, the output from "git graph" has time flowing up, most of our pictures have it going right or down. It would be nice if they could be unified, but it's not worth it - a clear time arrow is enough.

I think I had another idea about these diagrams but can't remember.

Instructor guidelines

Bullet points for each lesson, each episode,
Collecting experience - lessons learned.
Go through the git issues.

Remove ".." from branch diff examples

They are not needed and without ".." the examples are more consistent with the rest of the lesson.

Simplify recipe example, too conflict-prone

• Make very clear which lines to modify and which not and why
• Consider risk with newline characters, perhaps do not modify lines at the end of the recipe?

More emphasis on mergetool

Provide a demo with Meld. inform about the backup files.
So will not use
git config --global mergetool.keepBackup false
On my terminal to start with and show git clean instead.
Then show the git config

Checnge the timing for lessons git intro on the schedule

As undoing changes introduce need to change the timing somewhat

Diagram with working directory, staging area, and .git arrives too early

We should start typing and explain then. I think we explain concepts a bit too early.

add more exercises

This serves multiple purposes:

• more practice of the basic git status, add, commit, checkout, diff, ..., in order to get them into muscle memory
• shows more different flags and usage patterns of basic git commands
• something to do for people who finish simple exercises quickly

Apply Harsha's changes

#3

This now conflicts but this can also be applied manually. After that close the PR.

add repo to organization

this repo hasn't been added to the CodeRefinery organization so i can't push or PR

Vimdiff is default difftool

Which can be scary. In the instructions indicate that first you need your favorite diffing tool installed before you try difftool/mergetool.