Github - workflow?

prof_braino

Hi all

I don't know if this has been covered yet, I still have not gotten used to the new forums, so I will just ask.

Do we have example of "best practice" workflow for using git and github?

There are many ways to do things using git and github, and some are better than others. Many of the commands are not straight forward (for example we add a new file using the "git add" command, a but we also update file changes with "git add". We create branch by doing "git commit". We make a pull request by doing a push.). Many of us don't know what the heck we are doing in the first place when it comes to git and github.

Yes, the ProGit book https://progit.org/ is great and all, but there are too many options, most of which we can't use or understand until we have enough experience. The online open university classes did a great job of confusing the hell out of me. Sometimes I need to just ask actual people, I guess.

So how do you do what you do when you are successfully sharing code across many developers? I think there should be a sequence of like 6 commands that we use to get started, and then work our way into all the dark secrets of the git pro book as they present themselves.

I'm trying to write n00b level instructions for propforth on github (for me to use), I think I must be re-inventing the wheel.

So, for example, what's the preferred workflow for contributing to the PropellerIDE project on github?

edit 20151108 This is what I found:

* Join the project

git clone https://github.com/aproject/aproject.git
cd aproject/

* See the branches

git branch
git branch -v

* Start from the 'dev' branch

git checkout dev

* make a branch for your task

git branch YYYYMMDD_topic 
git checkout YYYYMMDD_topic 
git log

* sync with team at the start of each day

git fetch 
git pull --all
git status

* Add your changes from today

git add .
git status
git commit -m "what I did" 

* share your changes with everybody, requires a git userid

git push -u --all
git status

Buck Rogers

Well I find it practically interesting that they are almost giving away the entire book. That accounts for something.

Now as to your questions, I'm not sure there's an easy answer or two or three.

Heater.

I think the best place to start is to get your self a github and/or bitbucket account to play with.

Both github and bitbucket have very nice tutorials written for those who want to get stuff done and not spend ages wading through the billions of git commands and options. Very nice.

"git add" is a confusing thing initially. But really adding a new file or adding a change to a file are the same thing, they are both adding a change. Only the first change is to a non-existent file as far as git is concerned. Those changes can be committed or backed out if you change your mind.

We create a branch, in our local repository with "git branch branchName" and "git checkout branchName". Or "git checkout -b branchName" for short. Of course you may well want to commit your branch at some point, or even push it back to your repo on github or bitbucket.

Remember that git is a distributed system. Every developer has his own complete clone of the project repo. Whilst it's nice to make branches in your own repo whilst working on a feature I suspect most people don't want dozens of branches making there way to the upstream repo.

Nothing makes it's way to the main upstream project repo, not even if you commit changes, until you do a push.

As you say how you work with git depends a lot on the nature of the project, the work going on, the number of developers etc, etc,

Buck Rogers

Heater. wrote: »

I think the best place to start is to get your self a github and/or bitbucket account to play with.

Both github and bitbucket have very nice tutorials written for those who want to get stuff done and not spend ages wading through the billions of git commands and options. Very nice.

"git add" is a confusing thing initially. But really adding a new file or adding a change to a file are the same thing, they are both adding a change. Only the first change is to a non-existent file as far as git is concerned. Those changes can be committed or backed out if you change your mind.

We create a branch, in our local repository with "git branch branchName" and "git checkout branchName". Or "git checkout -b branchName" for short. Of course you may well want to commit your branch at some point, or even push it back to your repo on github or bitbucket.

Remember that git is a distributed system. Every developer has his own complete clone of the project repo. Whilst it's nice to make branches in your own repo whilst working on a feature I suspect most people don't want dozens of branches making there way to the upstream repo.

Nothing makes it's way to the main upstream project repo, not even if you commit changes, until you do a push.

As you say how you work with git depends a lot on the nature of the project, the work going on, the number of developers etc, etc,

That will work. I got my start with GitHub in much the same fashion. I now have some work parked on it, But not under the user name used here. Same e-mail address though.

I find it interesting that the entire site of theirs is parked on Amazon Web Services. And that they produce some darned interesting sheets explaining some of the more esoteric commands for Git.

I have to admit that the way you explained the way Git works is perfect.

But what does this have to do with one of erco's robots standing outside in the early snow and looking in at you?

Heater.

I recently started working with bitbucket. Under pressure from work, the team out voted me when they wanted more private repos which turn out to be cheaper on github. Anyway bitbucket works very nicely as well and their git instructions looked very good.

There are a lot of start-ups and not so start-ups operating on AWS for a long time now. It's so damn convenient to spin up more servers when you want them. Of course if the business grows, like github, you just spin up more and more... Then there is Google cloud and others that are cheaper in some situations.

My 2π.net is on AWS. Free for a year so had to be done.

prof_braino

I started making a minimum list of git instruction so I can consistently contribute to the propforth github project (without git errors).

I think my confusion comes from the "one stop" command that combine two commands, when I don't understand the two commands individually. Thanks heater, I will sort through this again and do the individual command as a first principles before I do the combined commands.

I will be interested to compare this with the way the propellerIDE project flow works.

For example, do folks use the staging (scratch?) area often? It seems to me the staging area might be useful in some situations, but is unnecessary for most work. So far the staging area has been only a source of confusion.

Heater.

Depends.

Round here we only have a few guys working on any particular project. They keep their own repos locally for their own development and testing. Mostly they are trusted not to push broken code into the production servers.

Bigger teams and projects will have individual developer repos, they will push (or get pulled, into testing repos where the QA guys get to test and break the code. From there it gets pushed to the live servers.

Others get into maintaining branches on the upstream repo and then messing around merging branches into main line. All seems a bit complex to me.

Do remember to tag everything that works and/or is released.

Main point is that git is a distributed system. All project repos are equal. In a way a repo is a branch. It will needing merging at some point with the same hassles that involves. At least if development happens in separate repos the main repo's history does not get filled up with old experimental Smile.

prof_braino

OK, I think I have it figured out. I think this is the minimum we need to have a consistent common workflow using git and github.
I guestimate that this is the minimum set of commands and explanation to get a newcomer started.
Comments welcome. Thanks in advance!

Clone- anybody that wants touse the source code should clone therepository

git clone [ulr]

Fork - nobody should fork the repository, unless they want to go in a differnet direction.
Anybody who fork has to manage the code on their own as a separate project.

Branch - everybody that wants to contribute should create their own branch,
from either the MASTER or DEV branches of the main repository.
The branch should be named for the function being developed perhaps

git branch YYMMDD_BrainoSetupDocumentation

checkout - this point us at the branch we want.
git checkout YYMMDD_BrainoSetupDocumentation
would point me as my branch,

git checkout DEV

would point me back at the development branch. Actually, before we create our own branch, we want to select the starting branch, if we want to start from DEV instead of MASTER.

"create-branch" and "check-out" are often combined into a single command, to make the documentation more confusing to newcomers

git checkout -b "YYMMDD_BrainoSetupDocumentation"

add - after I create or change files, I want to add them bach to the branch

git add .

would update all my changes back to the branch; add seems to be a most unfortunate choice of name, as update seems to be what its doing.

commit - this writes the changes I added to my branch. WE put a text label to say what we did

git commit -m "updates to the readme file"

"add" and "commit" are often combined into a single command to trip up anyone that made it past create-branch + checkout

git commit -a -m "updates to the readme file"

is the combined form

At this point we have our contributions recorded on the local repository. Now we want to send these up to our peers. We do what is called pull request. Its called pull request, but is actually a push, and is named to catch anyone that might have made it past the previous two traps.

git push -u --all

---At this opoint we are done for the day.---

Each time we START a new session, we want to check if anybody sent up changes. We want to deal with those changes sooner rather than later, so we start by checking now

status - we want to check sttatus often until we become comfortale with the workflow

git status

logs - we want to check the logs to see when we and other folks made contributions. This can help us if something start acting funny, we can use this log entries to hunt down when something has changed (For example using a binary search, etc)

git log

We exit the scrollable log listing with the leetter "q".

fetch - to actually get other folks changes, we use fetchto get the list of things changed

git fetch

pull - after we have fetched the list of changes, pull brings the actual changes to my machine

git pull --all

-- at this point we are ready to continue coding --

Notice the TWO dashes in from of the --all modifier for push and pull.

OK, did I miss anything? Thanks in advance.

prof_braino

I wonder how many "regular folks" use git? Perhaps this is a "developer only" class of tool, and is only used by folks that already use it for professional projects?

SRLM

Git isn't restricted to developers only, but it certainly addresses the complexity that larger projects have and smaller projects do not.

Heater.

prof_braino,

I have a slightly different take on my day to day git work flow. Let's assume a one man project, me hacking on my code which is in github or bitbucket:

1) Get the code onto my PC:

$ git clone https://bitbucket.org/zicog/propanel.git 

2) Edit a bunch of files. Let's say some edits are for a bug fix, some are for a new feature. So I edit the files and test the code on my machine.

3) After a while I want to stop for the day and get my changes back to github/bitbucket:

I can review my changes:

$ git status 
$ git diff someFile 

At this point I may want to clean up some comments, adjust formatting, make final tweaks, retest. I may want to throw away some work if it does not look good. Just checkout the original file(s)

$ git checkout someFile

4) When all is ship shape it's time to commit the changes:

$ git add someFile
$ git commit -m "Fix horrible crashing bug"
$ git add someOtherFile
$ git commit -m "Added awesome feature"

Notice there are two adds and two commits there? That's because I was working on two things at the same time. It's nice to have separate commit messages in the log. One could add all the files at once and do one commit but that mixes things up in the history.

5) At this point I have my bug fix and awesome feature in my local clone of the projects repo. What can we do next? The github repo is unchanged so far. Obviously if I'm happy with the work I want to get it back up to github/bitbucket:

$ git push

There we are done.

But what if I leave it for a day and come back realizing I did all that work the wrong way and I have a better idea. Now I want to throw away my local commits and start over. No problem, first let's see where we want to go back to:

$ git log
commit d85be6f3bc83950a7029d29499c797649d9c5de8
Author: zicog <michael@debian>
Date:   Thu Nov 12 07:19:05 2015 +0200

    Sign now displays success/fail response

commit 18475b41b98f3b4a3862ad19b283d19069ffd647
Author: zicog <ec2-user@ip-172-31-18-148.eu-west-1.compute.internal>
Date:   Wed Nov 11 10:46:21 2015 -0500

    Minor tweaks :)
...
...

Then throw away the recent work:

git reset --hard 18475b41

That will dispose of all the commits after the given commit hash (Note: you don't need to type the whole hash)

Now I can go round the loop again from step 2)

So there we have it. That's pretty much all of git that I use most of the time. In summary:

$ git clone
$ git status
$ git diff
$ git add
$ git commit
$ git pull
$ git push
$ git log

One more thing:

What if I now go to a different machine, and want to continue work on my project? And what if that machine already has a clone of the repo on it? Rather than doing a "git clone" to get started I just do a "git pull" to synch up the local copy with the latest on github. In this way I jump from machine to machine, home, office, cloud server, just pulling and pushing from where ever I am.

Heater.

prof_braino,

About git forking and branching.

Fork - nobody should fork the repository, unless they want to go in a differnet direction.
Anybody who fork has to manage the code on their own as a separate project.

Yes and no.

A fork need not be a major change in direction. Let's say I want to contribute to your project? I could ask you for push access to your repo but you may not want to do that. I could clone your repo to my PC, make the changes then send you some patches in the mail. That's hard work. What do I do?

Well, I fork your project on github. I then clone it to my PC. Work on it, make my changes and push them back to my repo fork. Then I send you a pull request. Now you can totally ignore that request. Or you can review what I have done and pull my changes into your code if you like it.

When I'm done with fixing your bugs I might delete my fork altogether.

Of course most of the time one need not worry about fork when working on your own code.

Branch - everybody that wants to contribute should create their own branch,

I don't agree with this. Branches are a complication one can live without a lot of the time.

When you clone a repo you have effectively created a branch. You can commit changes to it and it is now wondering off in a direction of it's own that the upstream repo knows nothing about. When you push your commits you are merging your branch on your PC with the main line on the upstream repo.

The last thing we want is for the upstream repo to be cluttered with lot's of branches from many different developers.

When do I want a branch?

Let's say I clone a repo and I want to add a new feature, developing that feature is going to take some time. Let's say I also may have to do some quick bug fixes on the main line code. I really don't want to get into a mess mixing up new feature changes with bug fixes changes and breaking everything. What to do?

1) Clone the repo, or pull it if I have it already.

2) Create a branch for the new feature:

$ git branch awsomeFeature
$ git branch -a
  awsomeFeature
  gulp_build
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/gulp_build
  remotes/origin/master

3) Move to that branch:

$ git checkout awsomeFeature  
M       app/auth.jsx
Switched to branch 'awsomeFeature'

4) Start developing the feature, add, commit etc etc.

5) Now I have a bug to fix in the master branch. Just move to master

$ git checkout master
M       app/auth.jsx
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.

Fix the bug. git add, commit, etc etc and push it back up stream.

6) Get back to working on the feature:

$ git checkout awsomeFeature  
M       app/auth.jsx
Switched to branch 'awsomeFeature'

7) When the awesome feature is complete I want to merge it's changes into the master:

$ git checkout master  
$ git merge awsomeFeature

Then I can push from my local master to the upstream master to get the new feature up there. The newFeature branch never shows up in the main repo.

Of course a may also create a branch for the bug fix. I might have many branches, one per feature, bug fix or whatever task in hand. The upstream repo need never know anything of the chaos I have locally

Of course, on a large project you may have more than one person working on a new feature, in which case it might make sense to create awsomeFeature branch on the upstream repo for then to collaborate on.

mindrobots

Great writeup of the workflow, Heater! I'm saving this one - I use git on and off but often forget the details.

I think it helps seeing all the steps tied together and how you really use it day to day.

Thanks!

Heater.

Thanks, mindrobots.

I like to keep things as simple as possible.

Publison

+1 for the great writeup. I understand it a lot better now.

78rpm

++1 from me. I think this will be very useful. Thank you, Heater.