#39

There’s an old document called git from the bottom up that helped me. It requires an understanding of a cryptographic hash but not much else.

Here’s a good cheat sheet I keep on my desk.

#42

FWIW, the same drop down can show tags

I can’t agree with this more. I’ve slowly weaned myself off of it and onto the CLI (of necessity), but IMO Gitkraken is the best visual representation/tool I’ve found (and I’ve looked at a lot). I still use it when I a) need a visual representation of the whole history, and b) need to quickly jump around to different files/commits; there’s simply no way a CLI can match this.
EDIT: I feel like I should mention that Gitkraken runs equally well on all modern platforms (well, not iOS or Android, but you know what I mean :wink: )

Shameless plug; I have a cheat sheet of my own - "git Beyond The Basics, or What You Need To Know To REALLY Fuck Things Up"
It’s a bit random, and applies to what I need to remember for day-to-day work, but it captures some of the things I really wish someone had told me just after I learned the basics.
PRs, issues, comments (and CORRECTIONS, for sure!) are all welcome (the irony/recursive nature of that statement is not lost on me :slight_smile: ).

3 Likes
#43

This is great.

#44

One question - is it best practice to create branches in your own fork or on the master?

1 Like
#45

From a best practice perspective, It tends to makes more sense when the branch is done on someone’s fork as opposed to the main repo. It helps keep the branches clean on the main repo (you don’t have to scroll through a list of a bunch of stale branches that were never cleaned up and deleted). Typically master and release branches are done at the main repo level.

That being said, if you have a branch that you want a bunch of people to directly commit to (and not have to open PRs to contribute), it can make sense to put in a main repo.

The monome projects as far as I’ve seen follow the branch-from-personal-fork method for most contributions.

#46

Unless you’re part of the team that owns a repo (or added as a collaborator) you can’t create branches in that repo.

In other words the default/normal workflow for non-team members is to create a fork and work from there.
If you want to create branches or not for work you do in your fork is your own choice of course :slight_smile:
I’d suggest to use branches, makes it a bit easier to understand the history if looking at it via for example the command-line or with something like tig or when looking a GitHub’s “network” graph (for example https://github.com/monome/norns/network).

#47

Ok, great, then just checking does the command in these instructions

  • git checkout upstream/master -b name_of_your_branch

…create a new branch in the master or the fork?

#49

git checkout -b newbranch will create a new branch in the repository you’re currently in. if it’s a fork it’ll create a branch in that fork.

this specific command implies it’s a fork, as it uses upstream/master as the starting point. when you fork a repo you typically set up a remote named upstream for the original repo (a remote named origin will be automatically set up for your fork when you clone it).

2 Likes
#50

OK, great, this is really helpful. Thank you.

1 Like
#51

I made a pull request for the monome/dust repo. Here’s my workflow on a Norns and my computer.

  • Fork repo into my personal account
  • Clone fork onto my computer
  • Create branch based on master for a new thing, named after new thing
  • Add upstream as a new origin to stay in sync with master
  • change the repo on the Norns to track my fork
  • Push Changes to my fork as I’m working, Norns can stay in sync
  • Edits made through Maiden (the Norns IDE) get diffs on device

When I got to a place where my fork + branch is ready, make a PR using Github’s interface. It assumes reasonable defaults and even displays a green button to make a PR.

I think it’s good etiquette to write pull requests with as much information as possible because reading diffs is a special skill. Describe the new features. Don’t describe anything not in the changes, even if the feature in mind is obvious. Future PRs can cover that.

update: another thing I forgot…delete branches when they are merged into master. If you want to do a new thing, even if it’s for the same kind of thing, make a new branch with a new name about only that new thing.

I’m borrowing these conventions from my professional work as a software developer, though with niche software like Monome the rules are more flexible.

5 Likes
#52

This might be useful to some: github released a training platform to learn how to use git/github.

#53

Along with the other replies here, there is also the question of force pushing (a.k.a. history rewriting) and the surrounding etiquette.

While there are no hard and fast rules, I’ve found that in circumstances where a branch is seen as being your own private branch (that just so happens to be in public on GitHub) then force pushing is fine, and even required when tidying up work prior to a PR being accepted.

Whereas in branches that are seen as collaborative and public then force pushing is a no-no.

For most projects this usually means that branches on the main repo are never force pushed to, but that it’s okay to do it on your own forks.

3 Likes
#54

OK, so as requested, a short github intro:

Let me know if (a) it’s helpful, (b) it’s not. If (b), then let me know what’s not clear, and I’ll try to see if I can clarify. Another option I might consider is doing a tutorial session over skype which might shorten the feedback loop. I’ve disabled comments to keep that thread here, and the video isn’t publicly listed.

12 Likes
Crow & end-user documentation
#55

LEGEND!!! Thank you so much. Will be digging in tonight.

1 Like
#56

Thanks for the lesson!

Did I understand it right, that you also need a github software on your computer to do all those things you did in the black text window with the git commands? Like downloading a clone of the repository, making changes to it and pushing it back to your account?

#57

This is a Terminal window. Terminal is an application on MacOS which gives you command line “terminal” to interact with the computer (Old-school UNIX, DOS, etc. use a command line interface).

(not sure what specific application people use for command line on Windows)

No - you can interact with everything from Terminal.

#58

If on Windows, I think you need to install git. It’s not included in the OS.

#59

Okay, I hardly ever use this - and when I don’t know what I am doing but only fulfill orders fron the internet. I think for windows it was the DOS window, which I used a bit back in the nineties. So when you type git clone or push in the terminal your Mac executes that on the GitHub website? Or are those commands part of MacOS?

#60

Ok,so yes, you do need to install either the command line utilities, or a git GUI application. As I mentioned I’m an old school guy so I prefer the command line tools, but the same can be achieved with the GUI.

The commands are run locally on your computer communicating the changes back to the github servers.

Thanks for the feedback, it sounds like I should try to take a step back and explain how to install the tools.

2 Likes
#61
mod action

moved GitHub-specific posts from @GoneCaving, @gnome666, @Leverkusen, @okyeron, @EqualTemperament ; Crow & end-user documentation -> here.

also deleted @okyeron’s call for the mod action to keep things clean.

3 Likes