Skip to content
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.

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

Staging process chart used to show "state" #522

Open
alexanderzimmerman opened this issue May 13, 2018 · 11 comments
Open

Staging process chart used to show "state" #522

alexanderzimmerman opened this issue May 13, 2018 · 11 comments

Comments

@alexanderzimmerman
Copy link
Contributor

@alexanderzimmerman alexanderzimmerman commented May 13, 2018

This lesson introduces a nice chart showing the staging and committing process:
image

But then in a later lesson, a similar chart is used to show the "state" of a repo:
image
This is done again in the next lesson.

I fail to understand how this chart explains the state of a repository, and I don't see where this has been explained. Why do we have all of this information about the staging process in these places? I'm personally confused and distracted by it, and I imagine the learner might be as well. Is it just me?

@iglpdc
Copy link
Contributor

@iglpdc iglpdc commented May 13, 2018

Thanks, @alexanderzimmerman ! I think the idea is to explain a couple of different things without introduce too many (or very different) graphics that add extra load.

The first graph tries to explain the stage area as a separate and previous "place" to store your changes. The stage area is one of the hardest things to understand in the lesson.

The second plot explains how the git push syncs the local and remote repos. The remote repo has no staging area and you can only add changes by pushing, instead of add/commit. There is a previous graph which shows the remote repo "empty" after creation.

I think one improvement could be to add short versions of the commit ids into the cylindrical chucks that picture the repo database. In this way, the meaning of push as sync of the remote and local repos could be stressed.

I think that removing the stage area from the local repo (is this what you are suggesting?) would be detrimental, in the sense that despite being maybe more accurate, learners may fail to recognize the local repo in the new graph.

@alexanderzimmerman
Copy link
Contributor Author

@alexanderzimmerman alexanderzimmerman commented May 15, 2018

It seems we agree about not wanting to add extra load; but we have different perspectives on what adds cognitive load here.

I would argue that this graphic shows too much extraneous information. I wouldn't assume that the learner has mastered the staging area concept and is perfectly comfortable with this staging area chart.

So for this lesson, I think we would just have a picture of a .git repo box with some files in it which represents the "state", since we don't care about the state of the staging area.

Since I'm still learning plenty of this as well: Is it true that the remote repo doesn't have a staging area, or do we just not interact with it? I think this would contradict what we teach earlier in the episode:
image

Thanks for thinking through this with me; and I apologize for the barrage of issues and comments that have come from me digging into this lesson for the first time :)

@alexanderzimmerman
Copy link
Contributor Author

@alexanderzimmerman alexanderzimmerman commented May 15, 2018

Also, about side-effects of removing the staging area from the graphics in this episode: I think it would be quite clear if we just labeled the boxes "local" and "remote", and perhaps also keep the local path and web address (already in the graphic) next to that.

@munkm
Copy link
Member

@munkm munkm commented May 15, 2018

I agree that the local path and remote URL should be kept to show the address of each repo on the systems that students might interact with.

I also agree that adding commit IDs to the stack would be a helpful addition to the graphic. When I teach the .git lesson, I generally do this on a whiteboard and I find it helpful.

Remote repositories do differ in behavior from local copies. There isn't a "working directory", nor is there a "staging area". The way that one interacts with a remote is different than with a local repo. As mentioned above, the graphic of the remote does attempt to show that visually by showing the stack of commits without having a working directory or staging area. I think we could clarify this by adding some descriptions around the graphics in lesson 07 when remotes are introduced. In this way we could reinforce the differences between using/interacting with remotes and how a remote and local repo differ for both visual and auditory learners.

I believe that the series of directions including mkdir planets, cd planets, and git init are fairly close to what happens on github. However, if I were to set up a remote repository on my own, I'd initialize it with git init --bare.

I should note that what I've described is a generic description for any type of remote (on a personal server, for example). Github is a little different because a user can still interact, commit, and edit files on github through the browser (so it might feel like there's a working directory). Github just happens to be the service we've chosen for remotes, so I think keeping the description of remotes as git-centric and not github focused is worthwhile, considering a learner may be working with a different type of remote in the future.

Removing the "stack" of commits that exist in these graphics and replacing them with only a current state of a directory could also be misleading to a learner. This might imply that only the most current working state is stored on a remote, which isn't true.

@iglpdc
Copy link
Contributor

@iglpdc iglpdc commented May 15, 2018

Since I'm still learning plenty of this as well: Is it true that the remote repo doesn't have a staging area, or do we just not interact with it? I think this would contradict what we teach earlier in the episode:
image

Yes, the repos on Github are different from "regular" local repos. They are called "bare" repos and are created with git init --bare. The main difference is that they do not have a staging area, only the .gitfolder (which is not actually named .git, but that's a detail).

So basically, you can add/commit to a regular repo, but not pull/push/clone. And, conversely, you can push/pull/clone to a bare repo, but not add/commit.

You can always create a bare repo with git init --bare, even in your own machine. Then you could add it as a remote for a local repo as we do in the lesson and push and pull there. This could be useful in case you don't want to put your files in someone else's computers (say for a project with sensitive information) or when you don't have access to the internet.

You could read more about it here.

In the image you showed, we are cheating a bit. The git init should be git init --bare to be technically correct, but I think skipping the bare flag allows us to not have to discuss the difference.

Thanks for thinking through this with me; and I apologize for the barrage of issues and comments that have come from me digging into this lesson for the first time :)

No worries! It's great to have new people joining and helping to make lesson stronger.

@munkm
Copy link
Member

@munkm munkm commented May 15, 2018

Ha! I guess we were writing at the same time @iglpdc

@alexanderzimmerman
Copy link
Contributor Author

@alexanderzimmerman alexanderzimmerman commented May 15, 2018

Okay this is all very enlightening.

As demonstrated by my own confusion, I don't think that this graphic makes sense without explaining the "--bare" difference. But if you've been using the graphic for other learners and they've found it understandable, then maybe I'm in a niche situation.

@iglpdc
Copy link
Contributor

@iglpdc iglpdc commented May 15, 2018

Ha! I guess we were writing at the same time @iglpdc

Yes, that's funnny!

@aragilar
Copy link
Contributor

@aragilar aragilar commented May 16, 2018

Suggestion: show the first graphic again (the local only version), and refer back to lesson 4, and then emphasise that it's just a single repository, and that's it's going to be our representation for our local system, and then introduce the second image with a remote. It may also be useful to have a third image which has a second local repository to repeat this representation of a local repository (and to explain how collaboration works).

Aside: it's entirely possible to push/pull/clone from none-bare repositories (see https://glyph.twistedmatrix.com/2014/09/actually-distributed.html for how to set this up), and to manipulate bare repositories as if they were not. This is used in a number of tools (e.g. git-annex, vcsh). Bare repositories are a consequence of git's branching model (it's really instructive to compare git's model to mercurial's, as mercurial does not have bare repositories). Obviously this is not something we should be covering in git-novice, but it is something worth understanding (if only from a "when you make a decision how to design something, there may be consequences" perspective).

@munkm
Copy link
Member

@munkm munkm commented May 16, 2018

Hi @aragilar. I'd like to further understand your suggestions, so I'm going to ask a few questions.

In lesson 07 we have two different graphics for the local + remote setup. Early in the lesson we show the local repo and an empty remote pre-pushing. Later in the lesson after git push is used we have a graphic with the remote containing the same full commit stack reflecting the local repo. Are you suggesting adding the graphic from lesson 04 before both of these graphics, or do you feel a verbal highlight of the local vs. remote at the introduction of what is now the first image (full local copy w/ version control history and an empty remote) is sufficient from the instructor?

In lesson 08 there is a graphic with two local copies reflecting wolfman cloning vlad's remote repository. Is this the type of graphic you're suggesting? Or were you thinking of something else?

@aragilar
Copy link
Contributor

@aragilar aragilar commented May 16, 2018

My suggestion for lesson 7 is to use the original image without modifications, i.e. https://swcarpentry.github.io/git-novice/fig/git-freshly-made-github-repo.svg has the github repository, we should have the original one just before it, and mention that this is the same image as before to try to contextualise the second image.

For lesson 8, the boxes appear to have had their "indentation" moved (so the github repo moves out, and the local ones move in). Having the local repos have one "indentation" always, and the remote have another may help with building up a more clear division (but this was the kind of image I was thinking of, though I'd use it to show push/pull, in addition to the clone image).

I'll try to come up with a PR showing what I mean for the first part tonight.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.