I'm publishing a tutorial that includes a lot of code interspersed with documentation. I'm considering two ways of hosting the code:
Separate git repository with code files and markdown files explaining the code
Github gist containing both of these
Are there advantages of hosting in a gist v/s a repository? When would one prefer one of these over the other?
Gist is a simple way to share snippets and pastes with others.
Whereas Repo is simply a place where the history of your work is stored.
There is no good answer, it's personal preference. I make mine a conceptual distinction. If it's code designed to demonstrate a technique, teach a principle, or show off a solution it goes in a gist. Doesn't matter if it's one file or 30 files. If it's actual code intended to be run, used as is, or forked as boilerplate I put it in a proper repository.
If you use markdown files for your tutorial, now there is one important difference, even if you are only creating one file (and specially if it is a long one).
Since April 2021, .md files created in github repositories now include an automatic Table of Contents which greatly improves navegability. See this related SO answer for more info.
As far as I know, this automatic ToC does not exist in gist-created .md files, so I'd rather go for a repository in this case (OP mentioned "a lot of code interspersed with documentation").
Related
My github repo is not showing the language statistics [in the form of the bar under 'packages'] and the most used language. I've done some testing with the same files and it seems like Github's Linguist just starts to break after a couple of commits. I've also looked into problems that might arise with vendored code and stuff like that but it doesn't seem likely since all the files worked when I tested them individually. I just don't understand why it breaks and then doesn't work again.
Here's a link to the repo: https://github.com/arshb22/Virtual-Reality-and-Game-Design
It seems that your repo is filled with files that have extensions that Github doesn't recognize. If your files don't have extensions used by common programming languages, Github won't be able to label them since it doesn't know what they are.
When creating a GitHub Pull Request, it is often that a file (script, lib, etc.) may be completely replaced (or introduced) with one from another repo. Sometimes, the file requires small changes. I'm trying to establish a standard for my team for how to communicate where the file came from and what changed. In the same way that you can craft a URL to highlight a specific change in a single repo, I'd like to be able to highlight a change across repos.
The reality may very well be that GitHub does not offer this. (I do a lot of research before asking questions. Consequently, the answer is often, "you couldn't find an answer because it is impossible.") In which case an alternative will be needed. One possibility might be to generate a diff in markdown and add it as a comment. (Notice I improved that answer back in 2016.)
One possibility might be to generate a diff in markdown and add it as a comment.
Good idea.
One alternative which would not depend on a PR comment would be to use git notes. They are not supported/displayed by GitHub since 2014 and they are criticised, but they would remain in your case possible way to leave... well a note describing where some of the PR files are coming from.
What are the main functionality differences between Github Wiki and Readme,
Asking those that have used both readme and wikis extensively. So that we can better decide which to use for the purpose of outputing verbal information. This would be based on your answer. Thanks.
As examples, some have used wikis --
http://github.com/mbostock/d3/wiki
http://github.com/ParticleCore/Particle/wiki/Features
and some people have used readmes --
http://gist.github.com/atcuno/3425484ac5cce5298932
no better place to ask? -- meta.stackexchange.com/questions/157888/what-site-is-good-for-github-questions
Talking about a project repository :
Readme.md is the packaging
wiki pages is made for development/contributors documentation
gh-pages branch hosts user documentation
Both readme & wiki have no function, except for providing information. Github recommends you to create a README.md to display a short summary & usage of your repository, while the Wiki is totally optional.
I have to cross this bridge today, and in addition to this helpful thread I also found reading up the following helpful
https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
A key excerpt from there that I found useful and to the point
A README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis.
Based on those and the other answers here, it makes sense to be high level in the readme along with all the getting started information (i.e. local setup), and leave the long form information such as application features, design principles, etc. in the wiki.
Another major difference of course is that the readme will get versioned whereas the wiki will not. Versioning of this doc is not a major concern for us, but it could be for you!
In github, is it possible to show the diff of a single file between two commits?
One can readily diff two commits, and it is possible to link to the anchor for a specific file in those two commits, but all files are included in that view. For example, https://github.com/adamginsburg/APEX_CMZ_H2CO/compare/a94a962db51e0f4e73ec3ba4170a0ca8269548da...adamginsburg:master#diff-22
I would like a similar view, but without the other files.
(I know how to do this on the command line with git, but I want to share this link with collaborators, so the command line approach is not relevant for this question)
I think your question can be consider a duplicate of this one :
How can I generate a diff for a single file between two branches in github
Unfortunately, the accepted answer doens't answer your expected behavior.
I really tried to exclude the other files without success, and since there not seems to have other means to filter it out but html anchor pointer, I guess what you already have is what best available with Github to pin point the change you want to talk about with your peers.
I can recommend you to use Vscode with the Git History, I know is not the same as having in Github but it allows you to see the changes of the code according to an specific file or the entire project, comparing with the actual code, see all the changes of specific file through the commits, I work with this tool and this is helpful for me, hopefully it will be helpful for you.
Git History Example Usage
You can use the GitHub File Diff extension available for Chrome and Firefox.
Disclaimer: I made this extension.
Does the wiki that installs with a GitHub repo support directories? Our wiki is cluttered with pages, and we are looking for a way to organize them better.
We tried pulling the repo, creating local directories, and moving things around, but when committed back, the wiki didn't pick up the changes.
I was having the exact same issue and tried variants of what you tried. Nothing stuck. Asked GitHub support about it and received a reply that essentially said "No, but we'll let the developers know that people are interested in this feature."
So the short answer is "No", and the long answer is "No, but maybe in the future."
Actually, it looks like github added support for directories recently.
I was able to do the following:
Move an existing markdown file to a new directory.
Create a new markdown file in an existing directory (created in the former step).
Create a new markdown file in a new directory.
In all cases, the existing pages were still there and new pages were added.
The one constraint that remains is that your file names must be unique. If you have more than one file with the same name, only one of them will show up in the wiki (I'm not sure which.. ).
The GitHub wiki (aka Gollum) does use directories but not in the way you may expect.
The documentation on the Gollum wiki could use some work but this is what I have figured out mostly via testing.
All files appear in the root of the wiki no matter where they are placed in the repo.
_Header, _Footer and _Sidebar files are per-directory, but inherited if there is
none present in a child folder.
File links can be relative to the source file (keep your files with your content).
So, if you want directories for namespacing you are out of luck. Consider using the {namespace}-{page} scheme for namespacing.
It's not the an ideal solution but the workaround would be to create a custom sidebar where you create a table of contents with links to your pages. I find this to be better than folders anyway because it allows you to have a link to a single page under multiple hierarchies.
Actually, there is still a limitation. Yes, you can add 1 level (so, 1 subfolder). But that's it! I refactored my whole documentation layout, creating multiple levels of subfolders for organisation, but that was a no-go.
sigh
I must say: I'm appalled by this Gollum thing. I'm surprised Github even picked it up.
Well, that's a disappointing missing feature!
What I try to do is to actually have directories under a docs directory and in each one, a README.md file.
Not great...but works for documentation and organizes stuff.
If you want to go further, you can have a different branch only with these files.
Still no intention of adding this 9/2022.
https://github.com/orgs/community/discussions/23914