Source code management using GitHub

This is an archive of a topic from NESdev BBS, taken in mid-October 2019 before a server upgrade.
View original topic
Source code management using GitHub
by on (#158600)
Hi,

I'm planning on putting some of my projects up on GitHub, but -- having very little experience in the field of Git-assisted source code management, myself -- thought it might be a good idea to ask questions first. :)

So far, I've made changes to a project's codebase whenever I spotted something that needed to be changed -- no matter whether it was actually related to my current coding objective or not. But as each single GitHub commit is supposed to reflect one distinct project milestone apparently, what's the best way of keeping track of all the changes to my offline codebase before I even update the online repository? Is there code editing software at all that allows you to "assign" different objectives/milestones to any edit (and/or whenever you save a file)? Or do I have to completely change the way I work, just in order to be "GitHub-compatible"?

Thanks for any GitHub-experienced input! :)
Ramsis
Re: Source code management using GitHub
by on (#158604)
You can split your changes into individual commits offline, before you push them to your main repository. Ordinary git supports this (but good luck figuring it out); GitHub provides a convenient GUI program that can hopefully make it easier.

Or you can be lazy; after all, they're your projects. :lol:
Re: Source code management using GitHub
by on (#158627)
Ramsis wrote:
Hi,

I'm planning on putting some of my projects up on GitHub, but -- having very little experience in the field of Git-assisted source code management, myself -- thought it might be a good idea to ask questions first. :)

So far, I've made changes to a project's codebase whenever I spotted something that needed to be changed -- no matter whether it was actually related to my current coding objective or not. But as each single GitHub commit is supposed to reflect one distinct project milestone apparently, what's the best way of keeping track of all the changes to my offline codebase before I even update the online repository? Is there code editing software at all that allows you to "assign" different objectives/milestones to any edit (and/or whenever you save a file)? Or do I have to completely change the way I work, just in order to be "GitHub-compatible"?

Thanks for any GitHub-experienced input! :)
Ramsis


Each Git commit does not have to reflect milestones in a project. For a large change or addition it is best to create a branch off of your master branch. Inside that branch you should make small commits following the progress of your work, with meaningful logs (code changes can be visualized as diffs, though). When a feature or bugfix branch like that is completed, it's time to merge it into your main branch. The history that went into working on that branch becomes part of your master history.

By completing portions of the project in branches like this, it is easy to allow person X to work on component A while person Y works on component B, each in their own branches, and they may merge their changes in. Git commits are more or less linked lists that describe changes to the previous commit, so it's not hard to imagine how different branches of work can come together.

Git is not GitHub, too. Pushing and pulling from a remote (like GitHub) is in a way synchronizing your local copy of the repository with the remote. You can use Git for version control without ever adding a remote. GitHub is just a large successful business built around providing an easy to use remote for git.
Re: Source code management using GitHub
by on (#158630)
SourceTree (https://www.sourcetreeapp.com/) has pretty good support for splitting changes into different commits. You can select individual files for "staging" (you should find this feature in pretty much every GUI client), and you can even select individual change blocks within a file ("stage hunk").

How fine-grained commits you do is really up to your tastes. Often I try to split small changes into multiple commits if they're completely unrelated, but sometimes (if I'm tired...) I slip them in within a bigger commit. One somewhat annoying part with using "stage hunk", or even commiting individual files, is that you can't test on the spot whether the commit is compilable (maybe it depends on changes from some other file that you left out of the commit by accident, or maybe it simply wasn't possible to pick the relevant changes from the file).
Re: Source code management using GitHub
by on (#158715)
Thanks, this helps a lot already. :)

Actually, I'd like to use GitHub as a remote (i.e., not just Git) so I can both distribute my sourcecode and receive bug reports in one place, along with the additional benefit of a commit history.

mikejmoffitt wrote:
By completing portions of the project in branches like this, it is easy to allow person X to work on component A while person Y works on component B, each in their own branches, and they may merge their changes in. Git commits are more or less linked lists that describe changes to the previous commit, so it's not hard to imagine how different branches of work can come together.

Aaahh, I see ... :idea: (TBH, I had a completely wrong concept of those "branches" up until reading your post, so thank you for your explanation. :D )

Now first of all, I downloaded the Git software. The download site suggested I also get a GUI, of which I chose GitHub, obviously. But do I really need to install both of them? ... Never mind, I already did, and as I suspected, the two software packages seem rather unrelated (i.e., it seems I could have gone with the GitHub software only). So I configured the GitHub software but haven't actually created a repository yet, lest I mess it up on the very first try. :lol:

Is there a way to prevent files from the project directory (like WLA executables or "run-on-higan" BAT files) from appearing in the repository at all? Also, assuming I create a branch, and there are project files I need to edit both in the branch and in the master tree, where/how does the software store these files? IOW, how do I determine which file I'm editing? (Currently, I'm using Programmer's Notepad with static PPG project files.)

Thanks again!
Re: Source code management using GitHub
by on (#158717)
Ramsis wrote:
, of which I chose GitHub, obviously.

This is not "obvious", because you're not forced to use the GitHub client with GitHub. You can use any other GUI client just as well, or simply "git" from command line.

Quote:
Is there a way to prevent files from the project directory (like WLA executables or "run-on-higan" BAT files) from appearing in the repository at all? Also, assuming I create a branch, and there are project files I need to edit both in the branch and in the master tree, where/how does the software store these files? IOW, how do I determine which file I'm editing? (Currently, I'm using Programmer's Notepad with static PPG project files.)

Check out ".gitignore". It's a file you can use to make git ignore certain files (with wildcards). Branches (and the repository contents in general, e.g. change history and so on) are stored in the ".git" directory (it's a hidden file in the root of your local repository copy). When you want to edit a specific branch, you have to specifically switch to it. On command line this is done with "git checkout", not sure how to do it in the GitHub client.
Re: Source code management using GitHub
by on (#158720)
thefox wrote:
Ramsis wrote:
, of which I chose GitHub, obviously.

This is not "obvious", because you're not forced to use the GitHub client with GitHub. You can use any other GUI client just as well, or simply "git" from command line.

It's obvious to me as a Git(Hub) newbie. Why on earth should I even consider entering my GitHub credentials in some non-GitHub-program, with a GitHub program existing in the first place? :?: It's as though you'd recommend a Windows newbie to use ReactOS in order to run Notepad. :lol:

thefox wrote:
Check out ".gitignore". It's a file you can use to make git ignore certain files (with wildcards).

But isn't .gitignore meant to stop Git from tracking files? I want files not only not to be tracked but to be excluded from the repository altogether. Also, I don't want a list of those files in my remote repository, so this doesn't seem to be an option.

thefox wrote:
Branches (and the repository contents in general, e.g. change history and so on) are stored in the ".git" directory (it's a hidden file in the root of your local repository copy). When you want to edit a specific branch, you have to specifically switch to it.

Ugh, that isn't exactly practical ... :|
Re: Source code management using GitHub
by on (#158723)
Ramsis wrote:
thefox wrote:
Ramsis wrote:
, of which I chose GitHub, obviously.

This is not "obvious", because you're not forced to use the GitHub client with GitHub. You can use any other GUI client just as well, or simply "git" from command line.

It's obvious to me as a Git(Hub) newbie. Why on earth should I even consider entering my GitHub credentials in some non-GitHub-program, with a GitHub program existing in the first place? :?: It's as though you'd recommend a Windows newbie to use ReactOS in order to run Notepad. :lol:

I said that because based on your earlier comments I wasn't sure that you understood the division between "git" and "GitHub" (and the many other sites that provide git repository hosting).

Quote:
thefox wrote:
Check out ".gitignore". It's a file you can use to make git ignore certain files (with wildcards).

But isn't .gitignore meant to stop Git from tracking files? I want files not only not to be tracked but to be excluded from the repository altogether. Also, I don't want a list of those files in my remote repository, so this doesn't seem to be an option.

"Not tracking" means that git will not notify you about any changes to the files, nor will it bother you about those files not being added to the repository. So that's basically the same as "excluding from the repository". Also note that the working directory (the one with the unnecessary files) is not the same thing as the repository itself (which is in the .git directory).
Re: Source code management using GitHub
by on (#158725)
Ramsis wrote:
Why on earth should I even consider entering my GitHub credentials in some non-GitHub-program, with a GitHub program existing in the first place?

For the same reason that an e-mail service provider may offer its own customized mail client while allowing access from any IMAP client. Or Google Talk and other XMPP clients before Google replaced it with Hangouts to counter spam.
Re: Source code management using GitHub
by on (#158727)
tepples wrote:
Ramsis wrote:
Why on earth should I even consider entering my GitHub credentials in some non-GitHub-program, with a GitHub program existing in the first place?

For the same reason that an e-mail service provider may offer its own customized mail client while allowing access from any IMAP client. Or Google Talk and other XMPP clients before Google replaced it with Hangouts to counter spam.

Well, I don't use either of those, so why clutter up this thread with it? :roll:

But never mind, guys. I've come to the conclusion that Git(Hub) is not the way to go for now. :D
Re: Source code management using GitHub
by on (#158730)
Ramsis wrote:
tepples wrote:
Ramsis wrote:
Why on earth should I even consider entering my GitHub credentials in some non-GitHub-program, with a GitHub program existing in the first place?

For the same reason that an e-mail service provider may offer its own customized mail client while allowing access from any IMAP client. Or Google Talk and other XMPP clients before Google replaced it with Hangouts to counter spam.

Well, I don't use either of those, so why clutter up this thread with it? :roll:

It was an analogy to help you understand the concept of both providing your own branded client and allowing use of third-party clients, in case you did use either of those.
Re: Source code management using GitHub
by on (#158738)
I just want to write it really big in case it's potentially not clear:

git != github

Git is a program, and GitHub provides remote storage for git repos. The GitHub program and SourceTree are front-end GUI programs that manipulate Git. Git is the command-line tool itself. By installing one of the former two, you will have Git installed in some way or another. I got started using the GitHub GUI program and moved to the command line shortly afterwards. As tepples illustrated, git is filling a role closer to a service standard than a service itself, and entering credentials into one client is no different than entering them into another. The GitHub program just happens to be a client that was created by the same service you're connecting to.

Entering your GitHub credentials in the normal Git client is not only fine, but it's also what the GUI is going to be doing anyway*.

*The GUI likely will allow you to use an SSH key to make this credential business unnecessary, but again, that's the GUI abstracting away something that the Git client is doing normally.
Re: Source code management using GitHub
by on (#158763)
Instead of shying away completely by git – it can be a bit overwhelming at first – I suggest you try a basic local workflow first. Branches and remotes (ie. github) can come later.

Make a copy of a local project directory and add it to a git UI client. SourceTree is a good pick, and it's not tied to a particular remote service. I use it almost exclusively. Since it seems important for you to exclude certain files, make some ignore rules before even making the initial local commit.

Then as you edit files, any changes made will show up in the "file status" and "log" views in SourceTree (I'm usually in the "log view" since it shows both the uncommited local changes ("working copy") and the commit history at once). Changed files can be "staged" (which means they are include when you next do a commit) or reset to the last (or any other) commit. So, as you code along and feel that you've done something meaningful, stage the changes and commit them. In the commit message you describe what the changes accomplished.

Just doing this I think you will soon realize the value of having an easily accessible history of your projects. Reverting certain files to certain points back in the history is super simple. As is viewing a log of all changes made to a specific file since the project was started.

By the way, since you asked how to make an edit to a file in all branches... To understand why that's not something you can (or want) to do you need to know a bit on how git manages all this magic. Basically, the git database resides in the ".git" directory in the root directory of the project. All other files is called the "working copy". When you check out another branch, the entire working copy is swapped out (via diffing, the branches are not stored with the full file contents – the history a tree structure of diffs). Any commits is then done to that branch. To propagate the changes to another branch (say, the master branch) you first switch to (ie. check out) that branch, then merge the changes from whatever branch you just worked on.

Anyway, try it, you'll probably come to like it!
Re: Source code management using GitHub
by on (#158779)
Thank you all. :)

So I switched to SourceTree, and after some time of playing around with it, I can only admit that it appears to be a very powerful piece of software. :D

Here's my first remote repository (SNES PowerPak firmware, initial commit = first v3.00 "MUFASA" release):
https://github.com/Ramsis-SNES/snes-powerpak-firmware-v3