This repository has been archived by the owner on Jan 3, 2018. It is now read-only.
Cleanups for the git/novice material #187
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Hopefully it's clear from the context that we're running commands ;). Now the text just focuses on *why*.
We're talking about the message, 'untracked files' just clarifies which message we mean. I don't really have a good argument here, but I think the form with 'untracked files' first sounds better. I'd also be happy with: The message about "untracked files" means...
High pronoun density makes me confused ;). Adding a few extra words to make things explicit should avoid confusion.
`-m` is great when we're writing examples, because editor screen shots just add complication. However, I hardly ever use `-m` myself (and I usually use `-v`). Telling students that they don't have to remember `-m` will hopefully be comforting. Now that the `-m` (or not) discussion is a bit more involved, break the subsequent `status` lead-in off into its own paragraph.
I expect shell redirected output (>>) was used in a previous version of this lesson. However, this version is using nano to edit the file, so the >> reminder is no longer needed.
If diffs were not intended for human consumption, I'd expect they would be printed in a binary format. If you want a format that's almost exactly like Microsoft Word's "track changes" feature, you can use `--word-diff=color`. For code, the default format is probably more legible. Also, the colorized output (we configured color.ui earlier) may help a bit. Can we colorize the Markdown preformatted block? In any case, I think the tone we're shooting for is "don't worry if you don't understand the diff yet, we're about to explain it", not "you might as well give up now, this is only for wizards" ;).
I've only ever seen it used on the Git mailing list to ask if a patch was based on unpublished work, but digging that reference out of the mailing list archives would be difficult. Newbies probably don't care about the information encoded in that line.
That's what we use for `@@`, and we should be consistent. Code styling should also match the preformatted-block styling used for the diff itself, and it's nice if the styling of our reference matches the styling of the original.
I don't find this argument very convincing. I rarely have to reset a particular program class or document section to an earlier revision. I *do* have to undo broken commits, but there you have `git rebase` or `git revert` to help you out. Without that use case to motivate it, I think "you'll probably want to restructure your workflow to use lots of tiny files" is too aggressive for new Git users.
Move implies a single copy switching from one place to another. In other words, the original location no longer has the moved item after the move. Version control systems usually copy between repositories, adding the item to the new location without removing it from the original location. I also changed the item from 'files' to 'changes', because although for Git, both blobs and commits are copied. To me, 'changes' implies the broader scope (current status, as well as why and how we got there), while 'files' just implies the current status.
For folks to see some other options. I can't cite statistics, but even Software Carpentry is moving away from the centralized repo workflow. Every other project I'm involved with (outside of my job) uses the 'integration manager' workflow. I think it's best to soften statements like "it's easiest" and "most programmers" and instead just say we're going to show them a popular approach, while linking to a number of other popular approaches.
Git calls them protocols in the 'GIT URLS' section of git-fetch(1). No need to use our own name. Hopefully not too many people mind the 'Hypertext Transfer Protocol protocol' redundancy ;).
In 2013, even novice Git users should have heard the term 'URL' a few times before they get into our class.
I don't think the distinction between: $ git push -u nickname master and $ git push nicname master is useful for newbies. The former is explained as "Push changes from a local repository to a remote (if master doesn't yet exist in the remote)", but that's not what the -u option actually does (it actually sets the upstream branch, see git push --help for details). I only use -u myself when I'm setting up a branch for a hub pull-request [1,2]. I'm not sure we should be teaching the more implicit forms of push, because the default semantics are going to change with Git 2.0 [3]. I imagine that will lead to confusion if students are referring to notes that haven't been future-proofed by either: a. explaining the change in push semantics, or b. only using explicit forms (`git push $REMOTE $BRANCH`) In the interest of simplicity (and following PEP 20 [4]), I'm in favor of option b. Then students don't need to internalize the default remote- and branch-selection rules. If we go with (b), I don't see why we'd care about the default upstream branch. Perhaps we want 'git status' to explain: # Your branch is ahead of 'origin/master' by 14 commits. or some such. If so, I think that we should explicitly use that in our motivation. [1]: https://github.com/github/hub#contributing [2]: https://github.com/github/hub/blob/master/lib/hub/commands.rb#L179 [3]: http://git.kernel.org/cgit/git/git.git/tree/Documentation/RelNotes/1.8.5.txt#n7 [4]: http://www.python.org/dev/peps/pep-0020/
Git would complain that 'tip of your current branch is behind hint: its remote counterpart' event if the changes didn't overlap. The problem is that the push isn't a fast forward, not that there are merge conflicts.
We added the remote as 'vlad' in 02-collab.md. I expect the 'gvwilson' entries are just copy/paste errors.
For explaining conflict avoidance. The size of your file doesn't really matter to Git (outside of the three lines of diff context, it doesn't care at all). Communication is important, and separate files may help you do that, but there are other ways to avoid stepping on toes as well (including shouting "I'm about to refactor fizz_buzz(), do you have any pending changes I should know about first?" across the hallway).
From the current https://bitbucket.org/plans: All plans include: * Unlimited private repos ... I think the main reason to use common hosting sites like GitHub and Bitbucket is increased visibility or access to features (like the web interface and bug trackers). Personally, I wouldn't trust a third party host to protect my private data when I can easily host it myself. I'm not sure how widely shared this paranoia is ;), but I'd certainly want to talk to lawyers before hosting patient medical records in a private repository on Bitbucket.
|
See #191 - still unsure how to explain the |
|
See discussion in #191. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Some of these are simple typo fixes, others may be more controversial.
Details in the individual commit messages. There's no overarching
organization here, I just edited as I saw fit during a read-through.