Skip to content

Update the outline #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jan 22, 2014
Merged

Update the outline #1

Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
2168be1
GitHub is a chapter
ben Jan 7, 2014
c3cf5ff
Tweak github chapter
ben Jan 7, 2014
c63aab8
Three trees
ben Jan 8, 2014
b041728
Add some things
ben Jan 8, 2014
76a4312
Feedback
ben Jan 9, 2014
3a07fc7
More hosting, hg, and libgit2
ben Jan 9, 2014
11f2ca2
Other-system completionism/symmetry
ben Jan 13, 2014
750ced0
Gerrit
ben Jan 13, 2014
9db34fe
request-pull
ben Jan 13, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 60 additions & 9 deletions OUTLINE.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
* Your Editor
* Your Diff Tool
* Checking Your Settings
* Credential Caching
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

1.6 Getting Help
1.7 Summary

Expand All @@ -44,6 +45,7 @@
* Changing Your Last Commit
* Unstaging a Staged File
* Unmodifying a Modified File
* Undoing All Changes
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking maybe instead of the entire "Undoing Things" section it should roughly be replaced with the "Three Trees" explanation of the 'reset' command first and then dig into all these use cases of various types of undoing and redoing.

2.5 Working with Remotes
* Showing Your Remotes
* Adding Remote Repositories
Expand Down Expand Up @@ -71,6 +73,8 @@
* Basic Branching
* Basic Merging
* Basic Merge Conflicts
* Rerere
* Undoing Merges (or should this go in "Undoing Things"?)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this needs to go after "Basic Branching and Merging" so they know what a merge commit is. Perhaps after the "Rebasing" section instead.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I think the "rerere" command belongs better in Chapter 6 with the rest of the semi-random tools. We should probably briefly mention it and cross reference from the 5.3 Maintaining section, since that's where it's most used, though.

3.3 Branch Management
3.4 Branching Workflows
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a thought about this section. In the github-alm book there was a section on branching workflows, and the TOC ended up looking like this:

  • Branching models
    • 1 branch: commit to trunk
    • 2 branches: master & features (GitHub flow)
    • 3 branches: master, dev, features
    • 4+ branches: Usually for specific reason (e.g. Git Flow), or out of control

I kind of like the math-ness of how it came out, and how it shows that mo' branches = mo' problems. This also has kind of a narrative about a project's evolution. Do you think it could work here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, it's not really '2 branches' though. It's 1, 1+N, 2+N, etc. I think 1, 1+N and >1+N are the three interesting narratives, where 1 is master only, 1+N is GitHub flow-like and >1+N is the concept of having several long running named branches and several short lived feature branches, git-flow being an example.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So do you think this:

  • master only
  • master + feature branches
  • master + dev + feature branches
  • git-flow/release branches/other things that are insane

… would be a better way to structure this? I'm kind of liking that, and it's more-or-less a superset of what's there in the first edition.

* Long-Running Branches
Expand All @@ -83,6 +87,7 @@
* The Basic Rebase
* More Interesting Rebases
* The Perils of Rebasing
* Rebase vs. Merge
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

3.7 Summary

4. Git on the Server
Expand Down Expand Up @@ -111,14 +116,6 @@
* Other Features
4.9 Git Daemon
4.10 Hosted Git
* GitHub
* Setting Up a User Account
* Creating a New Repository
* Importing from Subversion
* Adding Collaborators
* Your Project
* Forking Projects
* GitHub Summary
4.11 Summary

5. Distributed Git
Expand Down Expand Up @@ -151,6 +148,14 @@
5.4 Summary

6. Git Tools
6.X Reset Demystified
* The Three Trees
* The Workflow
* The Role of Reset
* Reset With a Path
* A Fun Example
* Check It Out
* Summary
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I really think this whole section should go at the end of the Basic Git chapter. 'reset' is not an obscure Git command, even if it's not well understood. I think it's really powerful and should be part of basic knowledge if we can explain it well. This chapter I think is better as a skippable chapter - a shotgun approach of other stuff you can optionally do with the tool.

6.1 Revision Selection
* Single Revisions
* Short SHA
Expand Down Expand Up @@ -188,6 +193,15 @@
* Superprojects
* Issues with Submodules
6.7 Subtree Merging
6.X Notes
6.X Bundle
6.X Searching
* git grep
6.X Graphical Tools
* gitk/git gui
* GitHub for Windows/Mac
* Others?
* IDE Integration (VS, Eclipse)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think all of this is good, though we may want Searching to go earlier in the chapter - maybe after Stashing? I would sort of like this chapter to go more in order of what is most commonly used.

For the GUI stuff, we may want to a separate chapter after "Git and Other Systems" - something like "Git in Other Environments" perhaps. Where the sections are like "Git in Visual Studio", "Git in Eclipse", "Git and Powershell", something going over the Bash extension, etc.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooooh, I like that. It ties all this stuff together much better.

6.8 Summary

7. Customizing Git
Expand Down Expand Up @@ -251,11 +265,48 @@
* Deleting References
9.6 Transfer Protocols
* The Dumb Protocol
* The Smart Protocol
* The Smart Protocol (include HTTP/S)
* Uploading Data
* Downloading Data
* Credential Caching
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we need a thing here - the mechanics of the cred stuff are pretty simple. I do think it would be cool to add this under "Ch8 Git and Other Systems" maybe - like a section on how to write your own credential cache?

9.7 Maintenance and Data Recovery
* Maintenance
* Data Recovery
* Removing Objects
9.X History Hacks
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think maybe this section belongs better in Chapter 6 with the rest of the cool but rarely used tools.

* Grafts (maybe? this is deprecated)
* Replace
* Shallow
9.X Environment Variables
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 - I think here is probably a good place for this.

9.8 Summary

10. GitHub
10.1 Setting Up a User Account
10.2 Projects
* Creating a repository
* Adding collaborators
* Your Project
* Forking
10.3 GitHub Flow
10.4 Discussions
* PR/issue/discussion
* Markdown
* Notifications
* Email
* Mentions (issue/person/team)
10.5 Organizations
* Teams
10.6 Enterprise
10.7 Tips & Tricks
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably add some search/command bar tips. We also probably don't want to mention Enterprise and stick to what's freely available.

* Importing
* Subversion Interop
* hub or gh
* pull-request refs
* keyboard shortcuts
* ignore whitespace
* rev-parse specs
* commits by author
* .diff and .patch
* Line linking
10.8 The API
10.9 Summary
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great, but I think this whole chapter should go between chapters 5 and 6. After a description of how mailing list teams do it and before random tools. Chapter 5 will provide better context as to why we did some of the things we did and Chapter 6 is most likely where people really start to fall off.