Git repo setup

[felixhayashi]

Hi @Spangenhelm

Hi @felixhayashi the repo has been created but i don't know how to create the needed files: do i need to use git on my system (linux) of can i create them online?

Good to know you are using linux (me too!) that makes it much easier for me to support you :)

I'll respond tomorrow.

-Felix

[felixhayashi]

Hi @Spangenhelm

You need to create a certain filestructure on github for tw projects which looks like this: https://github.com/danielo515/TW5-contextPlugin/issues/2#issuecomment-67993083.

So after you read some github basics on the internet do the following:

create a project folder on your filesystem and name it TW5-EnhancedSearchResults. Without going inside that folder, run the following commands to create and setup the repo (are you familiar with the linux bash shell?)

# create the dirs
mkdir -p ./TW5-EnhancedSearchResults/master
cd ./TW5-EnhancedSearchResults/master

# add git
git init

# configuration
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=7200'
git config --global push.default simple

# register aliases
git remote add origin https://github.com/Spangenhelm/TW5-EnhancedSearchResults

# fetch stuff
git fetch --all

# create local branch
git checkout -b master

# Do first commit
echo "TW5-EnhancedSearchResults" > ./README.md
git add .
git commit -m 'First commit'

# push changes
git push origin master

Now when inside the master folder (exactly at the root of the master dir), add a test file to the repo e.g. a file named test.txt where you say helloworld

Now run

# see changes (for your information)
git status

# commit all changes
git commit -a

# upload changes
git push origin master

Go to github.com and see the effect.

---

Everytime I do a pull request and you decide to accept it (merge the changes), you need to update your local repo on your filesystem:

# Fetches updates on your remote github repository
git fetch master
# Merges updates made online with your local work
git merge

See https://help.github.com/articles/fetching-a-remote/

[Spangenhelm]

Hi felix, i have done those first steps but i wonder if i shouldn't create a new branch of my tw fork instead of doing that, this way it would be able to easily modify and adapt the files already presents and even build a new tiddlywiki with them directly no? Otherwise i will need to update the demo's page manually and re-create each tiddler we want to change. I don't know what's best..

[felixhayashi]

Hi @Spangenhelm

if i shouldn't create a new branch of my tw fork instead of doing that

That would not be a good idea because a branch, its readme and its files are not visible to github repo visitors. A good plugin is a project on its own, has its own title, subtitle, description. Also, how sould users star your project, follow it or fork it without forking your whole wiki?

this way it would be able to easily modify and adapt the files already presents and even build a new tiddlywiki with them directly no?

This is also possible without working in a tiddlywiki fork. I recommend you create a dedicated folder for this project on your fs and develop the plugin with tiddlywiki in node js mode.

Have a look at the folder structure of tiddlymap, it's basically this:

# Folder that contains your branches
/some/path/TW5-YourProjectName

# Holds the checked-out master branch;
/path/to/your/TW5-YourProjectName/master

# contains all src files that are relevant when including your plugin via node.js
/path/to/your/TW5-YourProjectName/master/src/

# Always contains the checked-out gh-pages branch 
/path/to/your/TW5-YourProjectName/gh-pages

# the project website accessible via gitusername.github.com/TW5-YourProjectName
/path/to/your/TW5-YourProjectName/gh-pages/index.html

# This is where all the files for your demo wiki are placed under
/path/to/your/TW5-YourProjectName/gh-pages/src/

To build your wiki you can use a nodejs command like the one below...

interpreterPath="/path/to/your/tiddlywiki.js"
demoSrcRootPath="/path/to/your/TW5-YourProjectName/gh-pages/src/"
demoOutputPath="/path/to/your/TW5-YourProjectName/gh-pages/"

node $interpreterPath $demoSrcRootPath --verbose --output $demoOutputPath --build

Hope it helps

-Felix

[felixhayashi]

If you feel uncomfortable with performing the described setup yourself, just tell me and I'll do a pull request with all the files you just have to accept..

In any case, you should create a gh-pages branch where we can upload the demo site. This is much easier than hosting it on tiddlyspot because you can automatically commit and upload it with a git command and it is online

[felixhayashi]

The start with github is always confusing... I know. Take your time but in the end its worth it :)

[Spangenhelm]

..create a gh-pages branch where we can upload the demo site.

Done !

[Spangenhelm]

There are several things that i don't understand: I have created a git init in the master folder but i assume that i would need one in the gh-pages folder too no? otherwise how will i be able to push modifications to github??

I have tried to push the commit but it says that there are no "origin" folder, i don't know what this is

Thank you

[felixhayashi]

Done !

Nice!

I have created a git init in the master folder but i assume that i would need one in the gh-pages folder too no? otherwise how will i be able to push modifications to github??

Well spotted, that is very correct :) You need to run the exact same commands as I described them for the master branch (https://github.com/Spangenhelm/TW5-EnhancedSearchResults/issues/1#issuecomment-115859488) but this time for the gh-pages folder (see below). This will also solve the problem with the no "origin" folder because it will be added (git remote add origin https://github.com/Spangenhelm/TW5-EnhancedSearchResults). The "origin" is the remote repo (github) in contrast to your local repo on your filesystem.

# create the dirs
mkdir -p ./TW5-EnhancedSearchResults/gh-pages
cd ./TW5-EnhancedSearchResults/gh-pages

# add git
git init

# configuration
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=7200'
git config --global push.default simple

# register aliases
git remote add origin https://github.com/Spangenhelm/TW5-EnhancedSearchResults

# fetch stuff
git fetch --all

# create local branch
git checkout -b gh-pages

# Do first commit
echo "TW5-EnhancedSearchResults" > ./README.md
git add .
git commit -m 'First commit'

# push changes
git push origin gh-pages

[Spangenhelm]

All done sir ;-)

[felixhayashi]

Nice :) please wait, I'll do a commit with a few files.

[felixhayashi]

But first I need to modify the plugin that it doesn't override any tiddlywiki core stuff anymore. That might take a while. I'll ping back when I am done.

[felixhayashi]

Just wanted to say I am highly caught up in work at the moment so I hope you don't mind that this takes a little while. It is certainly on my todo list :)

-Felix

[Spangenhelm]

No problem take your time i'm not in a hurry

[felixhayashi]

Hi @Spangenhelm

sorry this is getting delayed. Our search-results project is important to me but there is much on my todo-list that I am not finding the time to work on this at the moment. Since you already developed a working solution I guess we are not really in a hurry but I just wanted to drop by to say that I have not forgotten about our quest for a better search! :)

-Felix

[Spangenhelm]

Yes i was wondering but since you have told me that you had a lot of work at the moment i was not worried ;-) Unfortunatly my programming level is too low to move forward without your help so i will wait no problem !

[Spangenhelm]

Also i was thinking of adding a link to my repo in the https://github.com/Jermolene/TiddlyWiki5/issues/1066 thread for those who would like to help (apparently like Sukima or maybe Daniello etc..) and i have added a github.io page (to host the demo there instead of on tiddlyspot), what do you think ?

[felixhayashi]

By mentioning https://github.com/Jermolene/TiddlyWiki5/issues/1066 you just did it :) But I think they already know about the repo though..

Anyhow, I'll work on this today. I don't feel good when unfinished business is always in my head...

[felixhayashi]

Ok so now I reworked the checker (now called searchManager) and I'll organize everything a bit. then create a pull request.

[felixhayashi]

Nice I managed to remove all code from $:/core/ui/SideBarLists so it is left untouched!

[felixhayashi]

Nice I managed to remove all code from $:/core/ui/SideBarLists so it is left untouched!

Have to revert that again. The way tiddlywiki determines titles for tab-states is really bad... gives me no chance but to insert our code into $:/core/ui/SideBarLists :( But whatever, the goal is to make this official anyways!

Going to sleep now hope I can finish it tomorrow

[Spangenhelm]

Ok, what about hosting the demo on a github.io page instead of tiddlyspot?

[felixhayashi]

Ok, what about hosting the demo on a github.io page instead of tiddlyspot?

yes, this is the plan :)

[felixhayashi]

Hi @Spangenhelm

I am done now. Please accept both pull requests.

(for a demo see: http://felixhayashi.github.io/TW5-EnhancedSearchResults/)

I organized the code a bit so please have a look at the files and ask questions if you need help.

!! After accepting my 2 pull requests

On your computer, make sure you have two folders, one for the gh-pages branch and the other for the master branch. So it looks like this:

The easiest way to achieve this.

Create a folder TW5-EnhancedSearchResults

Inside this folder execute:

git clone https://github.com/Spangenhelm/TW5-EnhancedSearchResults gh-pages
cd ./gh-pages
# configuration
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=7200'
git config --global push.default simple
# register aliases
git remote add origin https://github.com/Spangenhelm/TW5-EnhancedSearchResults
git checkout gh-pages

cd ..

git clone https://github.com/Spangenhelm/TW5-EnhancedSearchResults master
cd ./master
# configuration
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=7200'
git config --global push.default simple
# register aliases
git remote add origin https://github.com/Spangenhelm/TW5-EnhancedSearchResults
git checkout master

-Felix

[felixhayashi]

then I added helper scripts for you that allow you to start a nodejs tiddlywiki server locally and compile the demo page.

[Spangenhelm]

Hi @felixhayashi doesn't it feel strange to you that you are the one that does all the job but you have to wait for me to publish it?! I can't see the point and i feel bad because you waste your time explaining me how everything works..

[felixhayashi]

Hi @Spangenhelm

:) Well, its not like this.

First, everybody needs help setting up a GitHub-repo, it is quite complicated. I am just supporting you here and if other TW-users start a project, we can point to this repo as an example.

Second, I don't think you have to feel bad about anything since you do/did your part. You revived the discussion on the search-mechanism and made the first step to create a plugin, you also you set up a demo wiki. Now I made the next step and organized the files and started the GitHub thingy. If you feel that GitHub is too complicated, just tell me or add me as an adminstrator for this repo, that's not a problem. I just think it is better to support you so you can solve next issues alone than to take over your project.

But what is true is that I have only very little time at the moment, so things might need to wait if I cannot pick them up right away.

-Felix

[Spangenhelm]

Hi, i have added you as a collaborator, you should now have more permissions!

[felixhayashi]

Nice, thanks @Spangenhelm

[Spangenhelm]

Hi Felix i have added the plugin as a single .tid file in the "src" folder (did you forget it or was it on purpose?! strange..) i had to do so to build the index.html file with the command you gave me (which works great!) otherwise the plugin wasn't included of course !!

I have also modified the files a bit (like ignoring the helpers while syncing, updated the text of the "stand alone" mode now that there is just one version left etc..)

Thanks a lot for your help i'm starting to have fun ;-) +++

Edit: i have tried to ignore the helpers file by using the .gitignore file and this: helper* but it does not seem to work, any help? (there is no need to keep them synchronized)

[felixhayashi]

Hi @Spangenhelm

Thanks a lot for your help i'm starting to have fun

Glad you are starting to get accustomed to the process :)

i have added the plugin as a single .tid file in the "src" folder (did you forget it or was it on purpose?! strange..) Hi Felix i have added the plugin as a single .tid file in the "src" folder (did you forget it or was it on purpose?! strange..)

Yes, actually this is on purpose ;) Say you changed a file in master. Next to test it, you would go to the gh-pages folder execute the helper-publish and the helper-start-demo scripts.

They

1. install tiddlywiki in ./node_modules/tiddlywiki/
2. and then search for a dist directory in ../master/dist/
3. and then link this file to ./node_modules/tiddlywiki/plugins/spangenhelm/enhancedsearch.

They do this to include the plugin so you do not need to do this by adding a tid file...

updated the text of the "stand alone" mode now that there is just one version left etc..)

great :)

Edit: i have tried to ignore the helpers file by using the .gitignore file and this: helper* but it does not seem to work, any help? (there is no need to keep them synchronized)

Well, but then when I update a helper script you do not receive updates :) In a shared project, it is also important to synchronize such "meta-scripts".

I also saw that you changed the plugin path to FelixHayashi&Spangenhelm/EnhancedSearch/readme. This is kind of you but it is actually better to have a single authorname in small letters and the project name also in small letters. Why? this path is not for giving credits but as namespace and a namespace is short, alphanumeric (no "&") and lowercase. So actually it is better to use spangenhelm/enhancedsearch. Adding me as an author in the plugin.info or in the the demo description (what you both did) is the best way to do it ;)

Sorry for the corrections, all your intentions are very reasonable, it is just that there are some conventions for plugins... it also took me quite a while to understand all this, so don't worry.

-Felix

[Spangenhelm]

They do this to include the plugin so you do not need to do this by adding a tid file...

Wow i couldn't get it without explaination! it is complicated at first look.. So if we want to modify the plugin we should not use the nodejs tiddlywiki (otherwise it will save a .tid in the "src" folder, which is apparently not what we want, so we need to modify the file present in the "dist" folder right? then rebuild the index?)

but then when I update a helper script you do not receive updates :) To me they are not part of the plugin itself i was afraid they would be confusing for those interested by the project so i hate to see them here but you are right i will leave them.

Also there is a "dist" shortcut in "master" and i don't understand its role because it points to itself..

One last thing: can we use the tw in stand-alone mode to make little modifications or do we absolutly need to use the node version?

[felixhayashi]

Salut @Spangenhelm

So if we want to modify the plugin we should not use the nodejs tiddlywiki (otherwise it will save a .tid in the "src" folder, which is apparently not what we want, so we need to modify the file present in the "dist" folder right? then rebuild the index?)

yes, correct!

Why this is necessary:

1. It is much easier to program javascript when it is not in the tid format. So when working on the SearchTabManager.js the programmer has syntax highlighting etc. in contrast to when javascript is bundled as .tid.
2. People using node.js can include the project by referencing the dist folder in the tiddlywiki.info.

Also there is a "dist" shortcut in "master" and i don't understand its role because it points to itself..

We need this shortcut to include the script recursively so when loading... ehm.. no actually this dist shortcut makes no sense :) I don't know how it got there. Maybe it is a bug of the build-scripts. I'll have a look at it next time...

One last thing: can we use the tw in stand-alone mode to make little modifications or do we absolutly need to use the node version?

Unfortunately we cannot use the stand-alone when using the node version :( …Node.js is absolutely needed when developing javascript files (without it would be a nightmare).

-Felix

[tobibeer]

@felixhayashi: Trying to decipher the gist of all this, why does: https://github.com/Spangenhelm/Spangenhelm.github.io not show a TW5-EnhancedSearchResult folder? Where is that gh-pages folder synced to?

[felixhayashi]

Hi @tobibeer

why does: https://github.com/Spangenhelm/Spangenhelm.github.io not show a TW5-EnhancedSearchResult folder?

Why should it display this folder? It is only necessary that the gh-pages branch contains an index.html…

Where is that gh-pages folder synced to?

Have a look the helper script in the gh-pages branch https://github.com/Spangenhelm/TW5-EnhancedSearchResults/blob/gh-pages/helper-publish.sh#L25

This script pushes the build demo to gh-pages.

[tobibeer]

That's the part I don't understand...

Why should it display this folder? It is only necessary that the gh-pages branch contains an index.html…

How can github pages display anything that is not part of that repo? Why would it only need an index.html?

And related to that:

How would GitHub pages know of any other resources that are not part of that repo? ...in this case: the (virtual?!?) TW5-EnhancedSearchResult folder.

[felixhayashi]

Hi @tobibeer

How can github pages display anything that is not part of that repo? Why would it only need an index.html?

GitHub' gh-pages mechanism uses the files that are pushed into the gh-pages branch to serve them on request as html pages. All files that are placed in the gh-pages branch are accessible using http://USERNAME.github.io/PROJECTNAME/FILENAME So if I place a file index.html in the gh-pages of Spangenhelm/TW5-EnhancedSearchResults then it will be served as html by the github server at http://spangenhelm.github.io/TW5-EnhancedSearchResults/index.html automatically.

How would GitHub pages know of any other resources that are not part of that repo? ...in this case: the (virtual?!?) TW5-EnhancedSearchResult folder.

Ehm, this question I did not understand.

[tobibeer]

I think I haven't yet studied how GitHub pages work on a per-repo basis. I'm currently only using per-my-user.

[felixhayashi]

I think I haven't yet studied how GitHub pages work on a per-repo basis. I'm currently only using per-my-user.

Yeah, that probably caused the confusion ;)